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.
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
WarningBy 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.
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
.
ImportantIn the Surrealist sandbox, querying via GraphQL is not supported.
Learn more about starting a connection in the Surrealist documentation.
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
.
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 tableDEFINE 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', };
ImportantYou 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, andDEFINE 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.
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.
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
.
To learn more about the GraphQL view in Surrealist, check out the Surrealist documentation.