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.

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
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 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 The thing (Table or Record ID) to create. Passing just a table will result in a randomly generated ID
data 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
record_id The record_id (Table or Record ID) to delete

Example usage

Request

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

Notice how the deleted record is returned. This differs from a DELETE statement via the CLI or Surrealist which returns nothing unless the RETURN BEFORE clause is used.

Response

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


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 The table to insert in to
data 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 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 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.


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 <label label="websocket only" />

This method stores a variable on the current connection.

Method Syntax

let [ name, value ]

Parameters

ParameterDescription
name The name for the variable without a prefixed $ character
value The value for the variable

Example usage

Request

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

Response

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


live <label label="websocket only" />

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

Method Syntax

live[ table ]

Parameters

ParameterDescription
table The table to initiate a live query for
diff 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 ]

Parameters

ParameterDescription
thing The thing (Table or Record ID) to merge into
data 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 ]

Parameters

ParameterDescription
thing The thing (Table or Record ID) to patch
patches An array of patches following the JSON Patch specification
diff 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 The query to execute against SurrealDB
vars 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

This method relates two records with a specified relation.

Method Syntax

relate [ in, relation, out, data? ]

Parameters

ParameterDescription
in The record to relate to
relation The relation table
out The record to relate from
data 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. reset your authentication (much like invalidate) unsets the selected NS/DB, unsets any defined connection params, and aborts any active live queries.

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 The name of the function or model to execute. Prefix with fn:: for custom functions or ml:: for machine learning models.
version The version of the function or model to execute.
args 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"
}


select

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

Method Syntax

select [ thing ]

Parameters

ParameterDescription
thing 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.

The object returned will contain a token property and an optional refresh property.

Method Syntax

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

Parameters

ParameterDescription
NS The namespace to sign in to. Only required for DB & RECORD authentication
DB The database to sign in to. Only required for RECORD authentication
AC Specifies the access method. Only required for RECORD authentication
user REQUIRED FOR ROOT, NS & DB The username of the database user. Only required for ROOT, NS & DB authentication
pass REQUIRED FOR ROOT, NS & DB 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.

The object returned will contain an optional token property and an optional refresh property.

Method Syntax

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

Parameters

ParameterDescription
NS Specifies the namespace of the record access method
DB Specifies the database of the record access method
AC Specifies the access method
... 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 <label label="websocket only" />

This method removes a variable from the current connection.

Method Syntax

unset [ name ]

Parameters

ParameterDescription
name 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 ]

Parameters

ParameterDescription
thing The thing (Table or Record ID) to update
data 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 The thing (Table or Record ID) to upsert
data 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 Sets the selected Namespace for queries
DB 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.