GraphQL via Surrealist

In this section, you will explore writing GraphQL queries in Surrealist. The GraphQL query view in Surrealist provides a rich set of features, including syntax highlighting, query validation, and query execution. You can see the results of your queries in JSON structure returned by GraphQL.

Getting Started

Before you can start making queries, you need to start SurrealDB with the GraphQL module enabled. You can do this by setting the SURREAL_EXPERIMENTAL_GRAPHQL environment variable to true and starting a new instance of SurrealDB with the surreal start command.

SURREAL_EXPERIMENTAL_GRAPHQL=true surreal start --log debug --user root --password root

$env:SURREAL_EXPERIMENTAL_GRAPHQL=true surreal start --log debug --user root --password root

Warning

By running SurrealDB with the GraphQL module enabled, you are opting into an experimental feature. While the GraphQL module is fully functional, it is still considered experimental and may not be as stable as the core SurrealQL module which means we cannot guarantee that it will provide the same security guarantees. It is not recommended for production use. We welcome your feedback and contributions to help improve the feature and make it more robust.

After starting the SurrealDB instance, you can navigate to the Surrealist to start a new connection.

Start a new connection

In the top left corner of the Surrealist, start a new connection. Ensure that the connection information is the same as the one you used to start the SurrealDB instance. In the example above we have set the user to root and the password to root.

Important

In the Surrealist sandbox, querying via GraphQL is not supported.

Learn more about starting a connection in the Surrealist documentation.

Setting a namespace and database

Before you can start writing queries, you need to set the namespace and database you want to use. For example you can set the namespace to test and the database to test. This will set the namespace and database for the current connection.

Additionally, you can start a serving in Surrealist which also enables GraphQL automatically, which starts a server on http://localhost:8000 by default for a root user with username and password root.

Preparing your database

Next, use the SurrealQL query editor to create some data. For example, you can create a new user table with fields for firstName, lastName, and email and add a new user to the database.

In order to allow querying the created table using GraphQL, you will need to explicitly enable GraphQL using the DEFINE CONFIG statement. This will allow you to query the table using GraphQL on a per-database basis.

Creating a user table
DEFINE TABLE user SCHEMAFULL;

-- Enable GraphQL for the user table.
DEFINE CONFIG GRAPHQL AUTO;

-- Define some fields.
DEFINE FIELD firstName ON TABLE user TYPE string;
DEFINE FIELD lastName ON TABLE user TYPE string;
DEFINE FIELD email ON TABLE user TYPE string
  ASSERT string::is::email($value);
DEFINE INDEX userEmailIndex ON TABLE user COLUMNS email UNIQUE;

-- Create a new User
CREATE user CONTENT {
    firstName: 'Jon',
    lastName: 'Doe',
    email: 'Jon.Doe@surrealdb.com',
};

Important

You can only use GraphQL to query data from explicitly defined resources for a given table. That is, you must use the DEFINE TABLE statement to define the table, and DEFINE FIELD statement to define the fields for the table. As such, in schemaless mode, since the fields are not explicitly defined, you cannot query them using GraphQL.

Write your first GraphQL query

After you have created some data, you can start writing GraphQL queries. You can use the Surrealist GraphQL editor to write your GraphQL queries.

For example, to query the person table for all records, you can write the following GraphQL query:

{
    user {
        firstName
        lastName
        email
    }
}

and to get the person with the email “Jon.Doe@surrealdb.com”, you can write the following GraphQL query:

{
    user(filter: {email: {eq: "Jon.Doe@surrealdb.com"}}) {
        firstName
        lastName
    }
}

Surrealist will automatically validate the query and provide you with the results.

Introspection

Surrealist also supports introspection with GraphQL. This means that you can query the database and Surrealist will automatically infer the type of the data you are querying. For example, if you query the user table for all records, Surrealist will automatically infer the type of the data to be user.

Learn more

To learn more about the GraphQL view in Surrealist, check out the Surrealist documentation.