Sample queries

From SurrealDB 3.1.0, SurrealDB’s GraphQL layer uses Apollo-style names: a pluralised list field (for example people for table person), a singular fetch field person(id: …), and people_aggregate for aggregates. Under the hood these map to SurrealQL-style reads (typically SELECT). The SurrealQL here is a rough equivalent for the same or similar data shape. See GraphQL overview for the full naming table.

Before trying the examples, enable GraphQL and define data in the current namespace and database (see GraphQL overview using DEFINE CONFIG GRAPHQL AUTO). The snippets below assume:

• •

  Namespace main, database main

• •

  Root authentication root / secret

• •

  A person table with name and age, and records person:simon and person:marcus as in GraphQL via HTTP

DEFINE TABLE person SCHEMAFULL;
DEFINE FIELD name ON TABLE person TYPE string;
DEFINE FIELD age ON TABLE person TYPE number;
CREATE person:simon SET name = "Simon", age = 23;
CREATE person:marcus SET name = "Marcus", age = 28;
DEFINE CONFIG GRAPHQL AUTO;

List records and choose fields

GraphQL here returns a list of objects, similar to SELECT without ONLY.

query {
	people {
		name
		age
	}
}

{
	"data": {
		"people": [
			{
				"age": 28,
				"name": "Marcus"
			},
			{
				"age": 23,
				"name": "Simon"
			}
		]
	}
}

Fetch a single record by id

Use person(id: …) with the record key (simon, not person:simon in the argument). The GraphQL id field on the result is the full record id.

query {
	person(id: "simon") {
		id
		name
		age
	}
}

{
	"data": {
		"person": {
			"id": "person:simon",
			"name": "Simon",
			"age": 23
		}
	}
}

Limit how many records are returned

GraphQL uses limit (and optional start for offset). SurrealQL uses LIMIT / START and ONLY to return a single record as opposed to an array containing a single record.

query {
	people(limit: 1) {
		name
		age
	}
}

{
	"data": {
		"people": [
			{
				"age": 28,
				"name": "Marcus"
			}
		]
	}
}

Filter records

GraphQL accepts filter or where with the generated input type for the table. For a scalar field, use comparison keys such as eq, ne, gt, and lt where the schema allows them.

query {
	people(where: { age: { eq: 23 } }) {
		name
	}
}

{
	"data": {
		"people": [
			{
				"name": "Simon"
			}
		]
	}
}

Order results

Use an order argument with asc or desc and a field name.

query {
	people(order: { asc: age }) {
		name
		age
	}
}

{
	"data": {
		"people": [
			{
				"age": 23,
				"name": "Simon"
			},
			{
				"age": 28,
				"name": "Marcus"
			}
		]
	}
}

Next steps

• •

  Query the same endpoint from HTTP clients: GraphQL via HTTP

• •

  Optional: Bruno or Surrealist

For the full configuration surface (tables, functions, limits), see DEFINE CONFIG GRAPHQL.