Get started with GraphQL

GraphQL is an open source data query and manipulation language that provides declarative schema definitions and a composable query syntax. By design, GraphQL eliminates over- and under-fetching of relational data, which minimizes network and memory use for clients.

Resources

This tutorial, and other GraphQL topics covered within this documentation, provides details of the FaunaDB GraphQL API. For more general information about GraphQL, training, or the specification itself, see these resources:

To learn more about the FaunaDB GraphQL API, see the GraphQL reference, which includes details on the API’s endpoints, directives, input types, relations, and user-defined functions.

GraphQL tutorial

This tutorial assumes that you have completed the Quick start with FaunaDB tutorial.

This tutorial demonstrates how to get started with GraphQL, including designing an initial schema, importing that schema into FaunaDB, adding a few records, and then running a GraphQL query to retrieve those records. Start to finish, these steps should only take a few minutes to complete.

The steps:

  1. Log in to FaunaDB

    Visit https://dashboard.fauna.com/ in your web browser, and log in.

    The FaunaDB dashboard

  2. Create a GraphQL database

    Let’s create a new database to hold our GraphQL data. Any database would work, but this keeps your GraphQL experiments separate.

    Click New Database, enter graphql into the Database Name field, and press Return (or click SAVE).

    The new graphql database

  3. Create a GraphQL schema

    A GraphQL schema defines the "shape" of the data that can be managed and queried, including all of the fields and their types. We are going to start with a very basic schema for a "todo" list, where each todo item is just a title and a flag to indicate whether the item is complete or not. The schema also defines the kinds of queries that we want to run.

    Create a file called schema.gql containing the following content (or download it here):

    type Todo {
   title: String!
   completed: Boolean
}

type Query {
   allTodos: [Todo!]
   todosByCompletedFlag(completed: Boolean!): [Todo!]
}

  4. Import the GraphQL schema

    Before we can perform any GraphQL queries, we need to import the schema into FaunaDB. Once we do so, the FaunaDB GraphQL API automatically creates the necessary classes and indexes to support the schema.

    Click GRAPHQL in the left sidebar.

    The Import your <mark>GraphQL</mark> schema page

    Click IMPORT SCHEMA, which opens your browser’s file selector. Select the schema.gql file, and click the file selector’s Open button. The GraphQL Playground screen is displayed:

    The <mark>GraphQL</mark> Playground screen

  5. Create a record

    Even though our schema has been imported, there are no records yet. Let’s create one. Copy the following GraphQL mutation query into the left panel of the GraphQL Playground screen:

    mutation CreateATodo {
   createTodo(data: {
   title: "Build an awesome app!"
   completed: false
   }) {
       title
       completed
   }
}

    Then click the "Play" button (the circle with the right-facing triangle). The query should execute and the response should appear in the right panel:

    {
  "data": {
    "createTodo": {
      "title": "Build an awesome app!",
      "completed": false
    }
  }
}

    The GraphQL Playground screen should now look like this:

    Created a record in <mark>GraphQL</mark> Playground

  6. Fetch all records

    Now that we have a record that can be fetched, let’s run a query to fetch all records. Copy the following GraphQL fetch query:

    query FindAllTodos {
  allTodos {
    data {
      _id
      title
      completed
    }
  }
}

    Then click the "new tab" + button in the GraphQL Playground screen (at the top left, just right of the CreateATodo tab). Then paste the query into the left panel, and click the "Play" button. The query should execute and the response should appear in the right panel:

    {
  "data": {
    "allTodos": {
      "data": [
        {
          "_id": "235276560024732167",
          "title": "Build an awesome app!",
          "completed": false
        }
      ]
    }
  }
}

    GraphQL Playground should now look like this:

    Creating a record in <mark>GraphQL</mark> Playground

Conclusion

You have now seen how to prepare FaunaDB for GraphQL queries, how to create and import a GraphQL schema, how to use the GraphQL Playground screen to create and query data. You are now ready to continue your GraphQL journey!

Next steps

Was this article helpful?

We're sorry to hear that.
Tell us how we can improve! documentation@fauna.com

Thank you for your feedback!