This section covers the ways to write and send queries to your SurrealDB database. The main focus is on the SurrealQL query language, which strongly resembles traditional SQL but differs in a number of ways to accommodate patterns such as graph traversal, record links, and other features unique to SurrealDB.
Queries can also be written without using direct SurrealQL through methods such as SDKs in your preferred programming language, GraphQL, or GQL (ISO graph pattern queries on the /gql endpoint). The Postgres wire protocol lets standard Postgres clients (psql, JDBC, etc.) connect and run SurrealQL or GQL with tabular results. Built-in eval::* functions can also run SurrealQL or GQL query strings from inside a transaction when explicitly enabled.
This section also includes tips for writing efficient queries. For more detail, the reference section of the documentation has separate pages for each statement, data type, clause and more for the entire SurrealQL query language.
Concepts and guides
Parameterised queries - pass values as parameters instead of building query strings
Working with types - how values are typed, cast and asserted
Custom functions - name and reuse a query with
DEFINE FUNCTIONSubqueries and advanced patterns - nest queries and compose results
Transactions - group statements so they succeed or fail together
Idempotent operations - write statements that are safe to retry
Error handling - what a failed statement returns, and how to react to it
Sequences - generate monotonic numbers without a race
Sessions and scoping - what a session carries, and how long it lasts
Query optimisation - read a query plan and index for it
Bulk operations and data import - load many records efficiently
Connecting from serverless & edge - connection patterns where processes are short-lived
Representations and codecs - how values are encoded over each protocol
Testing - assert query results as part of a test suite
Performance
Performance best practices - what to measure, and what usually costs the most
Custom APIs
Middleware - run code before and after a custom API handler