View Source Surrealix.Api (surrealix v0.1.8)

Thin layer over the Websockets API for SurrealDB that is 100% generated from a data-structure.

Summary

Functions

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

create [ thing, data ] This method creates a record either with a random or specified ID

delete [ thing ] This method deletes either all records in a table or a single record NOTE: Notice how the deleted record is being returned here

info This method returns the record of an authenticated scope user.

insert [ thing, data ] This method creates a record either with a random or specified ID Single insert

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

kill [ queryUuid ] This methods kills an active live query

let [ name, value ] This method stores a variable on the current connection

live [ table ] This methods initiates a live query for a specified table name NOTE: For more advanced live queries where filters are needed, use the Query method to initiate a custom live query.

Convenience method that combines sending a (live-)query and registering a callback.

merge [ thing, data ] This method merges specified data into either all records in a table or a single record NOTE: This function merges the current document / record data with the specified data. If no merge data is passed it will simply trigger an update.

patch [ thing, patches, diff ] This method patches either all records in a table or a single record with specified patches NOTE: This function patches the current document / record data with the specified JSON Patch data.

ping This method pings the SurrealDB instance

query [ sql, vars ] This method executes a custom query against SurrealDB

select [ thing ] This method selects either all records in a table or a single record

signin [ NS, DB, SC, ... ] This method allows you to signin a root, NS, DB or SC user against SurrealDB As Root

signup [ NS, DB, SC, ... ] This method allows you to signup a user against a scope's SIGNUP method

unset [ name ] This method removes a variable from the current connection

update [ thing, data ] This method replaces either all records in a table or a single record with specified 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.

use [ ns, db ] Specifies the namespace and database for the current connection

Functions

Link to this function

authenticate(pid, token, task_opts \\ Config.task_opts_default())

View Source

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

Example request:

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

Example response:

{
  "id": 1,
  "result": null
}
Link to this function

build_cast_payload(method, args, id)

View Source
Link to this function

create(pid, thing, data, task_opts \\ Config.task_opts_default())

View Source

create [ thing, data ] This method creates a record either with a random or specified ID

Example request:

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

Example response:

{
  "id": 1,
  "result": [
    {
      "id": "person:s5fa6qp4p8ey9k5j0m9z",
      "name": "Mary Doe"
    }
  ]
}
Link to this function

delete(pid, thing, task_opts \\ Config.task_opts_default())

View Source

delete [ thing ] This method deletes either all records in a table or a single record NOTE: Notice how the deleted record is being returned here

Example request:

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

Example response:

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

info(pid, task_opts \\ Config.task_opts_default())

View Source

info This method returns the record of an authenticated scope user.

Example request:

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

Example response:

{
  "id": 1,
  "result": {
    "id": "user:john",
    "name": "John Doe"
  }
}
Link to this function

insert(pid, thing, data, task_opts \\ Config.task_opts_default())

View Source

insert [ thing, data ] This method creates a record either with a random or specified ID Single insert

Example request:

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

Example response:

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

Bulk insert

Example request:

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

Example response:

{
  "id": 1,
  "result": [
    {
      "id": "person:s5fa6qp4p8ey9k5j0m9z",
      "name": "Mary Doe"
    },
    {
      "id": "person:xtbbojcm82a97vus9x0j",
      "name": "John Doe"
    }
  ]
}
Link to this function

invalidate(pid, task_opts \\ Config.task_opts_default())

View Source

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

Example request:

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

Example response:

{
  "id": 1,
  "result": null
}
Link to this function

kill(pid, queryUuid, task_opts \\ Config.task_opts_default())

View Source

kill [ queryUuid ] This methods kills an active live query

Example request:

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

Example response:

{
  "id": 1,
  "result": null
}
Link to this function

let(pid, name, value, task_opts \\ Config.task_opts_default())

View Source

let [ name, value ] This method stores a variable on the current connection

Example request:

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

Example response:

{
  "id": 1,
  "result": null
}
Link to this function

live(pid, table, diff, task_opts \\ Config.task_opts_default())

View Source

live [ table ] This methods initiates a live query for a specified table name NOTE: For more advanced live queries where filters are needed, use the Query method to initiate a custom live query.

Example request:

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

Example response:

{
  "id": 1,
  "result": "0189d6e3-8eac-703a-9a48-d9faa78b44b9"
}

Live notification

Example request:

{}

Example response:

{
  "result": {
    "action": "CREATE",
    "id": "0189d6e3-8eac-703a-9a48-d9faa78b44b9",
    "result": {
      "id": "person:8s0j0bbm3ngrd5c9bx53",
      "name": "John"
    }
  }
}
Link to this function

live_query(pid, sql, vars \\ %{}, callback)

View Source
@spec live_query(pid(), String.t(), map(), (any(), String.t() -> any())) :: :ok

Convenience method that combines sending a (live-)query and registering a callback.

Params:

sql: string
vars: map with variables to interpolate into SQL
callback: fn (data, live_query_id)
Link to this function

merge(pid, thing, data, task_opts \\ Config.task_opts_default())

View Source

merge [ thing, data ] This method merges specified data into either all records in a table or a single record NOTE: This function merges the current document / record data with the specified data. If no merge data is passed it will simply trigger an update.

Example request:

{
  "id": 1,
  "method": "merge",
  "params": [
    "person",
    {
      "active": true
    }
  ]
}

Example response:

{
  "id": 1,
  "result": [
    {
      "active": true,
      "id": "person:8s0j0bbm3ngrd5c9bx53",
      "name": "John Doe"
    },
    {
      "active": true,
      "id": "person:s5fa6qp4p8ey9k5j0m9z",
      "name": "Mary Doe"
    }
  ]
}
Link to this function

patch(pid, thing, patches, diff, task_opts \\ Config.task_opts_default())

View Source

patch [ thing, patches, diff ] This method patches either all records in a table or a single record with specified patches NOTE: This function patches the current document / record data with the specified JSON Patch data.

Example request:

{
  "id": 1,
  "method": "patch",
  "params": [
    "person",
    [
      {
        "op": "replace",
        "path": "/last_updated",
        "value": "2023-06-16T08:34:25Z"
      }
    ]
  ]
}

Example 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"
      }
    ]
  ]
}
Link to this function

ping(pid, task_opts \\ Config.task_opts_default())

View Source

ping This method pings the SurrealDB instance

Example request:

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

Example response:

{
  "id": 1,
  "result": null
}
Link to this function

query(pid, sql, vars, task_opts \\ Config.task_opts_default())

View Source

query [ sql, vars ] This method executes a custom query against SurrealDB

Example request:

{
  "id": 1,
  "method": "query",
  "params": [
    "CREATE person SET name = 'John'; SELECT * FROM type::table($tb);",
    {
      "tb": "person"
    }
  ]
}

Example 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"
        }
      ]
    }
  ]
}
Link to this function

select(pid, thing, task_opts \\ Config.task_opts_default())

View Source

select [ thing ] This method selects either all records in a table or a single record

Example request:

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

Example response:

{
  "id": 1,
  "result": [
    {
      "id": "person:8s0j0bbm3ngrd5c9bx53",
      "name": "John"
    }
  ]
}
Link to this function

signin(pid, payload, task_opts \\ Config.task_opts_default())

View Source

signin [ NS, DB, SC, ... ] This method allows you to signin a root, NS, DB or SC user against SurrealDB As Root

Example request:

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

Example response:

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

Signin as scope

Example request:

{
  "id": 1,
  "method": "signin",
  "params": [
    {
      "NS": "surrealdb",
      "DB": "docs",
      "SC": "commenter",
      "username": "johndoe",
      "password": "SuperStrongPassword!"
    }
  ]
}

Example response:

{
  "id": 1,
  "result": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJTdXJyZWFsREIiLCJpYXQiOjE1MTYyMzkwMjIsIm5iZiI6MTUxNjIzOTAyMiwiZXhwIjoxODM2NDM5MDIyLCJOUyI6InRlc3QiLCJEQiI6InRlc3QiLCJTQyI6InVzZXIiLCJJRCI6InVzZXI6dG9iaWUifQ.N22Gp9ze0rdR06McGj1G-h2vu6a6n9IVqUbMFJlOxxA"
}
Link to this function

signup(pid, payload, task_opts \\ Config.task_opts_default())

View Source

signup [ NS, DB, SC, ... ] This method allows you to signup a user against a scope's SIGNUP method

Example request:

{
  "id": 1,
  "method": "signup",
  "params": [
    {
      "NS": "surrealdb",
      "DB": "docs",
      "SC": "commenter",
      "username": "johndoe",
      "password": "SuperStrongPassword!"
    }
  ]
}

Example response:

{
  "id": 1,
  "result": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJTdXJyZWFsREIiLCJpYXQiOjE1MTYyMzkwMjIsIm5iZiI6MTUxNjIzOTAyMiwiZXhwIjoxODM2NDM5MDIyLCJOUyI6InRlc3QiLCJEQiI6InRlc3QiLCJTQyI6InVzZXIiLCJJRCI6InVzZXI6dG9iaWUifQ.N22Gp9ze0rdR06McGj1G-h2vu6a6n9IVqUbMFJlOxxA"
}
Link to this function

unset(pid, name, task_opts \\ Config.task_opts_default())

View Source

unset [ name ] This method removes a variable from the current connection

Example request:

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

Example response:

{
  "id": 1,
  "result": null
}
Link to this function

update(pid, thing, data, task_opts \\ Config.task_opts_default())

View Source

update [ thing, data ] This method replaces either all records in a table or a single record with specified 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.

Example request:

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

Example response:

{
  "id": 1,
  "result": {
    "id": "person:8s0j0bbm3ngrd5c9bx53",
    "name": "John Doe"
  }
}
Link to this function

use(pid, ns, db, task_opts \\ Config.task_opts_default())

View Source

use [ ns, db ] Specifies the namespace and database for the current connection

Example request:

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

Example response:

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