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 starting a new instance of SurrealDB with the surreal start command.

surreal start --log debug --user root --password root

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.

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;

Here is an example of how to accomplish this query via a curl command to a namespace and database both named main, assuming a root user with the password secret.

curl -X POST -u "root:secret" -H "Surreal-NS: main" -H "Surreal-DB: main" -H "Accept: application/json" \
  -d 'DEFINE CONFIG GRAPHQL AUTO' http://localhost:8000/sql

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:secret" -H "surreal-ns: main" -H "surreal-db: main" -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",
			},
		]
	}
]