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:
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.
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:
| Function | Description |
|---|
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 |
info | Returns 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 |
invalidate | Invalidate 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 |
ping | Sends 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 |
reset | Resets 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 |
version | Returns 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
| Parameter | Description |
|---|
token required | 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
| Parameter | Description |
|---|
thing required | The thing (Table or Record ID) to create. Passing just a table will result in a randomly generated ID |
data optional | 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
| Parameter | Description |
|---|
record_id required | 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
| Parameter | Description |
|---|
thing required | The table to insert in to |
data optional | 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
| Parameter | Description |
|---|
table required | 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 required | 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
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
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.
This method is particularly useful in databases that support graph-like relations, enabling complex data modeling and querying capabilities.
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
| Parameter | Description |
|---|
name required | The name for the variable without a prefixed $ character |
value required | The value for the variable |
Example usage
Request
{
"id": 1,
"method": "let",
"params": [ "website", "https://surrealdb.com/" ]
}
Response
{
"id": 1,
"result": null
}
live websocket only
This methods initiates a live query for a specified table name.
Method Syntax
live[ table ]
For more advanced live queries where filters are needed, use the Query method to initiate a custom live query.
Parameters
| Parameter | Description |
|---|
table required | The table to initiate a live query for |
diff optional | 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 ]
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
| Parameter | Description |
|---|
thing required | The thing (Table or Record ID) to merge into |
data optional | 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 ]
This function patches the current document / record data with the specified JSON Patch data.
Parameters
| Parameter | Description |
|---|
thing required | The thing (Table or Record ID) to patch |
patches required | An array of patches following the JSON Patch specification |
diff optional | 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
| Parameter | Description |
|---|
sql required | The query to execute against SurrealDB |
vars optional | 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
| Parameter | Description |
|---|
in required | The record to relate to |
relation required | The relation table |
out required | The record to relate from |
data optional | 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
| Parameter | Description |
|---|
func_name required | The name of the function or model to execute. Prefix with fn:: for custom functions or ml:: for machine learning models. |
version optional | The version of the function or model to execute. |
args optional | 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"
}
When using a machine learning model (prefixed with ml::), the version parameter is required.
select
This method selects either all records in a table or a single record.
Method Syntax
select [ thing ]
Parameters
| Parameter | Description |
|---|
thing required | 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
| Parameter | Description |
|---|
NS required | The namespace to sign in to. Only required for DB & RECORD authentication |
DB required | The database to sign in to. Only required for RECORD authentication |
AC required | Specifies the access method. Only required for RECORD authentication |
user required | The username of the database user. Only required for ROOT, NS & DB authentication |
pass required | 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
| Parameter | Description |
|---|
NS required | Specifies the namespace of the record access method |
DB required | Specifies the database of the record access method |
AC required | Specifies the access method |
… required | 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 websocket only
This method removes a variable from the current connection.
Method Syntax
unset [ name ]
Parameters
| Parameter | Description |
|---|
name required | 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 ]
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
| Parameter | Description |
|---|
thing required | The thing (Table or Record ID) to update |
data optional | 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
| Parameter | Description |
|---|
thing required | The thing (Table or Record ID) to upsert |
data optional | 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
| Parameter | Description |
|---|
NS required | Sets the selected Namespace for queries |
DB required | 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]
["test", none]
[none, "test"]
["test", "test"]
[none, null]
[null, none]
[null, null]
["test", null]
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.
The actual values in the response will depend on your specific database/server instance.
