SurrealDB supports GraphQL through the /graphql endpoint, which can be accessed via Surrealist, GraphiQL, Postman, or any other GraphQL client.
Key features
GraphQL offers a number of key features that make it a powerful tool for working with SurrealDB:
Declarative Data Fetching: GraphQL allows you to request exactly the data you need, no more and no less. This reduces over-fetching and under-fetching of data, leading to more efficient queries.
Strongly Typed Schema: GraphQL uses a strong type system to define the capabilities of an API. This schema serves as a contract between the client and the server, ensuring that queries are valid before execution.
Hierarchical Structure: GraphQL queries mirror the shape of the data they return, making it intuitive to work with nested data structures.
Single Endpoint: When using GraphQL over HTTP, it typically uses a single endpoint, simplifying API architecture and reducing network overhead.
Ecosystem and Tools: GraphQL has a rich ecosystem of tools for development, testing, and monitoring, including GraphiQL for query exploration and Apollo Client for state management.
Getting started
Enabling GraphQL queries for SurrealDB can be done through a single statement: DEFINE CONFIG GRAPHQL.
The simplest clause to follow this with is AUTO, which will automatically include all tables in the GraphQL schema.
A query for (INFO FOR DB).configs will show that the above statement ends up having the clauses TABLES AUTO FUNCTIONS AUTO.
For more fine tuning of the configuration, the TABLES and FUNCTIONS clauses can be followed by other clauses.
Schema naming Available since: v3.1.0
From SurrealDB 3.1.0, the auto-generated GraphQL schema follows a single Apollo-style naming convention (there is no NAMING switch):
| Operation | Example for table person |
|---|---|
| Fetch one record | person(id: ID!) |
| List records | people(filter, where, order, limit, start, version) — pluralised table name |
| Aggregate | people_aggregate(filter, groupBy, …) |
| Create / update / delete | createPerson, updatePerson, deletePerson (bulk: createPeople, …) |
Field names on types mirror SurrealQL unless you set GRAPHQL_ALIAS or GRAPHQL_DEPRECATED on DEFINE FIELD / DEFINE TABLE / DEFINE FUNCTION. List queries also support Relay-style peopleConnection cursor pagination alongside offset limit / start.
If you upgrade from 3.0.x, regenerate client stubs and saved queries — names such as _get_person and createManyPerson are no longer generated for typical tables.
Next steps
The next page introduces some common GraphQL patterns and their SurrealQL equivalents or near equivalents.
This is followed by the following pages that detail the various tools by which GraphQL queries can be run on a SurrealDB database:
Using the
/graphqlendpoint via HTTP (cURL)Using Surrealist, SurrealDB's interactive environment for experimenting with GraphQL queries and seeing results immediately in the UI.
Other tools such as Postman and many others can be used against the /graphql endpoint.