GraphQL reference

GraphQL reference

This section provides reference information for the Fauna GraphQL API.

You can find step-by-step GraphQL tutorials in the Tutorials section.

Supported scalar types

The GraphQL API supports the following built-in types:

  • Boolean: A value that represents true or false.

  • Date: A date value. The GraphQL API communicates and renders these as strings in the format yyyy-MM-dd, but they are stored as FQL dates.

  • Float: A 64-bit floating point number.

  • ID: A string representing a generic identifier. Compared to the String type, an ID is not intended to be human-readable.

    If the field specification in your schema includes the @unique directive, the identifier must be unique within the current type.

    Fauna provides a unique identifier for a document via the _id field, which represents the document’s reference. You would typically use the ID type for documents that have an externally-created identifier, such as documents imported from another database).

  • Int: A 32-bit signed decimal integer number.

  • Long: A 64-bit signed decimal integer number.

  • String: A string of UTF-8 characters.

  • Time: A timestamp value. The GraphQL API communicates and renders these as strings in the format yyyy-MM-ddTHH:mm:ss.SSSZ, but they are stored as FQL timestamps.

    Fauna provides a document’s most recent modification timestamp via the _ts field, which has microsecond resolution.


For more general information about GraphQL, training, or the specification itself, see these resources:

There are a few online, interactive GraphQL interfaces. The one we recommend is GraphQL Playground. It is embedded into Fauna Console.

For developers, the Fauna GraphQL API should work with most GraphQL libraries. See the next section for known limitations.


The Fauna GraphQL API is in its initial release. It is functional, and can handle most GraphQL workloads. However, there are some GraphQL features that are currently not supported:

  • Schemas do not support:

    • Custom directives

    • Custom interfaces

    • Custom scalars

    • Union types

  • No name can start with an underscore (_)

  • Subscriptions are not supported.

Also, Fauna GraphQL API can only work with the defined schema. Any existing collections, indexes, or functions that may exist in a database, that are not referenced in the GraphQL schema, are unavailable to GraphQL queries.

Is this article helpful? 

Tell Fauna how the article can be improved:
Visit Fauna's forums or email

Thank you for your feedback!