Skip to main content

What's New in MarkLogic 11

GraphQL

MarkLogic 11 provides a GraphQL query service with out-of-the-box support for querying user-defined views. Those views may be defined via Template Driven Extraction or Query-Based Views. Additionally, the views and the relationships between the views may be augmented based on a custom GraphQL schema. This service is accessible by sending a JSON object with a "query" property containing a GraphQL query string to the /v1/rows/graphql REST endpoint using either an HTTP GET or HTTP POST request. Those requests must set the Content-Type header to "application/graphql".

Features

The GraphQL query service supports the following features:

Feature

Description

View Arguments

This version supports arguments for specifying a value to filter a column on. See https://graphql.org/learn/queries/#arguments.

Range Directives

These are a set of directives (ie. @greaterThan) that may be used to specify a range filter for a column.

Sort Directive

This directive allows for specifying a sort column and a direction for the resulting records.

Pagination Arguments

The "first" and "offset" arguments allow for pagination. These arguments should only be used in the root view of a query.

Implicit GraphQL Schemas

Implicit GraphQL schemas are generated by MarkLogic at request time to reflect the user-defined views available in the database.

Explicit GraphQL Schemas

These user-defined schemas are used to augment or customize the default schema.

Join Directive

This directive is used in explicit schemas to relate two views and to define the join columns for that relationship.

ID Directive

This directive is used in explicit schemas to define the primary key column for a view. That primary key column is then used for object grouping in the JSON responses.

View & Field Aliases

Aliases may be used to rename views and columns in the resulting JSON objects. See https://graphql.org/learn/queries/#aliases.

Multiple Queries in a single operation

A single query operation may contain multiple queries. The results are included in a single JSON response object.

REST APIs

The following REST APIs are available in MarkLogic 11:

API

Description

/REST/POST/v1/rows/graphql

Executes a GraphQL query in order to retrieve a JSON object with the results. The query is passed in the "query" property of the JSON request body.

/REST/GET/v1/rows/graphql

Executes a GraphQL query in order to retrieve a JSON object with the results. The query parameter of the GET URL should be JSON containing a "query" property.

GraphQL Schemas

Implicit GraphQL schemas are automatically generated by MarkLogic during request processing to reflect the user-defined views available in the database. They define the default queries and data types that are available to users of the service and are user-specific.

Explicit GraphQL schemas are created by a MarkLogic administrator in order to augment or customize the implicit GraphQL schema. They can be used for defining joins and/or limiting columns available in views. While processing a request, if an explicit GraphQL schema has been defined and the GraphQL service has been configured to use that schema, then the service merges the implicit GraphQL schema with the explicit GraphQL schema. Any types or queries that are defined in both schemas are overwritten with the version in the explicit schema.

Limitations

This initial version of the GraphQL service is focused on basic query handling. As such, non-query operations and some optional query features are not yet available.

  • Mutations - Users will not be able to send updates to the database via GraphQL.

  • Subscriptions - Users will not be able to subscribe to queries for receiving data pushes from the server.

  • Introspection - Users will not be able to request schema information from the server using GraphQL. However, it is possible to get schema information using QConsole.

  • Multi-Operation Requests - The service will only provide a response to the first query operation in a request. Any additional query operations will be ignored.

  • Skip Directive - Users will not be able to use this directive to specify columns to exclude under specific conditions.

  • Include Directive - Users will not be able use this directive to specify columns to include under specific conditions.

  • Variables - Users will not be able to define or use variables in queries.

  • Fragment - Users will not be able to define or use fragments of queries.

  • Custom Grouping and Aggregation - Users will not be able to set custom grouping or aggregations as part of a query. However, a work-around is to implement a query-based view with the desired grouping and aggregation in the MarkLogic server and use that query.

  • Custom Resolvers - Users will not be able to customize how views and columns are resolved.

Known Issues

  • Using the "limit" or "offset" arguments on joined views does not work as expected for GraphQL. The pagination takes place for the entire joined view; therefore, the result set may not have all the expected data for the joined view.

  • Joins can lead to very large result sets. Pagination on the root view only affects the number of root view objects returned. Therefore, those root view objects may have a very large number of child objects. 

  • Empty object arrays in 3rd-tier joins have single objects with null values. It is recommended that the user check child objects for null values.

In this section: