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

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 /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",
			},
		]
	}
]