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
letmethod 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
unsetmethod to remove a previously defined variable from the session.The
resetmethod, in addition to its other functions, clears all currently defined session variables, restoring the session's variable state.
Implicit Request-Scoped Management:
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.
Parameters
| Parameter | Description |
|---|---|
token
| The token that authenticates the user |
Example usage
create
This method creates a record either with a random or specified ID.
Parameters
| Parameter | Description |
|---|---|
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
delete
This method deletes either all records in a table or a single record.
Parameters
| Parameter | Description |
|---|---|
record_id
| The record_id (Table or Record ID) to delete |
Example usage
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.
info
This method returns the record of an authenticated record user.
Example usage
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.
insert
This method creates a record either with a random or specified ID.
Parameters
| Parameter | Description |
|---|---|
thing
| The table to insert in to |
data
| One or multiple record(s) |
Example usage
Bulk insert
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.
Parameters
| Parameter | Description |
|---|---|
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
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.
Notes
tableparameter:Specifies the relation table into which the new relation record will be inserted.
If
tableisnullornone, the method expects thedatato contain anidfrom which it can infer the relation table.
dataparameter:Must include at least the
inandoutfields, representing the starting and ending points of the relation.Can include additional fields to store more information within the relation.
Relation IDs:
If an
idis provided in thedata, it will be used as the identifier for the new relation record.If no
idis provided, the system may generate one based on thetable,in, andoutfields.
Single vs. multiple inserts:
The method primarily handles single relation inserts.
The
onevariable in the code determines if thetableparameter refers to a single item.
Error Handling
Invalid parameters:
If you provide fewer than two parameters or incorrect parameter types, you will receive an
InvalidParamserror.The method expects exactly two parameters:
tableanddata.
Example of invalid parameters:
Best practices
Include
inandoutFields:Always provide the
inandoutfields in yourdatato define the relation endpoints.
Specifying the Relation Table:
If possible, specify the
tableparameter to clearly indicate the relation table.If not specified, ensure that the
idindatacorrectly reflects the desired relation table.
Providing an
idindata:If you want to control the
idof the relation, include it in thedata.This is especially important when
tableisnullornone.
Additional examples
Inserting a Relation with Auto-Generated ID
Notes:
The
idis generated based on thetable,in, andoutfields.The relation is inserted into the
friendshiptable.
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.
Note
invalidate
This method will invalidate the user's session for the current connection.
Example usage
let <label label="websocket only" />
This method stores a variable on the current connection.
Parameters
| Parameter | Description |
|---|---|
name
| The name for the variable without a prefixed $ character |
value
| The value for the variable |
Example usage
live <label label="websocket only" />
This methods initiates a live query for a specified table name.
Important
Parameters
| Parameter | Description |
|---|---|
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
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.
merge
This method merges specified data into either all records in a table or a single record.
Note
Parameters
| Parameter | Description |
|---|---|
thing
| The thing (Table or Record ID) to merge into |
data
| The content of the record |
Example usage
patch
This method patches either all records in a table or a single record with specified patches.
Note
Parameters
| Parameter | Description |
|---|---|
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
ping
Example usage
query
This methods sends a custom SurrealQL query.
Parameters
| Parameter | Description |
|---|---|
sql
| The query to execute against SurrealDB |
vars
| A set of variables used by the query |
Example usage
relate
This method relates two records with a specified relation.
Parameters
| Parameter | Description |
|---|---|
in
| The record to relate to |
relation
| The relation table |
out
| The record to relate from |
data
| The content of the record |
Example usage
Creating a Relation With Additional Data
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.
Example usage
run
This method allows you to execute built-in functions, custom functions, or machine learning models with optional arguments.
Parameters
| Parameter | Description |
|---|---|
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
Executing a custom function
Executing a machine learning model
Important
select
This method selects either all records in a table or a single record.
Parameters
| Parameter | Description |
|---|---|
thing
| The thing (Table or Record ID) to select |
Example usage
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.
Parameters
| Parameter | Description |
|---|---|
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
Example with Record user
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.
Parameters
| Parameter | Description |
|---|---|
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
unset <label label="websocket only" />
This method removes a variable from the current connection.
Parameters
| Parameter | Description |
|---|---|
name
| The name of the variable without a prefixed $ character |
Example usage
update
This method replaces either all records in a table or a single record with specified data.
Note
Parameters
| Parameter | Description |
|---|---|
thing
| The thing (Table or Record ID) to update |
data
| The content of the record |
Example usage
upsert
Parameters
| Parameter | Description |
|---|---|
thing
| The thing (Table or Record ID) to upsert |
data
| The content of the record |
Example usage
use
This method specifies or unsets the namespace and/or database for the current connection.
Parameters
| Parameter | Description |
|---|---|
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
version
This method returns version information about the database/server.
Parameters
This method does not accept any parameters.
Example usage
Notes
Parameters: Providing any parameters will result in an
InvalidParamserror.Result Fields:
version: The version number of the database/server.build: The build identifier.timestamp: The timestamp when the version was built or released.