GraphQL reference

GraphQL reference

This section provides reference information for the Fauna GraphQL API.

End of GraphQL development notice

As you probably know, we recently released a major new update to Fauna’s database language that provides a familiar, TypeScript-inspired interface into the database. We have received very strong positive feedback from customers on the new FQL as being much more intuitive and powerful than previous versions of FQL or the GraphQL interface.

In addition, we have seen a drop in query volume with our GraphQL API and have had some customers confuse this API with the functionality available from broader GraphQL server products such as Apollo, Grafbase, or Hasura.

As a result, we have decided to end development of our GraphQL API and instead focus on continuing to evolve FQL and integrate with best-in-class GraphQL providers.

In ending development of the GraphQL API, we will continue to support the API by fixing bugs and adding security patches. No new features or functionality will be added to the service. The API endpoints and service will remain available until February 29th, 2024.

Where do I migrate to?

There are two migration options:

We highly recommend following the Learn path of our documentation to become familiar with FQL and its capabilities and make an informed decision. As mentioned above, Fauna v10 natively provides a superset of the GraphQL API capabilities, including a declarative schema, easy-to-understand query language, and static type checking.

Migrate to FQL v10

Using Fauna Schema Language

Pushing SDL files through Fauna’s GraphQL API has been used by some customers as a means to manage their database schema declaratively. In migrating off the GraphQL API, you will instead use FSL to manage the database schema directly. You may use the Fauna Shell CLI to manage your database schema by downloading and uploading .fsl files. In fact, as a best practice, we recommend that you manage these .fsl files in a code repository and apply the same DevOps principles you currently use for application code to your schema.

Using the Fauna Drivers

Application clients can interact with the Fauna HTTP API directly. However, we recommend using the Fauna v10 drivers for most use cases. This is because Fauna supports complex types, such as Date, and Reference types, which are beyond the set supported by pure JSON. The Fauna drivers serialize and de-serialize these types for you, and you will need to handle these types yourself if you interact using the API directly. In-depth details on the configuration and use of the drivers are beyond the scope of this guide, but detailed documentation for each of the drivers is available here in their respective project pages.

Considerations

Object Types plus Field-level Enforcement

FQL is a statically typed language and will perform type checking on scalar types at compile time. Complex type checking, where type checking includes object types with field level definition, will be a feature of Schema Enforcement.

Embedded Types

Use of the @embedded directive of an SDL enables users to define a named type, which exists only as an object nested in another parent type. Embedded types are not persisted into a collection of their own but are instead persisted as a field of some other type which is stored in a collection of their own. At the time of GA, named embedded types were not yet supported in FSL. These types will be implemented as part of a feature of schema enforcement.

Legacy Indexes and UDFs

As you may be aware, when you upload an SDL using Fauna’s GraphQL API, Fauna creates native schema elements in your database necessary to support the SDL. You can refer to our documentation for details on how the GraphQL API adjusts your schema during import. Indexes and functions created by this SDL import process are not yet presented in FSL, as FSL currently only supports v10 elements. However, FSL support for these legacy elements is coming soon. These elements can be managed directly with the imperative commands of FQL v4.

Integrate Fauna with a GraphQL server

To continue to use Fauna with GraphQL, you will need to use a GraphQL middleware layer, such as Apollo, Grafbase, or Hasura, which would sit ahead of Fauna, replacing the end-of-life Fauna GraphQL API. Your application clients would make their API requests to this middleware layer instead of the Fauna GraphQL API.

Managing schema in Fauna

The first step in using Fauna with a GraphQL service is to use the new Fauna Schema Language (FSL) to define and manage your database schemas. FSL is an easy and intuitive language specifically designed to fully define your database. Collections, indexes, user-defined functions, and ABAC roles and access providers can all be expressed in .fsl files that you can track in code repositories. Your existing GraphQL schema will still be used to define the API your client applications connect to, but you will now use FSL to define your database schema. More detail on FSL and how to use it is available in our documentation.

Connecting to Fauna from your GraphQL server

Regardless of the service you choose to serve your GraphQL APL, you can use the same graphQL schema you had been importing to Fauna’s schema endpoint to configure these services. You may be aware that the Fauna API auto-generated a limited set of resolvers when you imported a GraphQL schema. In using a GraphQL service, you will need to define the resolver functions that query Fauna to get the data needed to fulfill the GraphQL API. You define resolvers for each of the query and mutation types defined in your GraphQL schema. You’ll use the Fauna driver in the resolver code to connect and send queries to Fauna.

Apollo quick start example

The following code snippet, which is intentionally similar to the Apollo quick start guide, is a simple example of how you would use Apollo and define basic resolvers to connect to the Fauna server using a simple GraphQL API.

import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';
import { Client, fql, type Page } from "fauna";

// Declare the Fauna client
const client = new Client({
  secret: "YOUR FAUNA SECRET"
});

type Customer = {
  firstName: string;
  lastName: string;
  email: string;
};

// Define the GraphQL schema
const typeDefs = `#graphql
  # Define the "customers" type.
  type customers {
    firstName: String
    lastName: String
    email: String
  }

  # This "Query" lists all the queries
  # The "customer" query returns an array of customers
  type Query {
    customers: [customers]
  }
`;

// define your resolvers
const resolvers = {
  Query: {
    customers: async () => {
      const response = await client.query<Page<Customer>>( fql`customers.all()` )
      return response.data.data
    }
  }
};

// define the server
const server = new ApolloServer({
  typeDefs,
  resolvers,
});

// Create ApolloServer
const { url } = await startStandaloneServer(server, {
  listen: { port: 4000 },
});

console.log(`🚀  Server ready at: ${url}`);

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!