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.

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

Available since: v3.3.0

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 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.

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
}

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

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

ping

ping

Example usage

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

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

query

This method sends a custom SurrealQL query.

query [ sql, vars ]

Parameters

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

query_cancel

Available since: v3.3.0

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

Available since: v3.3.0

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 ]

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.

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, custom functions, or machine learning models with optional arguments.

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
}

Executing a machine learning model

{
    "id": 1,
    "method": "run",
    "params": [ "ml::image_classifier", "v2.1", [ "image_data_base64" ] ]
}

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

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.

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.

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.