SurrealDB Docs Logo

Enter a search query

Back to home

Enter a search query

IntegrationRPC Protocol

RPC Protocol

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

Note

Version 2 of the RPC protocol significantly enhances data manipulation and retrieval methods by adding an optional object parameter. This enables direct control over statement clauses like WHERE, LIMIT, TIMEOUT, and more, previously only available through direct SQL execution.

Important

Method Consolidation: The merge, patch, and insert_relation methods from version 1 have been consolidated into the update and insert methods respectively.

Session Variables

SurrealDB’s session variables provide a robust mechanism for managing session-specific data. Think of them as temporary storage tied directly to a user’s active connection, ideal for tasks like maintaining application state, storing user preferences, or holding temporary data relevant only to the current session.

A key characteristic of session variables is their scope: they are strictly confined to the individual connection. This isolation ensures that one user’s session data remains private and does not interfere with others, allowing for personalized experiences within a multi-user environment. You can interact with session variables in the following ways:

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

FunctionDescription
authenticate [ token ]Authenticate a user against SurrealDB with a token
create [ thing, data ]Create a record with a random or specified ID
delete [ thing ]Delete either all records in a table or a single record
graphql [ query, options? ]Execute GraphQL queries against the database
infoReturns the record of an authenticated record user
insert [ thing, data ]Insert one or multiple records in a table
insert_relation [ table, data ]Insert a new relation record into a specified table or infer the table from the data
invalidateInvalidate a user’s session for the current connection
kill [ queryUuid ]Kill an active live query
let [ name, value ]Define a variable on the current connection
live [ table, diff ]Initiate a live query
merge [ thing, data ]Merge specified data into either all records in a table or a single record
patch [ thing, patches, diff ]Patch either all records in a table or a single record with specified patches
pingSends a ping to the database
query [ sql, vars ]Execute a custom query with optional variables
relate [ in, relation, out, data? ]Create graph relationships between created records
resetResets all attributes for the current connection
run [ func_name, version, args ]Execute built-in functions, custom functions, or machine learning models with optional arguments.
select [ thing ]Select either all records in a table or a single record
signin [NS, DB, AC, … ]Signin a root, NS, DB or record user against SurrealDB
signup [ NS, DB, AC, … ]Signup a user using the SIGNUP query defined in a record access method
unset [ name ]Remove a variable from the current connection
update [ thing, data ]Modify either all records in a table or a single record with specified data if the record already exists
upsert [ thing, data ]Replace either all records in a table or a single record with specified data
use [ ns, db ]Specifies or unsets the namespace and/or database for the current connection
versionReturns version information about the database/server

authenticate

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

Method Syntax
authenticate [ token ]

Parameters

ParameterDescription
token required

The token that authenticates the user

Example usage

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

create

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

Method Syntax
create [ thing, data ]

Parameters

ParameterDescription
thing required

The thing (Table or Record ID) to create. Passing just a table will result in a randomly generated ID

data optional

The content of the record

Example usage

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

delete

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

Method Syntax
delete [ thing ]

Parameters

ParameterDescription
thing required

The thing (Table or Record ID) to delete

Example usage

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

Notice how the deleted record is being returned here

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

graphql

Available since: v2.0.0

This method allows you to execute GraphQL queries against the database.

Method Syntax
graphql [ query, options? ]

Parameters

ParameterDescription
query required

A GraphQL query string or an object containing the query, variables, and operation name.

options optional

An object specifying options such as the output format and pretty-printing.

query Parameter

The query parameter can be either:

  • A string containing the GraphQL query. For example:
{ "query": "{ author { id name } }" }
  • An object with the following fields:
    • query (required): The GraphQL query string.
    • variables or vars (optional): An object containing variables for the query.
    • operationName or operation (optional): The name of the operation to execute.

Example:

{
    "query": "query GetUser($id: ID!) { user(id: $id) { id name } }",
    "variables": { "id": "user:1" },
    "operationName": "GetUser"
}

options Parameter

The options parameter is an object that may include:

  • pretty (optional, default false): A boolean indicating whether the output should be pretty-printed.
  • format (optional, default "json"): The response format. Currently, only "json" is supported.

Example:

{
    "pretty": true,
    "format": "json"
}

Example Usage

Executing a Simple GraphQL Query

Request
{
    "id": 1,
    "method": "graphql",
    "params": [ "{ users { id name } }" ]
}
Response
{
    "id": 1,
    "result": {
        "data": {
            "users": [
                { "id": "user:1", "name": "Alice" },
                { "id": "user:2", "name": "Bob" }
            ]
        }
    }
}

Executing a GraphQL Query with Variables and Operation Name

Request
{
    "id": 1,
    "method": "graphql",
    "params": [
        {
            "query": "query GetUser($id: ID!) { user(id: $id) { id name } }",
            "variables": { "id": "user:1" },
            "operationName": "GetUser"
        }
    ]
}
Response
{
    "id": 1,
    "result": {
        "data": {
            "user": { "id": "user:1", "name": "Alice" }
        }
    }
}

Executing a GraphQL Query with Options

Request
{
    "id": 1,
    "method": "graphql",
    "params": [
        "{ users { id name } }",
        { "pretty": true }
    ]
}
Response
{
    "id": 1,
    "result": "{\n    \"data\": {\n        \"users\": [\n            { \"id\": \"user:1\", \"name\": \"Alice\" },\n            { \"id\": \"user:2\", \"name\": \"Bob\" }\n        ]\n    }\n}"
}

Notes

  • GraphQL Support: This method requires GraphQL support to be enabled in the database configuration. If not enabled, you will receive a MethodNotFound error.
  • Format Options: Currently, only the "json" format is supported. Using "cbor" will result in an error.
  • Pretty Output: Setting pretty to true formats the JSON response with indentation for readability.
Important

Ensure that your GraphQL queries and variables are correctly formatted to avoid parsing errors.


info

This method returns the record of an authenticated record user.

Method Syntax
info

Example usage

Request
{
    "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.

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

insert

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

Method Syntax
insert [ thing, data ]

Parameters

ParameterDescription
thing required

The table to insert in to

data optional

One or multiple record(s)

Example usage

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

Bulk insert

Request
{
    "id": 1,
    "method": "insert",
    "params": [
        "person",
        [
            {
                "name": "Mary Doe"
            },
            {
                "name": "John Doe"
            }
        ]
    ]
}
Response
{
    "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.

Method Syntax
insert_relation [ table, data ]

Parameters

ParameterDescription
table required

The name of the relation table to insert into. If null or none, the table is determined from the id field in the data.

data required

An object containing the data for the new relation record, including in, out, and any additional fields.

Example Usage

Inserting a Relation into a Specified Table

Request
{
    "id": 1,
    "method": "insert_relation",
    "params": [
        "likes",                   // (relation table)
        {                          // data
            "in": "user:alice",
            "out": "post:123",
            "since": "2024-09-15T12:34:56Z"
        }
    ]
}
Response
{
    "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.

Request
{
    "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"
        }
    ]
}
Response
{
    "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:

Request with missing parameters
{
    "id": 3,
    "method": "insert_relation",
    "params": [
        "likes"  // Missing the data parameter
    ]
}
Response
{
    "id": 3,
    "error": {
        "code": -32602,
        "message": "Invalid parameters"
    }
}

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

Request
{
    "id": 4,
    "method": "insert_relation",
    "params": [
        "friendship",              // table (relation table)
        {                          // data
            "in": "user:alice",
            "out": "user:bob",
            "since": "2024-09-15"
        }
    ]
}
Response
{
    "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.

The insert_relation method is a powerful way to insert new relation records into your database, allowing you to specify the relation table and include detailed data for each relation. By understanding the parameters and how the method operates, you can effectively manage relationships between records in your database.

Note

This method is particularly useful in databases that support graph-like relations, enabling complex data modeling and querying capabilities.


invalidate

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

Method Syntax
invalidate

Example usage

Request
{
    "id": 1,
    "method": "invalidate"
}
Response
{
    "id": 1,
    "result": null
}

kill websocket only

This method kills an active live query

Method Syntax
kill [ queryUuid ]

Parameters

ParameterDescription
queryUuid required

The UUID of the live query to kill

Example usage

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

let websocket only

This method stores a variable on the current connection.

Method Syntax
let [ name, value ]

Parameters

ParameterDescription
name required

The name for the variable without a prefixed $ character

value required

The value for the variable

Example usage

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

live websocket only

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

Method Syntax
live[ table ]
Important

For more advanced live queries where filters are needed, use the Query method to initiate a custom live query.

Parameters

ParameterDescription
table required

The table to initiate a live query for

diff optional

If set to true, live notifications will contain an array of JSON Patches instead of the entire record

Example usage

Request
{
    "id": 1,
    "method": "live",
    "params": [ "person" ]
}
Response
{
    "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"
        }
    }
}

merge

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

Method Syntax
merge [ thing, data ]
Note

This function merges the current document / record data with the specified data. If no merge data is passed it will simply trigger an update.

Parameters

ParameterDescription
thing required

The thing (Table or Record ID) to merge into

data optional

The content of the record

Example usage

Request
{
    "id": 1,
    "method": "merge",
    "params": [
        "person",
        {
            "active": true
        }
    ]
}
Response
{
  "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.

Method Syntax
patch [ thing, patches, diff ]
Note

This function patches the current document / record data with the specified JSON Patch data.

Parameters

ParameterDescription
thing required

The thing (Table or Record ID) to patch

patches required

An array of patches following the JSON Patch specification

diff optional

A boolean representing if just a diff should be returned.

Example usage

Request
{
    "id": 1,
    "method": "patch",
    "params": [
        "person",
        [
            { "op": "replace", "path": "/last_updated", "value": "2023-06-16T08:34:25Z" }
        ]
    ]
}
Response
{
    "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

Method Syntax
ping

Example usage

Request
{
    "id": 1,
    "method": "ping",
}
Response
{
  "id": 1,
  "result": null
}

query

This methods sends a custom SurrealQL query.

Method Syntax
query [ sql, vars ]

Parameters

ParameterDescription
sql required

The query to execute against SurrealDB

vars optional

A set of variables used by the query

Example usage

Request
{
    "id": 1,
    "method": "query",
    "params": [
        "CREATE person SET name = 'John'; SELECT * FROM type::table($tb);",
        {
            "tb": "person"
        }
    ]
}
Response
{
  "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"
              }
          ]
      }
  ]
}

relate

Available since: v1.5.0

This method relates two records with a specified relation.

Method Syntax
relate [ in, relation, out, data? ]

Parameters

ParameterDescription
in required

The record to relate to

relation required

The relation table

out required

The record to relate from

data optional

The content of the record

Example usage

Request
{
    "id": 1,
    "method": "relate",
    "params": [
        "person:12s0j0bbm3ngrd5c9bx53",
        "knows",
        "person:8s0j0bbm3ngrd5c9bx53"
    ]
}
Response
{
    "id": 1,
    "result": {
        "id": "knows:12s0j0bbm3ngrd5c9bx53:8s0j0bbm3ngrd5c9bx53",
        "in": "person:12s0j0bbm3ngrd5c9bx53",
        "out": "person:8s0j0bbm3ngrd5c9bx53"
    }
}

Creating a Relation With Additional Data

Request
{
    "id": 2,
    "method": "relate",
    "params": [
        "person:john_doe",          // in
        "knows",                    // relation
        "person:jane_smith",        // out
        { "since": "2020-01-01" }   // data
    ]
}
Response
{
    "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.

Method Syntax
reset

Example usage

Request
{
    "id": 1,
    "method": "reset"
}
Response
{
    "id": 1,
    "result": null
}

run

This method allows you to execute built-in functions, custom functions, or machine learning models with optional arguments.

Method Syntax
run [ func_name, version?, args? ]

Parameters

ParameterDescription
func_name required

The name of the function or model to execute. Prefix with fn:: for custom functions or ml:: for machine learning models.

version optional

The version of the function or model to execute.

args optional

The arguments to pass to the function or model.

Executing a built-in function

Request
{
    "id": 1,
    "method": "run",
    "params": [ "time::now" ]
}
Response
{
    "id": 1,
    "result": "2024-09-15T12:34:56Z"
}

Executing a custom function

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

Executing a machine learning model

Request
{
    "id": 1,
    "method": "run",
    "params": [ "ml::image_classifier", "v2.1", [ "image_data_base64" ] ]
}
Response
{
    "id": 1,
    "result": "cat"
}
Important

When using a machine learning model (prefixed with ml::), the version parameter is required.


select

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

Method Syntax
select [ thing ]

Parameters

ParameterDescription
thing required

The thing (Table or Record ID) to select

Example usage

Request
{
    "id": 1,
    "method": "select",
    "params": [ "person" ]
}
Response
{
    "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.

Important

Unlike v1, v2 returns an object containing a token property and an optional refresh property.

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

Parameters

ParameterDescription
NS required

The namespace to sign in to. Only required for DB & RECORD authentication

DB required

The database to sign in to. Only required for RECORD authentication

AC required

Specifies the access method. Only required for RECORD authentication

user required

The username of the database user. Only required for ROOT, NS & DB authentication

pass required

The password of the database user. Only required for ROOT, NS & DB authentication

…

Specifies any variables to pass to the SIGNIN query. Only relevant for RECORD authentication

Example with Root user

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

Example with Record user

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

            "username": "johndoe",
            "password": "SuperStrongPassword!"
        }
    ]
}
Response
{
    "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.

Important

Unlike v1, v2 returns an object containing an optional token property and an optional refresh property.

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

Parameters

ParameterDescription
NS required

Specifies the namespace of the record access method

DB required

Specifies the database of the record access method

AC required

Specifies the access method

… required

Specifies any variables used by the SIGNUP query of the record access method

Example usage

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

            "username": "johndoe",
            "password": "SuperStrongPassword!"
        }
    ]
}
Response
{
  "id": 1,
  "result": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJTdXJyZWFsREIiLCJpYXQiOjE1MTYyMzkwMjIsIm5iZiI6MTUxNjIzOTAyMiwiZXhwIjoxODM2NDM5MDIyLCJOUyI6InRlc3QiLCJEQiI6InRlc3QiLCJTQyI6InVzZXIiLCJJRCI6InVzZXI6dG9iaWUifQ.N22Gp9ze0rdR06McGj1G-h2vu6a6n9IVqUbMFJlOxxA"
}

unset websocket only

This method removes a variable from the current connection.

Method Syntax
unset [ name ]

Parameters

ParameterDescription
name required

The name of the variable without a prefixed $ character

Example usage

Request
{
    "id": 1,
    "method": "unset",
    "params": [ "website" ]
}
Response
{
    "id": 1,
    "result": null
}

update

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

Method Syntax
update [ thing, data ]
Note

This function replaces the current document / record data with the specified data if that document / record has already been created. If no document has been created this will return an empty array. Also, if no replacement data is passed it will simply trigger an update.

Parameters

ParameterDescription
thing required

The thing (Table or Record ID) to update

data optional

The content of the record

Example usage

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

upsert

Method Syntax
upsert [ thing, data ]

Parameters

ParameterDescription
thing required

The thing (Table or Record ID) to upsert

data optional

The content of the record

Example usage

Request
{
    "id": 1,
    "method": "upsert",
    "params": [
        "person:12s0j0bbm3ngrd5c9bx53",
        {
            "name": "John Doe",
            "job": "Software developer",
        }
    ]
}
Response
{
    "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.

Method Syntax
use [ ns, db ]

Parameters

ParameterDescription
NS required

Sets the selected Namespace for queries

DB required

Sets the selected Database for queries

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

Request
{
    "id": 1,
    "method": "use",
    "params": [ "surrealdb", "docs" ]
}
Response
{
    "id": 1,
    "result": null
}
Example Combinations
[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.

Method Syntax
version

Parameters

This method does not accept any parameters.

Example Usage

Request
{
    "id": 1,
    "method": "version"
}
Response
{
    "id": 1,
    "result": {
        "version": "2.0.0-beta.2",
        "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.
Note

The actual values in the response will depend on your specific database/server instance.


Edit this page on GitHub
HTTP & RestCBOR Protocol