GraphQL via HTTP

SurrealDB provides a powerful HTTP API that allows you to interact with the database programmatically. This API can be used to perform a wide range of database operations, from querying data to modifying records and managing database structures.

The HTTP API is designed to be simple and intuitive, with a RESTful interface that provides a consistent way to interact with the database. You can use the API to perform a wide range of database operations, from querying data to modifying records and managing database structures.

Starting a new connection

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

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.

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.

POST /sql

To use the GraphQL API, you first need to enable it using the DEFINE CONFIG statement. This will allow you to query the table using GraphQL on a per-database basis.

To do this, you can send a POST request to the /sql endpoint with a RAW body containing the DEFINE CONFIG statement. For example:

Enabling GraphQL
DEFINE CONFIG GRAPHQL AUTO;

POST /graphql

Available since: v2.0.0

To use the GraphQL API, you can send a POST request to the /graphql endpoint with a JSON body containing the GraphQL query. For example, to query the person table for all records, you can send the following request:

{
  "query": "{ person { name } }"
}

You can access this endpoint at http://localhost:8000/graphql via Postman or any other HTTP client.

The GraphQL endpoint enables use of GraphQL queries to interact with your data.

Headers

Example usage

Request
curl -X POST -u "root:root" -H "surreal-ns: mynamespace" -H "surreal-db: mydatabase" -H "Accept: application/json" -d '{"query": "{ person(filter: {age: {age_gt: 18}}) { id name age } }"}' http://localhost:8000/graphql

Response
[
	{
		"time": "14.357166ms",
		"status": "OK",
		"result": [
			{
				"age": "23",
				"id": "person:6r7wif0uufrp22h0jr0o"
				"name": "Simon",
			},
			{
				"age": "28",
				"id": "person:6r7wif0uufrp22h0jr0o"
				"name": "Marcus",
			},
		]
	}
]