WebSocket

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.

Function	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

This method specifies the namespace and database for the current connection

Method Syntax

use [ ns, db ]

Parameters

Parameter		Description
NSOPTIONAL		Sets the selected Namespace for queries
DBOPTIONAL		Sets the selected Database for queries

Example usage

Request

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

Response

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

info

This method returns the record of an authenticated scope 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"
    }
}

signup

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

Method Syntax

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

Parameters

Parameter		Description
NSREQUIRED		Specifies the namespace of the scope
DBREQUIRED		Specifies the database of the scope
SCREQUIRED		Specifies the scope
...REQUIRED		Specifies any variables used by the scope's SIGNUP method

Example usage

Request

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

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

Response

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

signin

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

Method Syntax

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

Parameters

Parameter		Description
NSREQUIRED FOR DB & SC		The namespace to sign in to
DBREQUIRED FOR SC		The database to sign in to
SC		Specifies the scope
userREQUIRED FOR ROOT, NS & DB		The username of the database user
passREQUIRED FOR ROOT, NS & DB		The password of the database user
...		Specifies any variables used by the scope's SIGNUP method

Example with Root user

Request

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

Response

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

Example with Scope user

Request

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

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

Response

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

authenticate

This method specifies the namespace and database for the current connection

Method Syntax

authenticate [ token ]

Parameters

Parameter		Description
tokenREQUIRED		The token that authenticates the user

Example usage

Request

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

Response

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

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

This method specifies the namespace and database for the current connection

Method Syntax

let [ name, value ]

Parameters

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

Example usage

Request

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

Response

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

unset

This method specifies the namespace and database for the current connection

Method Syntax

unset [ name ]

Parameters

Parameter		Description
nameREQUIRED		The name of the variable without a prefixed $ character
valueREQUIRED		The value for the variable

Example usage

Request

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

Response

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

live

Method Syntax

live[ table ]

INFORMATION: For more advanced live queries where filters are needed, use the Query method to initiate a custom live query.

Parameters

Parameter		Description
tableREQUIRED		The table to initiate a live query for
diffOPTIONAL		The value for the variable

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"
        }
    }
}

kill

This method kills an active live query

Method Syntax

kill [ queryUuid ]

Parameters

Parameter		Description
queryUuidREQUIRED		The UUID of the live query to kill

Example usage

Request

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

Response

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

query

This methods sends a custom SurrealQL query

Method Syntax

query [ sql, vars ]

Parameters

Parameter		Description
sqlREQUIRED		The query to execute against SurrealDB
varsOPTIONAL		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"
              }
          ]
      }
  ]
}

select

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

Method Syntax

select [ thing ]

Parameters

Parameter		Description
thingREQUIRED		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"
        }
    ]
}

create

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

Method Syntax

create [ thing, data ]

Parameters

Parameter		Description
thingREQUIRED		The thing (Table or Record ID) to select
dataOPTIONAL		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"
        }
    ]
}

insert

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

Method Syntax

insert [ thing, data ]

Parameters

Parameter		Description
thingREQUIRED		The table to insert in to
dataOPTIONAL		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"
        }
    ]
}

update

Method Syntax

update [ thing, data ]

NOTE: This function replaces the current document / record data with the specified data. If no replacement data is passed it will simply trigger an update.

Parameters

Parameter		Description
thingREQUIRED		The thing (Table or Record ID) to select
dataOPTIONAL		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"
    }
}

merge

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

Method Syntax

merge [ thing, data ]

NOTE: This function replaces the current document / record data with the specified data. If no replacement data is passed it will simply trigger an update.

Parameters

Parameter		Description
thingREQUIRED		The thing (Table or Record ID) to select
dataOPTIONAL		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 merges specified data into either all records in a table or a single record

Method Syntax

patch [ thing, patches, diff ]

NOTE: This function replaces the current document / record data with the specified data. If no replacement data is passed it will simply trigger an update.

Parameters

Parameter		Description
thingREQUIRED		The thing (Table or Record ID) to select
patchesREQUIRED		The content of the record
diffOPTIONAL		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"
            }
        ]
    ]
}

delete

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

Method Syntax

delete [ thing ]

NOTE: This function replaces the current document / record data with the specified data. If no replacement data is passed it will simply trigger an update.

Parameters

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

Example usage

Request

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

Notice how the deleted record is being returned here

Response

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