RPC protocol

The RPC protocol allows for network protocol agnostic communication with SurrealDB. It is used internally by our client SDKs, and is served over WebSocket, HTTP and, from 3.3.0, gRPC. Combined with the CBOR protocol specification, the RPC protocol provides a fully type-safe and efficient way to interact with SurrealDB over the network.

Session variables

SurrealDB's session variables hold session-specific data. They act as temporary storage tied to a user's active connection, for tasks such as maintaining application state, storing user preferences, or holding temporary data relevant only to the current session.

Session variables are strictly confined to the individual connection, so one user's session data remains private and does not interfere with other connections.

You can interact with session variables in the following ways:

1. 1.

   Explicit Session-Wide Management:

   • ◦

     Use the let method to define a new variable or update an existing one within the current session. This variable will persist for the duration of the connection.

   • ◦

     Use the unset method to remove a previously defined variable from the session.

   • ◦

     The reset method, in addition to its other functions, clears all currently defined session variables, restoring the session's variable state.

2. 2.

   Implicit Request-Scoped Management:

   • ◦

     Methods query, select, insert, create, upsert, update, relate, and delete, accept an optional vars parameter. This parameter is an object containing key-value pairs, where each key represents the variable name (without the leading $) and the value is the data to be assigned.

   • ◦

     Variables passed via this parameter are defined only for the execution context of that specific method call. They temporarily override any session-wide variable with the same name for that request but do not permanently alter the session state. These variables are automatically discarded once the method execution completes.

To use a session variable within a query or method, prefix its name with a dollar sign ($), for example, $user_id.

Scoped connections

The namespace and database can be part of the connection URL, so that a client sends no initial use:

ws://localhost:8000/ns/main/db/main/rpc
http://localhost:8000/ns/main/db/main/rpc

The namespace and database in the URL are where the connection starts, in the same way as the surreal-ns and surreal-db headers. The server checks them when it authenticates the connection, and the credentials must belong to that namespace and database. After that, a use, a SurrealQL USE, or a signin or signup can select another namespace or database, and reset unsets both. The full rules are on the HTTP page under Scoped URLs.

Supported methods

You can use the RPC protocol to perform the following actions:

Message size limits

How much a single RPC call may carry depends on the transport it arrives over.

The WebSocket ceiling is roughly thirty times the HTTP one, which is why the SDKs default to the WebSocket engine. If a payload is rejected over HTTP, moving the same call onto a WebSocket connection is usually enough.

Server and client limits

The values above are what the server accepts. An SDK may also enforce its own limit on outgoing messages, and that limit is applied before anything reaches the network. The effective ceiling is therefore whichever of the two is lower.

The Rust SDK defaults to 64 MiB per message. Sending more than that produces a Message too long error from the client itself, not a rejection from the server. The limit is configurable:

use surrealdb::engine::remote::ws::Ws;
use surrealdb::opt::{Config, WebsocketConfig};
use surrealdb::Surreal;

let websocket = WebsocketConfig::new().max_message_size(128 << 20); // 128 MiB
let config = Config::new().websocket(websocket)?;
let db = Surreal::new::<Ws>(("127.0.0.1:8000", config)).await?;

Raising a client limit above the server's ceiling does not help, as the server still rejects the message. Raise both in this case, or keep messages under the lower of the two.

For request bodies on the other HTTP endpoints, see Request size limits.

gRPC transport

The server also serves the RPC protocol over gRPC, as the surrealdb.protocol.rpc.v1.SurrealDBService service defined in the surrealdb-protocol repository. gRPC shares the listener, port and TLS configuration of the HTTP and WebSocket endpoints: it runs over HTTP/2, which the server negotiates by the connection preface on a plaintext port and by ALPN on a TLS one, so no second port is configured. gRPC calls pass through the same middleware as the other endpoints, including the startup gate and the handling of the Authorization header. Denying the rpc HTTP route closes gRPC along with both /rpc endpoints, and the RPC method names restrict gRPC calls as they do WebSocket ones.

Clients connect with a grpc:// address, or grpcs:// for TLS. The Rust SDK supports both through its protocol-grpc feature, and surreal db sql --endpoint accepts them too.

A few details:

• •

  SURREAL_GRPC_MAX_MESSAGE_SIZE limits every message the server receives and every message it sends. It defaults to the value of SURREAL_HTTP_MAX_RPC_BODY_SIZE, and the server reports it to clients as Limits.max_message_bytes in the GetCapabilities handshake, so a client knows the limit before it sends anything. The server splits query results across as many messages as they need, so the limit bounds a single request, record or live query notification rather than a whole result. A client can also set a figure of its own, which bounds the responses it accepts, as described for the Rust SDK.

• •

  Compression is negotiated per client. The server accepts requests compressed with zstd or gzip, answers in whichever of the two the client lists in grpc-accept-encoding, and sends uncompressed messages to a client that lists neither.

• •

  SURREAL_GRPC_MAX_ATTACHED_SESSIONS and SURREAL_GRPC_NOTIFICATION_BUFFER bound the sessions attached across all gRPC connections and the live query notifications buffered for a slow subscriber. All three variables are listed under HTTP server config.

• •

  The service's Health method is the gRPC health check, and the health HTTP route allows or denies it together with GET /health. The server does not implement the standard grpc.health.v1.Health service, so a probe that calls that service, such as a Kubernetes grpc probe, fails with Unimplemented. Probe GET /health or GET /ready over HTTP instead.

• •

  The server does not offer gRPC server reflection, so a tool such as grpcurl needs the .proto files from the surrealdb-protocol repository.

Shaped results

Shaped results are a result format for clients that read many records of the same shape. A shaped result describes the fields of a row once, with their names and types, and then sends each row as its values only, with no field names and no type tags. Everything else, such as errors, scalar results and the response envelope, is CBOR, so a client needs a decoder for the row blocks in addition to the CBOR decoder it already has. JSON, CBOR and the other formats are unchanged, and a client that does not ask for shaped results never receives them.

A client opts in for each connection or request:

A statement whose result is a list of rows returns a shaped block in place of the array, in a query response, in the rows frames of query_stream, and in live query notifications. A block is a CBOR byte string under tag 57.

authenticate

This method allows you to authenticate a user against SurrealDB with a token.

authenticate [ token ]

Parameters

Example usage

{
    "id": 1,
    "method": "authenticate",
    "params": [ "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJTdXJyZWFsREIiLCJpYXQiOjE1MTYyMzkwMjIsIm5iZiI6MTUxNjIzOTAyMiwiZXhwIjoxODM2NDM5MDIyLCJOUyI6InRlc3QiLCJEQiI6InRlc3QiLCJTQyI6InVzZXIiLCJJRCI6InVzZXI6dG9iaWUifQ.N22Gp9ze0rdR06McGj1G-h2vu6a6n9IVqUbMFJlOxxA" ]
}

{
    "id": 1,
    "result": null
}

begin

This method opens an interactive transaction on the connection and returns its id, a UUID. Requests that carry that id in a top-level txn field run inside the transaction, and the changes stay invisible to other requests on the connection until the transaction is committed.

begin

A connection can hold 64 open transactions by default, which SURREAL_MAX_TRANSACTIONS_PER_CONNECTION changes. A further begin is refused with Too many open transactions.

{
    "id": 1,
    "method": "begin"
}

{
    "id": 1,
    "result": "01a119b9-ae48-7821-bcb0-7d0ee0aad775"
}

To run a request inside the transaction, add the txn field next to method and params. This works for query and for the other data methods such as create, select and update.

{
    "id": 2,
    "method": "query",
    "txn": "01a119b9-ae48-7821-bcb0-7d0ee0aad775",
    "params": ["CREATE person:1 SET name = 'a'"]
}

A request without txn runs outside the transaction. In the example above, SELECT * FROM person without txn returns an empty array until the commit, while the same query with txn returns person:1.

commit

This method commits a transaction opened with begin. The transaction id is the only parameter, and it goes in params, not in the txn field.

commit [ txn ]

{
    "id": 3,
    "method": "commit",
    "params": ["01a119b9-ae48-7821-bcb0-7d0ee0aad775"]
}

{
    "id": 3,
    "result": null
}

A transaction id that is unknown or already finished returns Transaction not found.

cancel

This method discards a transaction opened with begin, along with every change made inside it. The transaction id goes in params.

cancel [ txn ]

{
    "id": 4,
    "method": "cancel",
    "params": ["01a119b9-b558-7780-9a29-e350a7a492a3"]
}

{
    "id": 4,
    "result": null
}

The begin, commit and cancel methods are not available over HTTP, because HTTP requests carry no connection to hold the transaction between them.

create

This method creates a record either with a random or specified ID.

create [ thing, data ]

Parameters

Example usage

{
    "id": 1,
    "method": "create",
    "params": [
        "person",
        {
            "name": "Mary Doe"
        }
    ]
}

{
    "id": 1,
    "result": [
        {
            "id": "person:s5fa6qp4p8ey9k5j0m9z",
            "name": "Mary Doe"
        }
    ]
}

delete

This method deletes either all records in a table or a single record.

delete [ thing ]

Parameters

Example usage

{
    "id": 1,
    "method": "delete",
    "params": [ "person:8s0j0bbm3ngrd5c9bx53" ]
}

Notice how the deleted record is returned. This differs from a DELETE statement via the CLI or SurrealDB Studio which returns nothing unless the RETURN BEFORE clause is used.

{
    "id": 1,
    "result": {
        "active": true,
        "id": "person:8s0j0bbm3ngrd5c9bx53",
        "last_updated": "2023-06-16T08:34:25Z",
        "name": "John Doe"
    }
}

info

This method returns the record of an authenticated record user.

info

Example usage

{
    "id": 1,
    "method": "info"
}

The result property of the response is likely different depending on your schema and the authenticated user. However, it does represent the overall structure of the responding message.

{
    "id": 1,
    "result": {
        "id": "user:john",
        "name": "John Doe"
    }
}

insert

This method creates a record either with a random or specified ID.

insert [ thing, data ]

Parameters

Example usage

{
    "id": 1,
    "method": "insert",
    "params": [
        "person",
        {
            "name": "Mary Doe"
        }
    ]
}

{
    "id": 1,
    "result": [
        {
            "id": "person:s5fa6qp4p8ey9k5j0m9z",
            "name": "Mary Doe"
        }
    ]
}

Bulk insert

{
    "id": 1,
    "method": "insert",
    "params": [
        "person",
        [
            {
                "name": "Mary Doe"
            },
            {
                "name": "John Doe"
            }
        ]
    ]
}

{
    "id": 1,
    "result": [
        {
            "id": "person:s5fa6qp4p8ey9k5j0m9z",
            "name": "Mary Doe"
        },
        {
            "id": "person:xtbbojcm82a97vus9x0j",
            "name": "John Doe"
        }
    ]
}

insert_relation

This method inserts a new relation record into the database. You can specify the relation table to insert into and provide the data for the new relation.

insert_relation [ table, data ]

Parameters

Example usage

Inserting a Relation into a Specified Table

{
    "id": 1,
    "method": "insert_relation",
    "params": [
        "likes",                   // (relation table)
        {                          // data
            "in": "user:alice",
            "out": "post:123",
            "since": "2024-09-15T12:34:56Z"
        }
    ]
}

{
    "id": 1,
    "result": {
        "id": "likes:user:alice:post:123",
        "in": "user:alice",
        "out": "post:123",
        "since": "2024-09-15T12:34:56Z"
    }
}

Inserting a Relation Without Specifying the Table

If you do not specify the table parameter (i.e., set it to null or none), the relation table is inferred from the id field within the data.

{
    "id": 2,
    "method": "insert_relation",
    "params": [
        null,                      // relation table is null
        {                          // data
            "id": "follows:user:alice:user:bob",
            "in": "user:alice",
            "out": "user:bob",
            "since": "2024-09-15T12:34:56Z"
        }
    ]
}

{
    "id": 2,
    "result": {
        "id": "follows:user:alice:user:bob",
        "in": "user:alice",
        "out": "user:bob",
        "since": "2024-09-15T12:34:56Z"
    }
}

Notes

• •

  table parameter:

  • ◦

    Specifies the relation table into which the new relation record will be inserted.

  • ◦

    If table is null or none, the method expects the data to contain an id from which it can infer the relation table.

• •

  data parameter:

  • ◦

    Must include at least the in and out fields, representing the starting and ending points of the relation.

  • ◦

    Can include additional fields to store more information within the relation.

• •

  Relation IDs:

  • ◦

    If an id is provided in the data, it will be used as the identifier for the new relation record.

  • ◦

    If no id is provided, the system may generate one based on the table, in, and out fields.

• •

  Single vs. multiple inserts:

  • ◦

    The method primarily handles single relation inserts.

  • ◦

    The one variable in the code determines if the table parameter refers to a single item.

Error handling

• •

  Invalid parameters:

  • ◦

    If you provide fewer than two parameters or incorrect parameter types, you will receive an InvalidParams error.

  • ◦

    The method expects exactly two parameters: table and data.

Example of invalid parameters:

{
    "id": 3,
    "method": "insert_relation",
    "params": [
        "likes"  // Missing the data parameter
    ]
}

{
    "id": 3,
    "error": {
        "cause": null,
        "code": -32603,
        "details": { "kind": "InvalidParams" },
        "kind": "Validation",
        "message": "Expected (what, data)"
    }
}

See Errors for the full error shape, the list of kinds, and the wire codes.

Best practices

• •

  Include in and out Fields:

  • ◦

    Always provide the in and out fields in your data to define the relation endpoints.

• •

  Specifying the Relation Table:

  • ◦

    If possible, specify the table parameter to clearly indicate the relation table.

  • ◦

    If not specified, ensure that the id in data correctly reflects the desired relation table.

• •

  Providing an id in data:

  • ◦

    If you want to control the id of the relation, include it in the data.

  • ◦

    This is especially important when table is null or none.

Additional examples

Inserting a Relation with Auto-Generated ID

{
    "id": 4,
    "method": "insert_relation",
    "params": [
        "friendship",              // table (relation table)
        {                          // data
            "in": "user:alice",
            "out": "user:bob",
            "since": "2024-09-15"
        }
    ]
}

{
    "id": 4,
    "result": {
        "id": "friendship:user:alice:user:bob",
        "in": "user:alice",
        "out": "user:bob",
        "since": "2024-09-15"
    }
}

Notes:

• •

  The id is generated based on the table, in, and out fields.

• •

  The relation is inserted into the friendship table.

invalidate

This method will invalidate the user's session for the current connection.

invalidate

Example usage

{
    "id": 1,
    "method": "invalidate"
}

{
    "id": 1,
    "result": null
}

let

This method stores a variable on the current connection.

let [ name, value ]

Parameters

Example usage

{
    "id": 1,
    "method": "let",
    "params": [ "website", "https://surrealdb.com/" ]
}

{
    "id": 1,
    "result": null
}

live

This method initiates a live query for a specified table name.

live[ table ]

Parameters

Example usage

{
    "id": 1,
    "method": "live",
    "params": [ "person" ]
}

{
    "id": 1,
    "result": "0189d6e3-8eac-703a-9a48-d9faa78b44b9"
}

Live notification

For every creation, update or deletion on the specified table, a live notification will be sent. Live notifications do not have an ID attached, but rather include the Live Query's UUID in the result object.

{
    "result": {
        "action": "CREATE",
        "id": "0189d6e3-8eac-703a-9a48-d9faa78b44b9",
        "result": {
            "id": "person:8s0j0bbm3ngrd5c9bx53",
            "name": "John"
        }
    }
}

kill

This method kills an active live query, stopping any further notifications for it.

kill [ queryUuid ]

Parameters

Example usage

{
    "id": 1,
    "method": "kill",
    "params": [ "0189d6e3-8eac-703a-9a48-d9faa78b44b9" ]
}

{
    "id": 1,
    "result": null
}

merge

This method merges specified data into either all records in a table or a single record.

merge [ thing, data ]

Parameters

Example usage

{
    "id": 1,
    "method": "merge",
    "params": [
        "person",
        {
            "active": true
        }
    ]
}

{
  "id": 1,
  "result": [
      {
          "active": true,
          "id": "person:8s0j0bbm3ngrd5c9bx53",
          "name": "John Doe"
      },
      {
          "active": true,
          "id": "person:s5fa6qp4p8ey9k5j0m9z",
          "name": "Mary Doe"
      }
  ]
}

mysql

This method runs MySQL statements on the RPC session, in the MySQL dialect that the MySQL wire protocol listener uses. It takes the same parameters and options, and answers in the same form, as pgsql, with these differences:

• •

  A positional ? binds to the variable of its position, so the first ? reads _1.

• •

  A column's type is { "name", "mysql_type" }, where mysql_type is the MySQL protocol type code.

• •

  command.tag is the kind of statement, such as SELECT, INSERT, REPLACE or CREATE TABLE.

• •

  An ERR entry carries MySQL's SQLSTATE and its error number in errno, such as 1064 for a parse failure, 1146 for a missing table and 1062 for a duplicate key.

• •

  An entry whose whole text is USE name switches the session database within the session namespace, as the use method does.

• •

  START TRANSACTION takes READ ONLY, READ WRITE and WITH CONSISTENT SNAPSHOT. A failing statement leaves the transaction "active", because MySQL has no failed state.

• •

  SET statements are accepted and have no effect. User variables (@a) and SQL PREPARE statements, which the MySQL listener supports, are not available.

• •

  A column without an alias is named as in the PostgreSQL dialect, such as count for COUNT(*), not by its expression text as the MySQL listener names it.

The method is gated by the mysql RPC method name, the arbitrary query capability and the mysql HTTP route name.

{
    "id": 1,
    "method": "mysql",
    "params": [
        "SELECT name FROM person WHERE name = ?",
        { "_1": "Tobie" },
        { "rowMode": "array" }
    ]
}

patch

This method patches either all records in a table or a single record with specified patches.

patch [ thing, patches, diff ]

Parameters

Example usage

{
    "id": 1,
    "method": "patch",
    "params": [
        "person",
        [
            { "op": "replace", "path": "/last_updated", "value": "2023-06-16T08:34:25Z" }
        ]
    ]
}

{
    "id": 1,
    "result": [
        [
            {
                "op": "add",
                "path": "/last_updated",
                "value": "2023-06-16T08:34:25Z"
            }
        ],
        [
            {
                "op": "add",
                "path": "/last_updated",
                "value": "2023-06-16T08:34:25Z"
            }
        ]
    ]
}

pgsql

This method runs PostgreSQL statements on the RPC session, as query runs SurrealQL. The statements are read in the PostgreSQL dialect that the Postgres wire protocol listener uses, and run against SurrealDB tables. The method answers with the column metadata, command tags, error codes and transaction status that a SQL client library needs, so a client modelled on node-postgres can run over WebSocket or HTTP instead of a TCP connection. mysql is the same method for the MySQL dialect.

pgsql [ statements, vars?, options? ]

Parameters

An unknown option or value fails the call with invalid_params. The session's namespace, database, authentication and variables apply, as they do for query, so a call runs with the permissions of the signed-in user.

Response

A call that reaches the engine answers with one object. statements has one entry for each SQL statement, params is present only for a describe call, and transaction.status is "idle", "active" or "failed". An entry that ran has a command with the PostgreSQL command tag (SELECT 1, INSERT 0 3, CREATE TABLE) and the number of rows it read or wrote, a columns list with each column's name, PostgreSQL type and source table and column, and its rows. A record ID in a row is sent as its key, so person:1 is sent as 1.

An INSERT, UPDATE or DELETE answers with a count and no rows, unless it has a RETURNING clause. Within one string, the first statement that fails stops the statements after it, which answer with an ERR entry. A failing batch entry does not stop the entries after it, so independent statements go in separate entries.

A statement that fails answers with an ERR entry, while the call itself succeeds. Its error holds the message and the PostgreSQL sqlstate, such as 42601 for a parse failure, 42P01 for a missing table, 23505 for a duplicate key and 40001 for a transaction conflict that can be retried. A failure that is not about the statement text, such as a denied method or malformed parameters, fails the call as an RPC error.

A parameter bound to a column is read as the column's type when it is sent as text, so a client that sends every parameter as text can write to integer, float, numeric, boolean, timestamp, uuid and json columns. Text that does not read as the column's type fails with 42804. SQL PREPARE and EXECUTE statements are refused, so bind parameters with vars instead.

Transactions

Over WebSocket, an entry whose whole text is BEGIN or START TRANSACTION, with optional ISOLATION LEVEL and READ ONLY modes, opens a transaction on the session. Later calls run inside it until an entry that is COMMIT or ROLLBACK. REPEATABLE READ, READ COMMITTED and READ UNCOMMITTED run at snapshot isolation, and SERIALIZABLE opens a serializable transaction. After a failing statement, the status is "failed" and later statements fail with 25P02 until the transaction ends. SET TRANSACTION and SET SESSION CHARACTERISTICS AS TRANSACTION choose the modes of the next transaction, or of every later one.

An HTTP request holds no transaction between requests, so an entry that opens one fails. Use atomic: true instead, which works over both transports. In an atomic call, the statements after the first failure are not run, and the response reports committed: false.

SET, SHOW and RESET act on session settings, which last for the session over WebSocket and for the request over HTTP. A setting has no effect on the engine. A running call over WebSocket is cancelled with query_cancel, given the call's request id.

Capabilities

The method is gated by the pgsql RPC method name, by the arbitrary query capability as query is, and by the postgres HTTP route name. A call that a capability denies fails with a NotAllowed error.

Example usage

{
    "id": 1,
    "method": "pgsql",
    "params": [
        "SELECT id, name FROM person WHERE name = $1",
        { "_1": "Tobie" }
    ]
}

{
    "id": 1,
    "result": {
        "statements": [
            {
                "status": "OK",
                "time": "412µs",
                "command": {
                    "tag": "SELECT 1",
                    "rows_affected": 1,
                    "last_insert_id": null,
                    "warnings": 0
                },
                "columns": [
                    {
                        "name": "id",
                        "type": { "name": "integer", "oid": 23 },
                        "nullable": null,
                        "table": "person",
                        "column": "id"
                    },
                    {
                        "name": "name",
                        "type": { "name": "text", "oid": 25 },
                        "nullable": null,
                        "table": "person",
                        "column": "name"
                    }
                ],
                "rows": [ { "id": 1, "name": "Tobie" } ]
            }
        ],
        "transaction": { "status": "idle" }
    }
}

ping

ping

Example usage

{
    "id": 1,
    "method": "ping",
}

{
  "id": 1,
  "result": null
}

query

This method sends a custom SurrealQL query.

query [ sql, vars?, options? ]

Parameters

An unknown option is refused, so a misspelt option is never ignored.

Example usage

{
    "id": 1,
    "method": "query",
    "params": [
        "CREATE person SET name = 'John'; SELECT * FROM type::table($tb);",
        {
            "tb": "person"
        }
    ]
}

{
  "id": 1,
  "result": [
      {
          "status": "OK",
          "time": "152.5µs",
          "result": [
              {
                  "id": "person:8s0j0bbm3ngrd5c9bx53",
                  "name": "John"
              }
          ]
      },
      {
          "status": "OK",
          "time": "32.375µs",
          "result": [
              {
                  "id": "person:8s0j0bbm3ngrd5c9bx53",
                  "name": "John"
              }
          ]
      }
  ]
}

Tracing the graph a query walked

A query or query_stream call can report the graph edges, references and record links that its statements read to produce their results, along with the parameters that a LET bound and the live queries that a LIVE SELECT started. A client such as a graph view uses this to draw the relationships a query followed, instead of guessing them from the record ids in the results. The trace option lists the kinds to report.

In the example below, person:a is related to person:b through the edge knows:ab, and the call asks for relations and variables:

{
    "id": 1,
    "method": "query",
    "params": [
        "LET $x = 1; SELECT ->knows->person AS friends FROM person:a;",
        {},
        { "trace": ["relations", "variables"] }
    ]
}

Each result carries the trace of its statement under a trace field. A statement with nothing to report has no trace field.

{
  "id": 1,
  "result": [
      {
          "result": null,
          "status": "OK",
          "time": "189.625µs",
          "trace": { "variables": { "x": 1 } },
          "type": null
      },
      {
          "result": [{ "friends": ["person:b"] }],
          "status": "OK",
          "time": "2.2515ms",
          "trace": { "relations": [["person:a", "knows:ab", "person:b"]] },
          "type": null
      }
  ]
}

The trace option takes these kinds:

A trace reports only what leads to the result:

• •

  A lookup is reported only where its value is part of the result, and only for the edges that lead to the records it returned. An edge that a filter in the path removed, or a path that reaches no record, is not reported. A recursive lookup is reported at every depth.

• •

  A lookup or link in a condition, such as a WHERE clause, is not reported. A link that the result returns without reading through it, as in SELECT author FROM post, is not reported either.

• •

  A lookup or link that reaches the result through a function, an operator or an aggregate, such as count(->knows), is not reported. The trace carries "partial": true instead. A LIMIT over a graph path in FROM also sets partial.

• •

  Edges that a RELATE writes are not reported, because its result already holds them, and nor are links that FETCH resolves.

A trace holds only what the session can read. A record that its table permissions hide, an edge of a table that the session cannot select, and a link in a field that the session cannot read are not reported.

Asking for a trace does not change the results. A kind that is not asked for is not recorded, and a call without the trace option records nothing. A statement that fails, or that a transaction rolls back, has no trace. The same entry can appear more than once, so a client keys entries by their record ids.

A trace has size limits. A LET whose value is too large is reported by name with the value NONE, and a buffered query keeps at most about 1 MiB of relation, reference and link entries across all its statements. A trace that reached a limit lists the kinds it cut short in a truncated array.

A kind that the server does not know is refused, so a client never reads an unsupported kind as an empty one:

{
    "id": 1,
    "error": {
        "cause": null,
        "code": -32603,
        "details": { "kind": "InvalidParams" },
        "kind": "Validation",
        "message": "Unknown trace kind `records`"
    }
}

The trace option is not available over gRPC. A buffered query with a trace sends its results as ordinary values, not as shaped results.

query_cancel

This method stops a query_stream request that is still running on the same connection.

query_cancel [ id ]

Parameters

The method returns null once the stream has been told to stop. The stream then ends with an end frame whose error is The streaming query was stopped before it completed, which retracts every statement that had not finished. A connection can stop only its own streams, and an id with no stream in progress, including one that has just finished, returns the error No streaming query with this request id is in progress.

Example usage

{
    "id": 2,
    "method": "query_cancel",
    "params": [1]
}

{
    "id": 2,
    "result": null
}

query_stream

This method runs a query in the same way as query, but answers with a sequence of frames sent while the query runs instead of one response at the end, so the first records reach the client before the last statement has finished. Only the WebSocket /rpc endpoint serves it, and HTTP POST /rpc reports Method not found. Neither the Rust nor the JavaScript SDK calls this method over WebSocket. The Rust SDK's .stream_items() streams incrementally on the embedded engines and over gRPC, and the JavaScript SDK's streaming query responses do so on the embedded Node.js and browser engines, which produce the same frames locally.

query_stream [ sql, vars?, options? ]

Parameters

The request needs an id, because every frame carries it, and one without an id is refused. A second query_stream that reuses the id of a stream still running on the connection is refused with A streaming query with this request id is already in progress. A request that carries a txn runs inside that client transaction, and the client waits for the end frame before it sends commit, because a commit that arrives while the stream is running ends the transaction the stream is still using. A failure before execution starts, such as a parse error or a denied capability, is answered with an ordinary error response and no frames.

Frames

Each frame arrives as an ordinary response carrying the request's id, and its result is an object whose stream field names the frame type:

Records are provisional until their statement's finished frame arrives:

• •

  A finished frame with an error retracts every record already sent for that statement.

• •

  An end frame with an error retracts every statement that has no finished frame, while the statements that finished stand. This covers a timeout, a query_cancel, a transaction that could not commit, and a stream the server stopped because its frames could not be delivered, which reports The streaming query was stopped before it completed.

• •

  An end error can also name LIVE SELECT subscriptions that were discarded because their session ended, since their statements had already finished and cannot be retracted.

New frame types and fields can be added without changing version, so a client ignores a stream value or a field it does not recognise. Every finished frame carries single, because a statement that sent no rows or value frame has no other way to say whether its value is an empty list or a single value.

Trace

A request with the trace option, described under Tracing the graph a query walked, receives the trace of each statement inside the frames that the stream already sends, under a trace field. A trace never takes a frame of its own. It goes on the statement's next rows or value frame, or on its finished frame when no other frame follows.

• •

  A trace belongs to its statement, not to the records of the frame it arrives on, so a client collects it for each index across that statement's frames.

• •

  A trace is provisional in the same way as records. A finished frame with an error retracts every trace already sent for that statement.

• •

  The same entry can arrive in more than one frame.

{
    "id": 1,
    "method": "query_stream",
    "params": [
        "SELECT title, author.name, ->tagged->tag AS tags FROM post;",
        {},
        { "trace": ["relations", "links"] }
    ]
}

{ "id": 1, "result": { "statements": 1, "stream": "begin", "version": 1 } }
{
    "id": 1,
    "result": {
        "index": 0,
        "stream": "rows",
        "trace": {
            "links": [["post:1", "author", "person:tobie"]],
            "relations": [["post:1", "tagged:a", "tag:rust"]]
        },
        "values": [{ "author": { "name": "Tobie" }, "tags": ["tag:rust"], "title": "Hello" }]
    }
}
{ "id": 1, "result": { "index": 0, "single": false, "stream": "finished", "time": "188.25µs", "type": null } }
{ "id": 1, "result": { "results": 1, "stream": "end", "time": "301.5µs" } }

Limits

• •

  SURREAL_WEBSOCKET_MAX_CONCURRENT_STREAMS, 32 by default, limits how many streams one connection runs at once. A request over the limit is refused with Too many concurrent streaming queries rather than queued.

• •

  SURREAL_WEBSOCKET_STREAM_SEND_TIMEOUT, 30 seconds by default, stops a stream that has waited that long to send one frame, which is what happens when the client stops reading. It applies whether or not --query-timeout is set.

• •

  --query-timeout, when set, limits the whole stream, including the time spent waiting to send frames.

• •

  query_stream is an RPC method capability of its own, and the query runs through the query method's gate as well, so denying either method denies streaming.

Both environment variables are listed under WebSocket config.

Example usage

{
    "id": 1,
    "method": "query_stream",
    "params": [
        "SELECT * FROM person; RETURN 1 + 2;"
    ]
}

The server sends these frames in order, one message each:

{ "id": 1, "result": { "statements": 2, "stream": "begin", "version": 1 } }
{
    "id": 1,
    "result": {
        "index": 0,
        "stream": "rows",
        "values": [
            { "id": "person:jane", "name": "Jane" },
            { "id": "person:john", "name": "John" }
        ]
    }
}
{ "id": 1, "result": { "index": 0, "single": false, "stream": "finished", "time": "215.042µs", "type": null } }
{ "id": 1, "result": { "index": 1, "stream": "value", "value": 3 } }
{ "id": 1, "result": { "index": 1, "single": true, "stream": "finished", "time": "18.5µs", "type": null } }
{ "id": 1, "result": { "results": 2, "stream": "end", "time": "402.917µs" } }

relate

This method relates two records with a specified relation.

relate [ in, relation, out, data? ]

Parameters

Example usage

{
    "id": 1,
    "method": "relate",
    "params": [
        "person:12s0j0bbm3ngrd5c9bx53",
        "knows",
        "person:8s0j0bbm3ngrd5c9bx53"
    ]
}

{
    "id": 1,
    "result": {
        "id": "knows:12s0j0bbm3ngrd5c9bx53:8s0j0bbm3ngrd5c9bx53",
        "in": "person:12s0j0bbm3ngrd5c9bx53",
        "out": "person:8s0j0bbm3ngrd5c9bx53"
    }
}

Creating a relation with additional data

{
    "id": 2,
    "method": "relate",
    "params": [
        "person:john_doe",          // in
        "knows",                    // relation
        "person:jane_smith",        // out
        { "since": "2020-01-01" }   // data
    ]
}

{
    "id": 2,
    "result": {
        "id": "knows:person:john_doe:person:jane_smith",
        "in": "person:jane_smith",
        "out": "person:john_doe",
        "since": "2020-01-01"
    }
}

reset

This method will reset all attributes for the current connection. It clears authentication (much like invalidate), unsets the selected NS/DB, unsets any defined connection params, and aborts any active live queries. On WebSocket connections it also cancels open client-managed transactions for the session being reset and frees their slots under SURREAL_MAX_TRANSACTIONS_PER_CONNECTION / SURREAL_MAX_TRANSACTIONS_PER_SESSION.

reset

Example usage

{
    "id": 1,
    "method": "reset"
}

{
    "id": 1,
    "result": null
}

run

This method allows you to execute built-in functions or custom functions with optional arguments. SurrealDB 4.0 removed SurrealML, so a call to an ml:: model fails.

run [ func_name, version?, args? ]

Parameters

Executing a built-in function

{
    "id": 1,
    "method": "run",
    "params": [ "time::now" ]
}

{
    "id": 1,
    "result": "2024-09-15T12:34:56Z"
}

Executing a custom function

{
    "id": 1,
    "method": "run",
    "params": [ "fn::calculate_discount", null, [ 100, 15 ] ]
}

{
    "id": 1,
    "result": 85
}

select

This method selects either all records in a table or a single record.

select [ thing ]

Parameters

Example usage

{
    "id": 1,
    "method": "select",
    "params": [ "person" ]
}

{
    "id": 1,
    "result": [
        {
            "id": "person:8s0j0bbm3ngrd5c9bx53",
            "name": "John"
        }
    ]
}

signin

This method allows you to sign in as a root, namespace, or database user, or with a record access method.

Signing in also selects the namespace and database it names, so the connection needs no separate use call afterwards. A database user or a record access method selects both NS and DB, and a namespace user selects NS. A root user selects neither. Once signed in, a user can only switch to a namespace or database that it has access to.

The result is the authentication token as a string. When a record access method is defined WITH REFRESH, the result is instead an object holding the token as access and a refresh token as refresh.

signin [ NS, DB, AC, ... ]

Parameters

Example with root user

{
    "id": 1,
    "method": "signin",
    "params": [
        {
            "user": "tobie",
            "pass": "3xtr3m3ly-s3cur3-p@ssw0rd"
        }
    ]
}

{
    "id": 1,
    "result": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE3OTAyMjQ0NjIsIm5iZiI6MTc5MDIyNDQ2MiwiZXhwIjoxNzkwMjI4MDYyLCJpc3MiOiJTdXJyZWFsREIiLCJqdGkiOiJmZWM2MDlmNS0zY2VhLTQwYTItOTc0MC00ZjliMWNmNGFhOWUiLCJJRCI6InJvb3QifQ.wJD-0zmqmGc1qE4XHt1zI6HBvA_YnOsHuxYwYBHqreAqxTgG04B_lb1-SfTLtHX_f319T15xaHaNhkeOUEmggg"
}

Example with record user

{
    "id": 1,
    "method": "signin",
    "params": [
        {
            "NS": "surrealdb",
            "DB": "docs",
            "AC": "commenter",

            "username": "johndoe",
            "password": "SuperStrongPassword!"
        }
    ]
}

{
    "id": 1,
    "result": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJTdXJyZWFsREIiLCJpYXQiOjE1MTYyMzkwMjIsIm5iZiI6MTUxNjIzOTAyMiwiZXhwIjoxODM2NDM5MDIyLCJOUyI6InRlc3QiLCJEQiI6InRlc3QiLCJTQyI6InVzZXIiLCJJRCI6InVzZXI6dG9iaWUifQ.N22Gp9ze0rdR06McGj1G-h2vu6a6n9IVqUbMFJlOxxA"
}

signup

This method allows you to sign a user up using the SIGNUP query defined in a record access method.

The result is the authentication token as a string. When the record access method is defined WITH REFRESH, the result is instead an object holding the token as access and a refresh token as refresh.

signup [ NS, DB, AC, ... ]

Parameters

Example usage

{
    "id": 1,
    "method": "signup",
    "params": [
        {
            "NS": "surrealdb",
            "DB": "docs",
            "AC": "commenter",

            "username": "johndoe",
            "password": "SuperStrongPassword!"
        }
    ]
}

{
  "id": 1,
  "result": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJTdXJyZWFsREIiLCJpYXQiOjE1MTYyMzkwMjIsIm5iZiI6MTUxNjIzOTAyMiwiZXhwIjoxODM2NDM5MDIyLCJOUyI6InRlc3QiLCJEQiI6InRlc3QiLCJTQyI6InVzZXIiLCJJRCI6InVzZXI6dG9iaWUifQ.N22Gp9ze0rdR06McGj1G-h2vu6a6n9IVqUbMFJlOxxA"
}

unset

This method removes a variable from the current connection.

unset [ name ]

Parameters

Example usage

{
    "id": 1,
    "method": "unset",
    "params": [ "website" ]
}

{
    "id": 1,
    "result": null
}

update

This method replaces either all records in a table or a single record with specified data.

update [ thing, data ]

Parameters

Example usage

{
    "id": 1,
    "method": "update",
    "params": [
        "person:8s0j0bbm3ngrd5c9bx53",
        {
            "name": "John Doe"
        }
    ]
}

{
    "id": 1,
    "result": {
        "id": "person:8s0j0bbm3ngrd5c9bx53",
        "name": "John Doe"
    }
}

upsert

upsert [ thing, data ]

Parameters

Example usage

{
    "id": 1,
    "method": "upsert",
    "params": [
        "person:12s0j0bbm3ngrd5c9bx53",
        {
            "name": "John Doe",
            "job": "Software developer",
        }
    ]
}

{
    "id": 1,
    "result": {
        "id": "person:12s0j0bbm3ngrd5c9bx53",
        "name": "John Doe",
        "job": "Software developer"
    }
}

use

This method specifies or unsets the namespace and/or database for the current connection.

use [ ns, db ]

Parameters

Accepted values

For either the namespace or database, a string will change the value, null will unset the value, and none will cause the value to not be affected.

On a scoped connection, use can select a namespace or database other than the ones in the URL.

Example usage

{
    "id": 1,
    "method": "use",
    "params": [ "surrealdb", "docs" ]
}

{
    "id": 1,
    "result": null
}

[none, none]     -- Won't change ns or db
["test", none]   -- Change ns to test
[none, "test"]   -- Change db to test
["test", "test"] -- Change ns and db to test

[none, null]     -- Will only unset the database
[null, none]     -- Will throw an error, you cannot unset only the database
[null, null]     -- Will unset both ns and db
["test", null]   -- Change ns to test and unset db

version

This method returns version information about the database/server.

version

Parameters

This method does not accept any parameters.

Example usage

{
    "id": 1,
    "method": "version"
}

{
    "id": 1,
    "result": {
        "version": "3.2.0",
        "build": "abc123",
        "timestamp": "2024-09-15T12:34:56Z"
    }
}

Notes

• •

  Parameters: Providing any parameters will result in an InvalidParams error.

• •

  Result Fields:

  • ◦

    version: The version number of the database/server.

  • ◦

    build: The build identifier.

  • ◦

    timestamp: The timestamp when the version was built or released.