GraphQL

This topic describes how Grafbase leverages GraphQL to define your data model.

GraphQL gives you the ability to define your data model in a straightforward schema. For example, you might want to track customers by ID, name, email address, or order(s); products by ID, SKU, name, price, currency, or inventory; and orders by ID, customer, or product(s). The GraphQL schema for that information might look like the following:

The exclamation mark (!) indicates that the field is required. The @model annotation means you want us to create APIs for instances of that data type.

A query to retrieve your customer names and the names of the products they ordered might look like:

Contrast that with a typical REST API sequence:

  1. Get the list of customers
  2. For each customer:
    1. Get the list of orders
    2. For each order:
      1. Get the list of products
      2. For each product:
        1. Get the product name

So at least (# customers) X (# orders/customer) X (# of products/order) calls versus one call.

Of course there is more work on the server side to resolve the query, but that's likely where the data is anyway.

We give you two paths to using GraphQL to define your data: using one of our templates, or using a GraphQL schema that you have already defined.

To use your GraphQL schema, you must have it defined in a file called schema.graphql within the directory grafbase at the root of your main branch in a GitHub repository.

You might wonder how we store your data based on a GraphQL schema.

Once we know what the GraphQL schema looks like, we provision a database for you that maps to your schema.

We also provide APIs that support create, read, update, and delete (CRUD) operations for all of the types in your schema that you have annotated with a @model directive.

For example, if you define a Product as shown previously, we provide an API to create a new product, which requires you supply a name, SKU, price, currency, and inventory (the number of the products initially in stock). If the API call succeeds, we create a new Product entry in the database. We do all of the heavy lifting to manage the interface between the APIs and the database; you simply write code using the APIs.