Skip to main content

RPC Protocol

The RPC protocol allows for easy bi-directional communication with SurrealDB. This allows you to maintain a single connection to run all your queries, but also opens up the possibility of Live Queries!

FunctionDescription
use [ ns, db ]Specifies the namespace and database for the current connection
infoReturns the record of an authenticated scope user
signup [ NS, DB, SC, ... ]Signup a user against a scope's SIGNUP method
signin [ ... ]Signin a root, NS, DB or SC user against SurrealDB
authenticate [ token ]Authenticate a user against SurrealDB with a token
invalidateInvalidate a user's session for the current connection
let [ name, value ]Define a variable on the current connection
unset [ name ]Remove a variable from the current connection
live [ table, diff ]Initiate a live query
kill [ queryUuid ]Kill an active live query
query [ sql, vars ]Execute a custom query with optional variables
select [ thing ]Select either all records in a table or a single record
create [ thing, data ]Create a record with a random or specified ID
insert [ thing, data ]Insert one or multiple records in a table
update [ thing, data ]Replace either all records in a table or a single record with specified data
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
delete [ thing ]Delete either all records in a table or a single record

use​

This method specifies the namespace and database for the current connection

Method Syntax
use [ ns, db ]

Parameters​

ParameterDescription
NSOPTIONAL

Sets the selected Namespace for queries

DBOPTIONAL

Sets the selected Database for queries

Example usage​

Request
{
    "id": 1,
    "method": "use",
    "params": [ "surrealdb", "docs" ]
}
Response
{
    "id": 1,
    "result": null
}

info​

This method returns the record of an authenticated scope 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"
    }
}

signup​

This method allows you to signup a user against a scope's SIGNUP method

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

Parameters​

ParameterDescription
NSREQUIRED

Specifies the namespace of the scope

DBREQUIRED

Specifies the database of the scope

SCREQUIRED

Specifies the scope

...REQUIRED

Specifies any variables used by the scope's SIGNUP method

Example usage​

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

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

signin​

This method allows you to signin a root, NS, DB or SC user against SurrealDB

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

Parameters​

ParameterDescription
NSREQUIRED FOR DB & SC

The namespace to sign in to

DBREQUIRED FOR SC

The database to sign in to

SC

Specifies the scope

userREQUIRED FOR ROOT, NS & DB

The username of the database user

passREQUIRED FOR ROOT, NS & DB

The password of the database user

...

Specifies any variables used by the scope's SIGNUP method

Example with Root user​

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

Example with Scope user​

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

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

authenticate​

This method specifies the namespace and database for the current connection

Method Syntax
authenticate [ token ]

Parameters​

ParameterDescription
tokenREQUIRED

The token that authenticates the user

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 specifies the namespace and database for the current connection

Method Syntax
let [ name, value ]

Parameters​

ParameterDescription
nameREQUIRED

The name for the variable without a prefixed $ character

valueREQUIRED

The value for the variable

Example usage​

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

unset websocket only​

This method specifies the namespace and database for the current connection

Method Syntax
unset [ name ]

Parameters​

ParameterDescription
nameREQUIRED

The name of the variable without a prefixed $ character

Example usage​

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

live websocket only​

Method Syntax
live[ table ]

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

Parameters​

ParameterDescription
tableREQUIRED

The table to initiate a live query for

diffOPTIONAL

The value for the variable

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​

ParameterDescription
queryUuidREQUIRED

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
}

query​

This methods sends a custom SurrealQL query

Method Syntax
query [ sql, vars ]

Parameters​

ParameterDescription
sqlREQUIRED

The query to execute against SurrealDB

varsOPTIONAL

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

select​

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

Method Syntax
select [ thing ]

Parameters​

ParameterDescription
thingREQUIRED

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

create​

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

Method Syntax
create [ thing, data ]

Parameters​

ParameterDescription
thingREQUIRED

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

dataOPTIONAL

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

insert​

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

Method Syntax
insert [ thing, data ]

Parameters​

ParameterDescription
thingREQUIRED

The table to insert in to

dataOPTIONAL

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

update​

Method Syntax
update [ thing, data ]

NOTE: This function replaces the current document / record data with the specified data. If no replacement data is passed it will simply trigger an update.

Parameters​

ParameterDescription
thingREQUIRED

The thing (Table or Record ID) to update

dataOPTIONAL

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

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
thingREQUIRED

The thing (Table or Record ID) to merge into

dataREQUIRED

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
thingREQUIRED

The thing (Table or Record ID) to patch

patchesREQUIRED

An array of patches following the JSON Patch specification

diffOPTIONAL

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

delete​

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

Method Syntax
delete [ thing ]

Parameters​

ParameterDescription
thingREQUIRED

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"
    }
}
What's on your mind?

Create GitHub Issue

Quickest way to alert
our team of a problem.