Gentics Mesh is also able to process GraphQL queries. You can use GraphQL to directly specify what fields should be retrieved and retrieve deeply nested data sets. Internally, Gentics Mesh will resolve your query and traverse your content graph to fetch only the data you specified.
The GraphQL API can thus be used to prepare a single request which returns all data needed to render a specific page.
Possible use cases are:
Loading multiple nodes using the webroot path.
Generating a custom navigation which only includes the information you need.
Invoking multiple search requests to find a set of specific nodes.
Resolve links within the content of a node.
Load users, roles, groups
Load tags, tag families, schema and microschema information
If you want to learn more about the GraphQL syntax take a look at the good documentation.
Nodes can be linked together in various way. One way is the regular parent-child relationship. Another way is by using node fields. The demo data contains vehicles which each is linked to a vehicle image. In order to present the vehicle we also need to retrieve the image path and other information.
The search query is an escaped JSON object which represents the a regular Elasticsearch query.
Similar to the REST API a value based pagination system is implemented.
The node will automatically be loaded in the language which matches up with the provided webroot path. A webroot path which points to an english node will yield the english content. Subsequent loading a node using the german path will yield the german content. It is important to node that Gentics Mesh tries to stick to a language as much as possible. Loading additional referenced nodes of an german node via either the children or a node field will return the german content if such content could be found. The fallback to the configured default language will be applied if no other matching content found be found. Null will be returned if this also fails.
It is possible to load a found node in a different language using the
node field as shown in the example.
Any time a node list is requested, you can provide a filter object as a parameter to narrow down the result.
Here are a few examples:
SchemaFilter matches nodes with a specific schema name.
StringFilter offers various ways to filter strings. One example is regular expressions.
In this example we get all nodes with the schema
vehicle. We check if their name field ends with a number.
Combine multiple filters to further narrow down your results. One example is the
We get the same nodes as in the previous example. Additionally we also get all vehicles that have a price lower than 200.000.
When filtering by fields of a node, it is currently only possible to filter by fields of the following types:
A note on GraphiQLEdit the above examples and experiment with the API. Use the GraphiQL autocompletion (press
Try it in your own installationYour instance of Gentics Mesh comes with the GraphiQL Browser as well.
Many tasks can be done by both the search and the filtering feature. Here are a few tips that help you decide which technology is suited best for your needs:
GraphQL filtering is independent of Elasticsearch. If you don’t want to use Elasticsearch, GraphQL filtering is still available.
GraphQL filtering is faster when dealing with small datasets. There is less overhead compared to Elasticsearch. GraphQL filtering iterates over the source set of elements and applies the filter until enough nodes have been found for the response.
Elasticsearch is faster when dealing with large datasets, because it uses an index to access its documents.
Elasticsearch is better suited for full text search queries from an end user because you can precisely tune the index to your requirements.
Try the exampleLive Demo
Alternatively, you can download Gentics Mesh and test the API locally.
Once authenticated you can access the interactive GraphiQL browser at
The GraphiQL browser currently does not support the
At the moment, the GraphQL API can currently only be used for read-only operations. Modifying data with via mutations is currently not supported.
GraphQL queries are restricted to a specific project. It is not possible to query data across multiple projects.
GraphQL queries are restricted to a specific project branch. The scope of the branch can be changed by adding the
?branch query parameter.