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.

Supported methods

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

use

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

Method Syntax
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

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

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

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.

signup

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

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

Parameters

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

signin

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

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

Parameters

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

authenticate

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

Method Syntax
authenticate [ token ]

Parameters

Example usage

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

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

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
}

let websocket only

This method stores a variable on the current connection

Method Syntax
let [ name, value ]

Parameters

Example usage

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

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

unset websocket only

This method removes a variable from the current connection

Method Syntax
unset [ name ]

Parameters

Example usage

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

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

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

kill websocket only

This method kills an active live query

Method Syntax
kill [ queryUuid ]

Parameters

Example usage

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

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

query

This methods sends a custom SurrealQL query

Method Syntax
query [ sql, vars ]

Parameters

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

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

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.

graphql

Available since: v2.0.0

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

Method Syntax
graphql [ query, options? ]

Parameters

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.

select

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

Method Syntax
select [ thing ]

Parameters

Example usage

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

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

create

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

Method Syntax
create [ thing, data ]

Parameters

Example usage

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

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

insert

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

Method Syntax
insert [ thing, data ]

Parameters

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

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.

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

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

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

relate

Available since: v1.5.0

This method relates two records with a specified relation

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

Parameters

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

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

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

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

delete

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

Method Syntax
delete [ thing ]

Parameters

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