Introduction to GraphQL with MarkLogic

MarkLogic 11 introduces support for GraphQL queries that run against views in your MarkLogic database. Customers interested in or already using GraphQL can now securely query MarkLogic via this increasingly popular query language.

What Is GraphQL?

GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.

— https://graphql.org/

Using GraphQL with MarkLogic Views

MarkLogic supports views of multi-model data that can be queried with SQL, Optic API, and now GraphQL. MarkLogic requires a View for a GraphQL query to be executed. MarkLogic defines two types of views: Indexed Views and Query Based Views. Indexed views are achieved by using Template Driven Extraction (TDE).

Template Driven Extraction (TDE) populates view indexes when documents are written to the database. These views are transactionally consistent with the records being stored in the database.

—To learn more about TDE, see https://docs.marklogic.com/guide/app-dev/TDE

Query Based Views (QBV) are views that are evaluated during query time. These views are saved queries written in MarkLogic’s Optic API. You can write robust queries that target multiple models.

—To learn more about Optic API and Query Based Views, see https://docs.marklogic.com/guide/app-dev/OpticAPI

Writing GraphQL Queries

When constructing GraphQL queries, it is important to understand the anatomy of the query. GraphQL queries will be translated internally and executed by the MarkLogic Optic API. This will allow for rich querying across data in any shape or size.

Below is a sample query looking for information about Mortgages. To better understand the full syntax supported by GraphQL, see https://graphql.org/learn/queries/. However, we will walk through this example to understand its structure.

Operation Type and Name – MarkLogic supports querying with GraphQL. The example demonstrates the “query” operation type and an operation name “MortgageQuery”. Specifying the operation type and name makes the code less ambiguous and allows the reader to quickly determine the intention of the query.

Schemas and Types – GraphQL supports the ability to query data by specifying an object type and a list of fields. In MarkLogic, the object type maps to Schema and View by naming the object type using the pattern “Schema_View”. So, in the example above, the Mortgage_Details object type maps to the Details view in the Mortgage schema.

Filtering – GraphQL also allows you to limit the data being queried by specifying the fields and the matching values. In this example, we are looking for mortgages that have a “LoanType” with the value “Conventional”.

Pagination – We can also specify the number of results and how many items to skip by specifying the “first” and “offset” fields in our filter.

Sorting – GraphQL @Sort allows you to specify fields and directions to use as a sorting mechanism. In this example, we are using the mortgage end date as the field and sorting descending.

Field Selection – While your view may have many columns, you will specify what data you want to retrieve by enumerating the fields.

Submitting GraphQL Queries

MarkLogic provides several out-of-the-box APIs for interacting with View data. The /v1/rows endpoint allows you to pull View data utilizing any of the several supported query languages. The /v1/rows/graphql endpoint allows you to send over queries utilizing GraphQL syntax. This REST endpoint can be leveraged by simple utilities like cURL or by more advanced tooling.

Example cURL using a GraphQL query saved in a file:

curl --location --request POST 
'http://localhost:8000/v1/rows/graphql' \
--header 'Content-Type: application/graphql' \
--data '@query.graphql'

Visualizing GraphQL Results

Many data visualization solutions support GraphQL endpoints as a data source. The example below shows how Grafana, a popular observability platform, can submit GraphQL queries to MarkLogic and visualize the results.

To get started, you will require a GraphQL Plug-in for Grafana. There are a few plug-ins available in their marketplace. Once the plug-in is installed, you can connect to the /v1/rows/graphql endpoint available with MarkLogic.

— GraphQL Plugin : https://grafana.com/grafana/plugins/fifemon-graphql-datasource/

Once your Data Source is configured, you can now add Panels using the GraphQL data source. In this example, we are pulling metadata for all the mortgages into a tablature view. You can configure a multitude of visualizations such as graphs, charts, and maps.

This full dashboard utilizes a live connection to MarkLogic Server, making multiple GraphQL queries to populate all the information quickly and effectively. We can see that we are leveraging multi-model data such as Document Views, Graph Views for Householding, and Geospatial.

Conclusion

GraphQL provides a standardized query language for your modern APIs. And with MarkLogic’s support for GraphQL, it provides another opportunity to integrate rich multi-model datasets within the ever-growing enterprise.

To learn more about the MarkLogic GraphQL query service, see the GraphQL new feature update in the MarkLogic 11 release notes.