Progress to Acquire MarkLogic - Learn More
BLOG ARTICLE

Introduction to GraphQL with MarkLogic

Back to blog
01.17.2023
4 minute read
Back to blog
01.17.2023
4 minute read

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.

sample query - mortgages

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.

screenshot of GraphQL plug-in for Grafana

— 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.

screenshot of GraphQL powered mortgage dashboard - edit panel

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.

screenshot of GraphQL powered mortgage dashboard

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.

Drew Wanczowski

Drew Wanczowski is a Principal Solutions Engineer at MarkLogic in North America. He has worked on leading industry solutions in Media & Entertainment, Publishing, and Research. His primary specialties surround Content Management, Metadata Standards, and Search Applications.

Read more by this author

Share this article

Read More

Related Posts

Like what you just read, here are a few more articles for you to check out or you can visit our blog overview page to see more.

Developer Insights

Multi-Model Search using Semantics and Optic API

The MarkLogic Optic API makes your searches smarter by incorporating semantic information about the world around you and this tutorial shows you just how to do it.

All Blog Articles
Developer Insights

Create Custom Steps Without Writing Code with Pipes

Are you someone who’s more comfortable working in Graphical User Interface (GUI) than writing code? Do you want to have a visual representation of your data transformation pipelines? What if there was a way to empower users to visually enrich content and drive data pipelines without writing code? With the community tool Pipes for MarkLogic […]

All Blog Articles
Developer Insights

Part 3: What’s New with JavaScript in MarkLogic 10?

Rest and Spread Properties in MarkLogic 10 In this last blog of the series, we’ll review over the new object rest and spread properties in MarkLogic 10. As mentioned previously, other newly introduced features of MarkLogic 10 include: The addition of JavaScript Modules, also known as MJS (discussed in detail in the first blog in this […]

All Blog Articles

Sign up for a Demo

Don’t waste time stitching together components. MarkLogic combines the power of a multi-model database, search, and semantic AI technology in a single platform with mastering, metadata management, government-grade security and more.

Request a Demo