Optimizely Graph schema
GraphQL is a query language that lets clients request only the fields they need. GraphQL is a query language that lets clients request only the fields they need. Optimizely Graph uses a GraphQL schema to describe the shape of the data available to client applications that call the service. The schema defines a hierarchy of types and fields from the back-end data store and specifies which queries and mutations are available against the data graph.
Optimizely Graph generates a unique schema for every site that syncs its data to the service. The shape of the data depends on how the content types are defined in the site's configuration. Exploring the uniquely generated schema for your site is essential to build query-driven applications with Optimizely Graph.
Access the schema
Locate the generated GraphQL schema in your Optimizely Graph environment so you can inspect the types and fields available to your queries.
Go to the API Gateway page in your Optimizely Graph environment and authenticate with your public key to find the generated GraphQL schema. See Get started with the GraphQL API. You can also use the GraphQL UI to access the GraphQL schema.
Methods and parameters
Each content type in the schema is exposed as one method with its own return type, so a single query can request exactly the properties relevant to that type.
GraphQL schemas contain one method per content type, and each method contains several parameters. Each method has a return type that matches the properties of the content type. This lets you select which content type properties to return in the result.
Field names, reserved fields, and characters
Each schema uses naming conventions that signal what a field does and where it comes from. Understanding the conventions makes the schema easier to read and helps you avoid collisions with reserved names.
GraphQL schemas contain regular field names of content, reserved field names, input arguments, enumerated values, and reserved characters.
Important Reserved fields in Optimizely Graph start with an underscore (_) and are used by the system. Do not use fields prefixed with underscores in your domain models. The system cannot guarantee all the query and search capabilities to work correctly for any field starting with an underscore.
The naming convention for these parts of a schema is as follows:
- Field names (regular) follow the site's content delivery model conventions. For example, if the model is serialized as Pascal case, the fields also display as Pascal case in the GraphQL schema. These fields display in the Input and Output types. The schema type or name of the schema is in Pascal case (PascalCase).
- Reserved field names start with an underscore prefix that permits special functionality. For example:
- _fulltext – A concatenation of the values of searchable fields to support full-text search.
- _link – A special field that embeds items of a content type within another item using a common value. See joins with linking.
- _score – The relevance ranking score, which is a number that shows how similar content is given the query, resulting in a ranked list of results.
- _id – The unique internal ID used by Graph for a content item.
- _metadata – All descendants within _metadata are special fields used by Optimizely CMS.
- _ranking – Orders results by a relevance score, internal document ID, or other special metrics.
- _modified – A date field that indicates when the content was ingested.
- _or, _and, and _not – Used for expressing Boolean logic in queries.
- Irregular reserved field names are fields that are tightly coupled with CMS (PaaS) (CMS 12.0 or earlier):
- ContentType
- Status
- StartPublish
- StopPublish
- Language.Name
- RolesWithReadAccess
- UsersWithReadAccess
- _rbac
Root-level fields are in camel case (camelCase):
- items – The root level for projecting the actual results.
- total – Shows the hit count or number of matching results the query gives.
- facets – Projects the aggregated field values, including matching hit count. These values can then be used for filtering.
- autocomplete – Shows autocomplete, word completion, type-ahead, or search-as-you-type suggestions in which an application predicts the rest of a word a user is typing.
- cursor – Shows the value that can be used for pagination with a cursor.
Input arguments are names of arguments in a method that follow snake case (snake_case) convention.
- Enumerated values are fixed values in uppercase (UPPERCASE) and snake case belonging to input arguments or reserved fields:
- The reserved field _ranking has values such as RELEVANCE, DOC, BOOST_ONLY, and SEMANTIC.
- An exception is the locale argument, which has different language codes like en, sv, fr, and so on.
- Reserved characters are part of the GraphQL syntax and must be escaped with a single backslash for querying. These characters are double quotes (\") and backslash (\\).
The following illustration summarizes these conventions hierarchically:
Reserved property names for CMS content types
Choose property names that avoid the built-in content properties of CMS 12 so every property you model stays queryable. When a property on a content type has a reserved name, Optimizely Graph leaves it out of the schema. Graph does not rename the property, so you cannot query it. The other properties of the content type sync as usual.
Do not use the following names for properties on content types that synchronize to Optimizely Graph:
- ContentLink
- Name
- Language
- ExistingLanguages
- MasterLanguage
- ContentType
- ParentLink
- RouteSegment
- Url
- Changed
- Created
- StartPublish
- StopPublish
- Saved
- Status
Graph also excludes properties named RolesWithReadAccess, UsersWithReadAccess, __typename, or _rbac, without a warning.
The Optimizely Graph full synchronization job reports each skipped property with a warning, such as 'Url' skipped for: ImageFile. To make a skipped property queryable, give it a different name in the content type and run the synchronization job again.