GraphQL schema

London Dev Meetup Rescheduled! Due to unavoidable reasons, the event has been moved to 21st May. Speakers remain the same—any changes will be communicated. Seats are limited—register here to secure your spot!

How it works

The GraphQL schema describes the functionality available to the client applications that connect to it. The GraphQL server uses the schema to describe the shape of the data graph, defining a hierarchy of types with fields that are populated from the back-end data store. The schema also specifies exactly which queries and mutations are available for clients to execute against the data graph.

Accessing the schema

The generated GraphQL schema can be found by accessing the API Gateway together with your public key, as described in Getting started. The GraphQL schema can also be accessed from the CMS UI.

Methods and parameters

The GraphQL schema contains one method per content type, and each method contains several parameters. Each method has a return type that matches the properties for the content type. This makes it possible to select which content type properties to return in the result.

Field names, reserved fields and characters

The GraphQL schemas contain regular field names of content, reserved field names, input arguments, enumerated values and reserved characters. Names prefixed with underscore are reserved for special system fields and we highly discourage the use of field names in the names of the regular content fields.

The (naming) convention for these parts of a schema is as follow:

Content field names (regular): it follows the convention as-is, so as specified in the content model. For example, if the model is serialized as Pascal case, the fields will also appear as Pascal case in the GraphQL schema. These fields appear in the Input and Output types.

Schema type: name of the schema, which is in Pascal case.

Reserved field names: these are reserved field names starting with an underscore prefix that allow special functionality. Examples:

_fulltext is a concatenation of the values of all searchable fields
_children is a special field that allows embedding a method for a content type within a parent content type.
_ranking allows ordering the results by a relevance score, internal document ID or other special metrics.
_modified is a date field that indicates when the content was ingested.
_or, _and, _not are used for expressing Boolean logic in queries.

System query fields: added to the field types for using matching & retrieval functions, or special projection are in snake case.

Root level fields: these are root level fields which are in snake case. Examples:

items is the root level for projecting the actual results.
total shows the hit count, i.e. the number of matching results given the query.
facets projects the aggregated values of a field, including matching hit count. These values can then be used for filtering.
cursor shows the value that can be used to do pagination with a cursor.

Input arguments: names of arguments in a method which are following the snake case convention.

Enumerated values: these are fixed values in uppercase and snake case belonging to input arguments or reserved fields. Example:

the reserved field _ranking has the values RELEVANCE and DOC.
locale argument has different language codes like EN, SV, FR, etc.

Reserved characters are part of the GraphQL syntax and need to be escaped with a single backslash for querying. These characters are double quote and backslash.

Example query with regular projection

Example query with facets