# RPC protocol The RPC protocol allows for easy bidirectional communication with SurrealDB. 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](./cbor) 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`](#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`](#unset-) method to remove a previously defined variable from the session. * The [`reset`](#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`](#query), [`select`](#select), [`insert`](#insert), [`create`](#create), [`upsert`](#upsert), [`update`](#update), [`relate`](#relate), and [`delete`](#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

## Message size limits How much a single RPC call may carry depends on the transport it arrives over. | Transport | Default limit | Environment variable | | --------- | ------------- | -------------------- | | WebSocket `/rpc` | 128 MiB per message | `SURREAL_WEBSOCKET_MAX_MESSAGE_SIZE` | | HTTP `POST /rpc` | 4 MiB per request body | `SURREAL_HTTP_MAX_RPC_BODY_SIZE` | The WebSocket ceiling is roughly thirty times the HTTP one, which is why the SDKs default to the WebSocket engine. If a payload is rejected over HTTP, moving the same call onto a WebSocket connection is usually enough. ### Server and client limits The values above are what the **server** accepts. An SDK may also enforce its own limit on **outgoing** messages, and that limit is applied before anything reaches the network. The effective ceiling is therefore whichever of the two is lower. The Rust SDK defaults to 64 MiB per message. Sending more than that produces a `Message too long` error from the client itself, not a rejection from the server. The limit is configurable: ```rust use surrealdb::engine::remote::ws::Ws; use surrealdb::opt::{Config, WebsocketConfig}; use surrealdb::Surreal; let websocket = WebsocketConfig::new().max_message_size(128 << 20); // 128 MiB let config = Config::new().websocket(websocket)?; let db = Surreal::new::(("127.0.0.1:8000", config)).await?; ``` Raising a client limit above the server's ceiling does not help, as the server still rejects the message. Raise both in this case, or keep messages under the lower of the two. For request bodies on the other HTTP endpoints, see [Request size limits](/docs/reference/rest-api/http-protocol.md#request-size-limits).
## `authenticate` This method allows you to authenticate a user against SurrealDB with a token. ```json title="Method Syntax" authenticate [ token ] ``` ### Parameters
Parameter Description
token The token that authenticates the user
### Example usage ```json title="Request" { "id": 1, "method": "authenticate", "params": [ "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJTdXJyZWFsREIiLCJpYXQiOjE1MTYyMzkwMjIsIm5iZiI6MTUxNjIzOTAyMiwiZXhwIjoxODM2NDM5MDIyLCJOUyI6InRlc3QiLCJEQiI6InRlc3QiLCJTQyI6InVzZXIiLCJJRCI6InVzZXI6dG9iaWUifQ.N22Gp9ze0rdR06McGj1G-h2vu6a6n9IVqUbMFJlOxxA" ] } ``` ```json title="Response" { "id": 1, "result": null } ```
## `create` This method creates a record either with a random or specified ID. ```json title="Method Syntax" create [ thing, data ] ``` ### 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 ```json title="Request" { "id": 1, "method": "create", "params": [ "person", { "name": "Mary Doe" } ] } ``` ```json title="Response" { "id": 1, "result": [ { "id": "person:s5fa6qp4p8ey9k5j0m9z", "name": "Mary Doe" } ] } ```
## `delete` This method deletes either all records in a table or a single record. ```json title="Method Syntax" delete [ thing ] ``` ### Parameters
Parameter Description
record_id The record_id (Table or Record ID) to delete
### Example usage ```json title="Request" { "id": 1, "method": "delete", "params": [ "person:8s0j0bbm3ngrd5c9bx53" ] } ``` Notice how the deleted record is returned. This differs from a [`DELETE`](/docs/reference/query-language/statements/delete.md) statement via the CLI or SurrealDB Studio which returns nothing unless the `RETURN BEFORE` clause is used. ```json title="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. ```json title="Method Syntax" info ``` ### Example usage ```json title="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. ```json title="Response" { "id": 1, "result": { "id": "user:john", "name": "John Doe" } } ```
## `insert` This method creates a record either with a random or specified ID. ```json title="Method Syntax" insert [ thing, data ] ``` ### Parameters
Parameter Description
thing The table to insert in to
data One or multiple record(s)
### Example usage ```json title="Request" { "id": 1, "method": "insert", "params": [ "person", { "name": "Mary Doe" } ] } ``` ```json title="Response" { "id": 1, "result": [ { "id": "person:s5fa6qp4p8ey9k5j0m9z", "name": "Mary Doe" } ] } ``` ### Bulk insert ```json title="Request" { "id": 1, "method": "insert", "params": [ "person", [ { "name": "Mary Doe" }, { "name": "John Doe" } ] ] } ``` ```json title="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. ```json title="Method Syntax" insert_relation [ table, data ] ``` ### 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** ```json title="Request" { "id": 1, "method": "insert_relation", "params": [ "likes", // (relation table) { // data "in": "user:alice", "out": "post:123", "since": "2024-09-15T12:34:56Z" } ] } ``` ```json title="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`. ```json title="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" } ] } ``` ```json title="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:** ```json title="Request with missing parameters" { "id": 3, "method": "insert_relation", "params": [ "likes" // Missing the data parameter ] } ``` ```json title="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** ```json title="Request" { "id": 4, "method": "insert_relation", "params": [ "friendship", // table (relation table) { // data "in": "user:alice", "out": "user:bob", "since": "2024-09-15" } ] } ``` ```json title="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. > [!NOTE] > This method is particularly useful in databases that support graph-like relations, enabling complex data modelling and querying capabilities.
## `invalidate` This method will invalidate the user's session for the current connection. ```json title="Method Syntax" invalidate ``` ### Example usage ```json title="Request" { "id": 1, "method": "invalidate" } ``` ```json title="Response" { "id": 1, "result": null } ```
## `let`