Skip to main content
Version: 2.x(alpha)

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 record user
signup [ NS, DB, AC, ... ]Signup a user using the SIGNUP query defined in a record access method
signin [ ... ]Signin a root, NS, DB or record 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 ]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
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 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"
    }
}

signup​

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

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

Parameters​

ParameterDescription
NSREQUIRED

Specifies the namespace of the record access method

DBREQUIRED

Specifies the database of the record access method

ACREQUIRED

Specifies the access method

...REQUIRED

Specifies any variables used by the SIGNUP query or 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"
}

signin​

This method allows you to signin as a root, NS, DB user or with an access method against SurrealDB

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

Parameters​

ParameterDescription
NSREQUIRED FOR DB & RECORD

The namespace to sign in to

DBREQUIRED FOR RECORD

The database to sign in to

AC

Specifies the access method

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 record'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",
            "AC": "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 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
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"
    }
}

upsert​

Method Syntax
upsert [ thing, data ]

Parameters​

ParameterDescription
thingREQUIRED

The thing (Table or Record ID) to upsert

dataOPTIONAL

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

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.