Click here to sign up to SurrealDB Cloud
Back to top
Documentation Integration WebSocket (text protocol)

WebSocket (text protocol)

The WebSocket 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!

Live queries are still under development, though available soon. Checkout this livestream to learn more about Live Queries.
Method Description
use [ ns, db ] Specifies the namespace and database for the current connection
info Returns the record of an authenticated scope user
signup [ NS, DB, SC, ... ] Signup a user against a scope's SIGNUP method
signin [ ... ] Signin a root, NS, DB or SC user against SurrealDB
authenticate [ token ] Authenticate a user against SurrealDB with a token
invalidate Invalidate 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 ] 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 [ ns, db ] method

This method specifies the namespace and database for the current connection

Parameter Description
ns Required Specifies the namespace to use
db Required Specifies the namespace to use

Example message

{
    "id": 1,
    "method": "use",
    "params": [ "surrealdb", "docs" ]
}

Response

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

info method

This method returns the record of an authenticated scope user.

Example message

{
    "id": 1,
    "method": "info"
}

Response

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.

{
    "id": 1,
    "result": {
        "id": "user:john",
        "name": "John Doe"
    }
}

signup [ NS, DB, SC, ... ] method

This method allows you to signup a user against a scope's SIGNUP method

Parameter Description
NS Required Specifies the namespace of the scope
DB Required Specifies the database of the scope
SC Required Specifies the scope
... Specifies any variables used by the scope's SIGNUP method

Example message

{
    "id": 1,
    "method": "signup",
    "params": [
        {
            "NS": "surrealdb",
            "DB": "docs",
            "SC": "commenter",

            "username": "johndoe",
            "password": "SuperStrongPassword!"
        }
    ]
}

Response

{
  "id": 1,
  "result": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJTdXJyZWFsREIiLCJpYXQiOjE1MTYyMzkwMjIsIm5iZiI6MTUxNjIzOTAyMiwiZXhwIjoxODM2NDM5MDIyLCJOUyI6InRlc3QiLCJEQiI6InRlc3QiLCJTQyI6InVzZXIiLCJJRCI6InVzZXI6dG9iaWUifQ.N22Gp9ze0rdR06McGj1G-h2vu6a6n9IVqUbMFJlOxxA"
}

signin [ NS, DB, SC, ... ] method

This method allows you to signin a root, NS, DB or SC user against SurrealDB

Parameter Description
NS Required for DB & SC The namespace to sign in to
DB Required for SC The database to sign in to
SC The scope to sign in to.
user Required for root, NS & DB The username of the database user
pass Required for root, NS & DB The password of the database user
... Specifies any variables used by the scope's SIGNIN method

Example message

Down below follow two example messages

Signin as root
{
    "id": 1,
    "method": "signin",
    "params": [
        {
            "user": "tobie",
            "pass": "3xtr3m3ly-s3cur3-p@ssw0rd"
        }
    ]
}

Response

{
    "id": 1,
    "result": null
}
Signin as scope
{
    "id": 1,
    "method": "signin",
    "params": [
        {
            "NS": "surrealdb",
            "DB": "docs",
            "SC": "commenter",

            "username": "johndoe",
            "password": "SuperStrongPassword!"
        }
    ]
}

Response

{
    "id": 1,
    "result": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJTdXJyZWFsREIiLCJpYXQiOjE1MTYyMzkwMjIsIm5iZiI6MTUxNjIzOTAyMiwiZXhwIjoxODM2NDM5MDIyLCJOUyI6InRlc3QiLCJEQiI6InRlc3QiLCJTQyI6InVzZXIiLCJJRCI6InVzZXI6dG9iaWUifQ.N22Gp9ze0rdR06McGj1G-h2vu6a6n9IVqUbMFJlOxxA"
}

authenticate [ token ] method

This method allows you to authenticate a user against SurrealDB with a token

Parameter Description
token Required The token that authenticates the user

Example message

{
    "id": 1,
    "method": "authenticate",
    "params": [ "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJTdXJyZWFsREIiLCJpYXQiOjE1MTYyMzkwMjIsIm5iZiI6MTUxNjIzOTAyMiwiZXhwIjoxODM2NDM5MDIyLCJOUyI6InRlc3QiLCJEQiI6InRlc3QiLCJTQyI6InVzZXIiLCJJRCI6InVzZXI6dG9iaWUifQ.N22Gp9ze0rdR06McGj1G-h2vu6a6n9IVqUbMFJlOxxA" ]
}

Response

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

invalidate method

This method will invalidate the user's session for the current connection

Example message

{
    "id": 1,
    "method": "invalidate"
}

Response

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

let [ name, value ] method

This method stores a variable on the current connection

Parameter Description
name Required The name for the variable without a prefixed $ character
value Required The value for the variable

Example message

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

Response

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

unset [ name ] method

This method removes a variable from the current connection

Parameter Description
name Required The name of the variable without a prefixed $ character

Example message

{
    "id": 1,
    "method": "unset",
    "params": [ "website" ]
}

Response

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

live [ table ] method

This methods initiates a live query for a specified table name

For more advanced live queries where filters are needed, use the Query method to initiate a custom live query.
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 message

{
    "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 [ queryUuid ] method

This methods kills an active live query

Parameter Description
queryUuid Required The UUID of the live query to kill

Example message

{
    "id": 1,
    "method": "kill",
    "params": [ "0189d6e3-8eac-703a-9a48-d9faa78b44b9" ]
}

Response

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

query [ sql, vars ] method

This method executes a custom query against SurrealDB

Parameter Description
sql Required The query to execute against SurrealDB
vars Optional A set of variables used by the query

Example message

{
    "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 [ thing ] method

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

Parameter Description
thing Required The thing (Table or Record ID) to select

Example message

{
    "id": 1,
    "method": "select",
    "params": [ "person" ]
}

Response

{
    "id": 1,
    "result": [
        {
            "id": "person:8s0j0bbm3ngrd5c9bx53",
            "name": "John"
        }
    ]
}

create [ thing, data ] method

This method creates a record either with a random or specified ID

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 message

{
    "id": 1,
    "method": "create",
    "params": [
        "person",
        {
            "name": "Mary Doe"
        }
    ]
}

Response

{
    "id": 1,
    "result": [
        {
            "id": "person:s5fa6qp4p8ey9k5j0m9z",
            "name": "Mary Doe"
        }
    ]
}

insert [ thing, data ] method

This method inserts one or multiple records in a table

Parameter Description
thing Required The table to insert in to
data Optional One or multiple record(s)

Example message

{
    "id": 1,
    "method": "insert",
    "params": [
        "person",
        {
            "name": "Mary Doe"
        }
    ]
}
{
    "id": 1,
    "result": [
        {
            "id": "person:s5fa6qp4p8ey9k5j0m9z",
            "name": "Mary Doe"
        }
    ]
}

Bulk insert

{
    "id": 1,
    "method": "insert",
    "params": [
        "person",
        [
            {
                "name": "Mary Doe"
            },
            {
                "name": "John Doe"
            }
        ]
    ]
}
{
    "id": 1,
    "result": [
        {
            "id": "person:s5fa6qp4p8ey9k5j0m9z",
            "name": "Mary Doe"
        },
        {
            "id": "person:xtbbojcm82a97vus9x0j",
            "name": "John Doe"
        }
    ]
}

update [ thing, data ] method

This method replaces either all records in a table or a single record with specified data

This function replaces the current document / record data with the specified data. If no replacement data is passed it will simply trigger an update.
Parameter Description
thing Required The thing (Table or Record ID) to update
data Optional The new content of the record

Example message

{
    "id": 1,
    "method": "update",
    "params": [
        "person:8s0j0bbm3ngrd5c9bx53",
        {
            "name": "John Doe"
        }
    ]
}

Response

{
    "id": 1,
    "result": {
        "id": "person:8s0j0bbm3ngrd5c9bx53",
        "name": "John Doe"
    }
}

merge [ thing, data ] method

This method merges specified data into either all records in a table or a single record

This function merges the current document / record data with the specified data. If no merge data is passed it will simply trigger an update.
Parameter Description
thing Required The thing (Table or Record ID) to merge into
data Optional The content to be merged

Example message

{
    "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 [ thing, patches, diff ] method

This method patches either all records in a table or a single record with specified patches

This function patches the current document / record data with the specified JSON Patch data.
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 message

{
    "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 [ thing ] method

This method deletes either all records in a table or a single record

Parameter Description
thing Required The thing (Table or Record ID) to delete

Example message

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

Response

Notice how the deleted record is being returned here

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