Schema previews

The Fauna GraphQL API uses an approach called "Schema previews", which gives you early, opt-in access to new or incomplete features. This approach lets you test features which will be available to production GraphQL queries in the future, which lets you develop your GraphQL queries with confidence.

Schema previews represent functionality changes to the GraphQL API. All such changes will be made in an additive way. Whenever fields require changes, they will be marked as deprecated but otherwise continue to function as normal. New fields supporting the new/revised functionality are added. This approach should eliminate changes that could break your queries.

Schema previews are opt-in, and are enabled per query:

  • When a schema preview provides some dynamic feature, such as a new query or mutation, a new dynamic type, etc., the schema preview needs to be enabled while executing queries via the /graphql endpoint.

  • When a schema preview provides new schema capabilities, such as a new directive, types, scalars, etc., the schema preview needs to be enabled while merging or overriding a schema via the /import endpoint.

This section describes the Current schema previews, the Retired schema previews, and how to Enable schema previews.

Current schema previews

Name Description

partial-update-mutation

Auto-generates an input type where all fields are optional, and auto-generates a mutation that validates any required fields at runtime.

Retired schema previews

This section describes schema previews that are no longer available as a preview, since their functionality has been integrated with normal, production schema processing.

Name Description

none so far
If you enable a schema feature that is no longer in preview, but is now in production, your request does not fail: the specified feature just works.

Enable schema previews

To access schema features that are in preview, your queries must include a custom HTTP header: X-Schema-Preview.

To enable a feature, specify its code in the header:

X-Schema-Preview: partial-update-mutation

To enable multiple features, express the feature codes as a comma-separated list:

X-Schema-Preview: partial-update-mutation, another-feature

In Dashboard’s GraphQL screen, you can add this header by clicking the HTTP Headers button in the lower left.

Once a preview feature has moved out of preview and into production, the code is marked as "retired": the feature it represents is available for general use, and your query should continue to succeed even though the code is no longer required.

If you provide an invalid feature code, your query fails with an invalid code error.

Is this article helpful? 

Tell Fauna how the article can be improved:
 Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!