GraphQL¶
GraphDB also allows you to explore your data using GraphQL — a simple language for querying various data stores. It is based on a strong type system (schema language) that allows objects and query validation, query autocompletion, and query type checking in modern languages such as TypeScript. It is not a replacement for SPARQL as it does not allow arbitrary queries to be issued. Instead, GraphQL is intended to provide a simple facade over complex backend storage systems.
GraphQL queries have a regular hierarchical structure. Each level is serviced (resolved) in sequence, and lower levels cannot influence the results at a higher level. If you want to order or filter by lower-level data, you often need to access the same fields in the higher-level filter clause, and in the lower-level selection clause.
GraphQL security¶
Since using GraphQL assumes a more limited access to the data, the GraphDB security mechanism allows administrators to provide users with access only to the GraphQL environment, without enabling access to the RDF layer. In other words, administrators can create GraphQL-only users who won’t be able to use SPARQL, mirroring most real-life use cases of GraphQL.
In addition to the GraphQL-only security check controlled through the User Management screen, a more robust Role-Based Access Control (RBAC) mechanism is also available. Whenever a GraphQL query or mutation is invoked, the RBAC mechanism controls which information is returned and which data can be modified in case of a mutation. The mechanism uses Custom user roles.
See also
Migrating GraphQL configurations from Semantic Objects to GraphDB details the important details and steps when migrating from Semantic Objects to GraphDB 11.
GraphQL endpoints¶
Usage of GraphQL is done through GraphQL endpoints which provide API access to a repository’s data. The endpoint works through a generated GraphQL schema which specifies how the repository’s classes and properties are treated as GraphQL types and fields. When you create a GraphQL endpoint, you can have GraphDB generate the endpoint from the existing OWL ontologies and SHACL shapes, or use your own GraphQL SHACL Model.
Further down below you can find an example of generating a GraphQL endpoint from a SHACL shape.
See also
The GraphQL schemas and endpoint management documentation provides a thorough overview of the creation, management and usage of GraphQL endpoints.
Licensing GraphQL¶
Basic GraphQL support is available in all versions of GraphDB, but some advanced options require an additional GraphQL license:
Schema validation against data
GraphQL federation
Note
These restrictions apply on an operational level. Schema parsing, validation and loading will work fine even without a valid license. An operation (query or mutation) is stopped only upon execution and only if any of the advanced features are necessary for its execution.
See also
For more information on licensing options, check the Licensing documentation.
GraphQL Playground¶
The GraphDB Workbench comes with — an environment that allows query autocompletion. The GraphQL Playground is built on GraphiQL, a graphical in-browser GraphQL IDE. You can access this interface through in the Workbench menu.
To perform a GraphQL query, you must first select an available GraphQL endpoint from the available list of endpoints, found at the top right of the GraphQL Playground interface.
Once you have selected an endpoint from the drop-down menu, you will be able to write and perform GraphQL queries. You can also perform some additional operations:
Executes the query and displays the results in the tab to the right.
Automatically formats the GraphQL query, making it easier to read and and work with.
Merges fragments into query. This only works for in-line fragments.
Copies the query.
There are several other plugins available in the GraphQL Playground:
Opens the of your schema. This plugin allows you to browse and explore the schema and its types and fields. This is the default plugin found in GraphiQL, and has mostly been superseded by the , also available in the playground.
Opens the tab, which shows previously executed queries. You can mark previous queries as Favorite for quick access.
Opens the , an advanced view of the types and fields available in your schema which also allows you to directly construct queries through its interface.
Generating an endpoint from SHACL using the Star Wars dataset¶
This example uses data describing Star Wars movies, characters, planets and vehicles. It shows how to generate a GraphQL endpoint from SHACL shapes and use it to perform simple queries in the GraphQL Playground.
Prerequisites¶
Before you go through this example, download the starwars-data.ttl dataset and import it into a new repository called star-wars. Then import the swapi-shapes-ex1 shapes and import them into a named graph in the same repository.
Generate an endpoint from named graph¶
Once you have imported your data and connected to the star-wars repository:
Go to , then select
Select :
Under Endpoint ID, provide a unique name for the endpoint. This example uses star-wars.
Under Vocabulary prefix, select voc.
You can also provide a short .
Choose to move the graph from Available (not included) to Included for generation.
Click on
next to the name of your graph.Tip
Since the repository should contain only one named graph at this point, you can also click on instead.
Select to move to the next screen. For the purposes of this example, leave all configurations on that page at their default values.
Select , then .
Once GraphDB finishes creating the endpoint, you can either navigate to , or directly select the name of the repository to load it into the GraphQL Playground.
See also
GraphQL schemas and endpoint management explains the generation of endpoints in detail, including the generation of endpoints from GraphQL schemas.
Executing simple queries in the GraphQL Playground¶
Once you have created your endpoint, you can use it to explore your data using GraphQL queries. Navigate to , and make sure that the star-wars endpoint is selected from the top-down menu at the top right of the GraphQL Playground.
Note
You can explore the GraphQL schema through the and . Note that the types and their properties in your endpoint correspond to the SHACL shapes.
First, let’s get a list of all characters in Star Wars, ordered by height in descending order. Paste this query into the Query editor, then select to execute the query:
query charactersOrderedByHeight {
character(orderBy: {height: DESC}) {
gender
label {
value
}
id
height
}
}
This query should return a result that begins with:
{
"data": {
"character": [
{
"gender": "male",
"label": [
{
"value": "Yarael Poof"
}
],
"id": "https://swapi.co/resource/quermian/57",
"height": "264.0"
},
{
"gender": "male",
"label": [
{
"value": "Tarfful"
}
],
"id": "https://swapi.co/resource/wookiee/80",
"height": "234.0"
},
{
"gender": "male",
"label": [
{
"value": "Lama Su"
}
],
"id": "https://swapi.co/resource/kaminoan/72",
"height": "229.0"
},
...
However, the list of all characters in this repository is rather extensive. If you wish, you can instead query for a smaller set of characters — such as a query that will return only the characters that appear in Star Wars Episode IV: A New Hope, and limit the results to the first five characters:
query allCharactersInANewHope {
character(limit: 5, where: {film: {ID: "https://swapi.co/resource/film/1"}}) {
id
label {
value
}
}
}
Which should return the following:
{
"data": {
"character": [
{
"id": "https://swapi.co/resource/droid/2",
"label": [
{
"value": "C-3PO"
}
]
},
{
"id": "https://swapi.co/resource/droid/3",
"label": [
{
"value": "R2-D2"
}
]
},
{
"id": "https://swapi.co/resource/droid/8",
"label": [
{
"value": "R5-D4"
}
]
},
{
"id": "https://swapi.co/resource/wookiee/13",
"label": [
{
"value": "Chewbacca"
}
]
},
{
"id": "https://swapi.co/resource/rodian/15",
"label": [
{
"value": "Greedo"
}
]
}
]
}
}