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