# GraphQL

In this section, you will explore GraphQL, an industry-wide recognised protocol for interacting with your data, allowing you to query your data using any preferred method which offers precision and efficiency in data retrieval.

SurrealDB supports [GraphQL](https://graphql.org/) through the [`/graphql`](/docs/reference/rest-api/http-protocol.md#graphql) endpoint, which can be accessed via [SurrealDB Studio](https://app.surrealdb.com/), GraphiQL, Postman, or any other GraphQL client.

> [!NOTE]
> **GraphQL is not GQL.** [ISO GQL](/docs/learn/querying/gql/overview.md) (`MATCH … RETURN …`) is a separate language on [`POST /gql`](/docs/reference/rest-api/http-protocol.md#gql). Do not abbreviate GraphQL to `gql` — in SurrealDB, `gql` always means ISO GQL.

## 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`](/docs/reference/query-language/statements/define/config.md).

The simplest clause to follow this with is `AUTO`, which will automatically include all tables in the GraphQL schema.

```surql
DEFINE CONFIG GRAPHQL AUTO;
```

A query for `(INFO FOR DB).configs` will show that the above statement ends up having the clauses `TABLES AUTO FUNCTIONS AUTO`.

```surql
{ GraphQL: 'GRAPHQL TABLES AUTO FUNCTIONS AUTO' }
```

For more fine tuning of the configuration, the `TABLES` and `FUNCTIONS` clauses can be followed by [other clauses](/docs/reference/query-language/statements/define/config.md#tables-configuration).

## Schema naming _(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`](/docs/reference/query-language/statements/define/field.md) or [`GRAPHQL_DEPRECATED`](/docs/reference/query-language/statements/define/field.md) on [`DEFINE FIELD`](/docs/reference/query-language/statements/define/field.md) / [`DEFINE TABLE`](/docs/reference/query-language/statements/define/table.md) / [`DEFINE FUNCTION`](/docs/reference/query-language/statements/define/function.md). 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 [`/graphql`](/docs/reference/rest-api/http-protocol.md#graphql) endpoint [via HTTP (cURL)](/docs/learn/querying/graphql/via-http.md)
- Using the [`/graphql`](/docs/reference/rest-api/http-protocol.md#graphql) endpoint [via Bruno](/docs/learn/querying/graphql/via-bruno.md)
- Using [SurrealDB Studio](https://app.surrealdb.com/), 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.