SurrealDB

App · 16 actions

Run SurrealQL, and list, find, create, insert, update and delete records in your SurrealDB database, on SurrealDB Cloud or your own server. Count and total fields, and read tables and their structure.

Actions

ActionWhat it does
Check server healthCheck that the server and its storage answer.
Count recordsCount the records in a table.
Create recordCreate a record in a table, with an id made by SurrealDB or one you choose.
Delete recordDelete one record by its id and return what it held.
Find recordsFind records in a table that match one condition, sorted and limited, with all their fields or only the ones you name.
Get recordGet one record by its id.
Get server versionGet the version of SurrealDB the server runs.
Get table structureGet a table's defined fields, indexes and events.
Insert multiple recordsCreate up to 200 records in a table in one request, each with an id made by SurrealDB.
List databasesList the databases in the connection's namespace.
List recordsGet a page of a table's records, up to 1000.
List tablesList the tables in the database and whether each enforces a schema.
Replace recordReplace a record's fields with exactly the ones given; fields not listed are removed.
Run SurrealQL queryRun one or more SurrealQL statements in the database and get each statement's result.
Total a fieldAdd up, average, or find the smallest or largest value of a number field across a table's records.
Update record fieldsChange only the fields given on an existing record and keep all its other fields.

Check server health

Check that the server and its storage answer. An unhealthy server is reported as 'healthy' false, not as a failed step.

Inputs

None.

Outputs

healthytrue/false
True if the server answered 200
status_codenumber
The HTTP status the server answered
Example output
{
  "healthy": true,
  "status_code": 200
}

Count records

Count the records in a table. Add a filter to count or total only the records that match it.

Inputs

TabletabletextRequired
The table. Pick one, or type a name: a table that does not exist yet is created by its first record.
Filter fieldfilter_fieldtext
Only records whose field matches the value below, such as status or address.city. Leave empty for every record.
Filter operatorfilter_operatortext
How to compare the field with the value. Defaults to equals.One of: eq (Equals), ne (Does not equal), gt (Greater than), gte (Greater than or equal to), lt (Less than), lte (Less than or equal to), contains (Contains the text). Default: eq.
Filter valuefilter_valuetext
The value to compare the field with.
Filter value typefilter_value_typetext
What the value is, so it is compared as a number, date or true/false rather than as text. Defaults to text.One of: text, number, boolean (True or false), datetime (Date and time). Default: text.

Outputs

countnumber
How many records
Example output
{
  "count": 12
}

Create record

Create a record in a table, with an id made by SurrealDB or one you choose. Fails if that id already exists.

Inputs

TabletabletextRequired
The table. Pick one, or type a name: a table that does not exist yet is created by its first record.
Record IDrecord_idtext
Your own id for the record, such as ada. Leave empty to have SurrealDB make one.
Fieldsdataobject
The record's fields as names and values, for example {"name": "Ada", "age": 36}. Dates are stored as text; use 'Run SurrealQL query' for a date-and-time field.

Outputs

idtext
The record's id, such as person:abc123
recordobject
The record, with its id
Example output
{
  "id": "person:ada",
  "record": {
    "age": 36,
    "id": "person:ada",
    "name": "Ada Lovelace"
  }
}

Delete record

Delete one record by its id and return what it held. A record that is already gone is reported, not an error.

Inputs

TabletabletextRequired
The table. Pick one, or type a name: a table that does not exist yet is created by its first record.
Record IDrecord_idtextRequired
The record's id, such as abc123, or the full id (person:abc123) from an earlier step.

Outputs

deletedtrue/false
True if a record was deleted, false if none existed
idtext
The record's id, such as person:abc123
recordobject
The record as it was before, empty if none existed
Example output
{
  "deleted": true,
  "id": "person:ada",
  "record": {
    "age": 36,
    "id": "person:ada",
    "name": "Ada Lovelace"
  }
}

Find records

Find records in a table that match one condition, sorted and limited, with all their fields or only the ones you name.

Inputs

TabletabletextRequired
The table. Pick one, or type a name: a table that does not exist yet is created by its first record.
Filter fieldfilter_fieldtext
Only records whose field matches the value below, such as status or address.city. Leave empty for every record.
Filter operatorfilter_operatortext
How to compare the field with the value. Defaults to equals.One of: eq (Equals), ne (Does not equal), gt (Greater than), gte (Greater than or equal to), lt (Less than), lte (Less than or equal to), contains (Contains the text). Default: eq.
Filter valuefilter_valuetext
The value to compare the field with.
Filter value typefilter_value_typetext
What the value is, so it is compared as a number, date or true/false rather than as text. Defaults to text.One of: text, number, boolean (True or false), datetime (Date and time). Default: text.
Fields to returnfieldstext
Field names separated by commas, such as name, age. The id is always included. Leave empty for every field.
Sort byorder_bytext
The field to sort by. Leave empty for no sorting.
Sort orderorder_directiontext
Which way to sort. Defaults to smallest first.One of: asc (Smallest or oldest first), desc (Largest or newest first). Default: asc.
Page sizelimitnumber
How many records to return, 1 to 1000. Defaults to 100.From 1 to 1000.
Skipstartnumber
How many records to skip before the first one returned. Use the 'next_start' of an earlier page to get the page after it.At least 0.

Outputs

countnumber
How many records are in this page
has_moretrue/false
True if the page is full, so there may be more
next_startnumber
The Skip value for the next page, empty on the last page
recordslist
The matching records
startnumber
How many records were skipped
Example output
{
  "count": 1,
  "has_more": false,
  "next_start": null,
  "records": [
    {
      "age": 36,
      "id": "person:ada",
      "name": "Ada Lovelace"
    }
  ],
  "start": 0
}

Get record

Get one record by its id. When there is none, 'found' is false instead of the step failing.

Inputs

TabletabletextRequired
The table. Pick one, or type a name: a table that does not exist yet is created by its first record.
Record IDrecord_idtextRequired
The record's id, such as abc123, or the full id (person:abc123) from an earlier step.

Outputs

foundtrue/false
True if the record exists
recordobject
The record, empty if it does not exist
Example output
{
  "found": true,
  "record": {
    "age": 36,
    "id": "person:ada",
    "name": "Ada Lovelace"
  }
}

Get server version

Get the version of SurrealDB the server runs. Needs no sign-in.

Inputs

None.

Outputs

servertext
What the server reports, such as surrealdb-3.0.0
versiontext
The version, such as 3.0.0
Example output
{
  "server": "surrealdb-3.0.0",
  "version": "3.0.0"
}

Get table structure

Get a table's defined fields, indexes and events.

Inputs

TabletabletextRequired
The table. Pick one, or type a name: a table that does not exist yet is created by its first record.

Outputs

eventslist
The defined events
fieldslist
The defined fields
indexeslist
The defined indexes
tabletext
The table
Example output
{
  "events": [],
  "fields": [
    {
      "definition": "DEFINE FIELD name ON person TYPE string PERMISSIONS FULL",
      "name": "name"
    }
  ],
  "indexes": [],
  "table": "person"
}

Insert multiple records

Create up to 200 records in a table in one request, each with an id made by SurrealDB.

Inputs

TabletabletextRequired
The table. Pick one, or type a name: a table that does not exist yet is created by its first record.
RecordsrecordslistRequired
A list of objects, one per record, such as [{"name": "Ada"}, {"name": "Grace"}]. A list from an earlier step works too.

Outputs

countnumber
How many were created
idslist
The ids of the records
recordslist
The records created
Example output
{
  "count": 1,
  "ids": [
    "person:ada"
  ],
  "records": [
    {
      "age": 36,
      "id": "person:ada",
      "name": "Ada Lovelace"
    }
  ]
}

List databases

List the databases in the connection's namespace. Needs a root or namespace user.

Inputs

None.

Outputs

countnumber
How many databases
databaseslist
The databases
Example output
{
  "count": 1,
  "databases": [
    {
      "definition": "DEFINE DATABASE main",
      "name": "main"
    }
  ]
}

List records

Get a page of a table's records, up to 1000. To see more, run it again with the next page's Skip value.

Inputs

TabletabletextRequired
The table. Pick one, or type a name: a table that does not exist yet is created by its first record.
Page sizelimitnumber
How many records to return, 1 to 1000. Defaults to 100.From 1 to 1000.
Skipstartnumber
How many records to skip before the first one returned. Use the 'next_start' of an earlier page to get the page after it.At least 0.

Outputs

countnumber
How many records are in this page
has_moretrue/false
True if the page is full, so there may be more
next_startnumber
The Skip value for the next page, empty on the last page
recordslist
The records in this page
startnumber
How many records were skipped
Example output
{
  "count": 1,
  "has_more": false,
  "next_start": null,
  "records": [
    {
      "age": 36,
      "id": "person:ada",
      "name": "Ada Lovelace"
    }
  ],
  "start": 0
}

List tables

List the tables in the database and whether each enforces a schema.

Inputs

None.

Outputs

countnumber
How many tables
tableslist
The tables
Example output
{
  "count": 1,
  "tables": [
    {
      "definition": "DEFINE TABLE person TYPE ANY SCHEMALESS PERMISSIONS NONE",
      "name": "person",
      "schemafull": false
    }
  ]
}

Replace record

Replace a record's fields with exactly the ones given; fields not listed are removed. Use 'Update record fields' to keep them.

Inputs

TabletabletextRequired
The table. Pick one, or type a name: a table that does not exist yet is created by its first record.
Record IDrecord_idtextRequired
The record's id, such as abc123, or the full id (person:abc123) from an earlier step.
FieldsdataobjectRequired
The record's fields as names and values, for example {"name": "Ada", "age": 36}. Dates are stored as text; use 'Run SurrealQL query' for a date-and-time field.

Outputs

idtext
The record's id, such as person:abc123
recordobject
The record, with its id
Example output
{
  "id": "person:ada",
  "record": {
    "age": 36,
    "id": "person:ada",
    "name": "Ada Lovelace"
  }
}

Run SurrealQL query

Run one or more SurrealQL statements in the database and get each statement's result. Anything the connected user may do can run, including changes and deletes.

Inputs

QueryquerytextRequired
SurrealQL, such as SELECT * FROM person WHERE age > $min_age; Refer to a variable below as $name.
Variablesvariablesobject
Values the query reads as $name. Numbers, true/false, lists and objects keep their type. Use these instead of typing values into the query.

Outputs

resultobject
The result of the last statement
resultslist
The result of each statement, in order
statement_countnumber
How many statements ran
Example output
{
  "result": [
    {
      "age": 36,
      "id": "person:ada",
      "name": "Ada Lovelace"
    }
  ],
  "results": [
    [
      {
        "age": 36,
        "id": "person:ada",
        "name": "Ada Lovelace"
      }
    ]
  ],
  "statement_count": 1
}

Total a field

Add up, average, or find the smallest or largest value of a number field across a table's records. Add a filter to count or total only the records that match it.

Inputs

TabletabletextRequired
The table. Pick one, or type a name: a table that does not exist yet is created by its first record.
Fieldfield_nametextRequired
The number field, such as price or stats.score.
Calculationstatistictext
What to work out. Defaults to the total.One of: sum (Total), mean (Average), min (Smallest), max (Largest). Default: sum.
Filter fieldfilter_fieldtext
Only records whose field matches the value below, such as status or address.city. Leave empty for every record.
Filter operatorfilter_operatortext
How to compare the field with the value. Defaults to equals.One of: eq (Equals), ne (Does not equal), gt (Greater than), gte (Greater than or equal to), lt (Less than), lte (Less than or equal to), contains (Contains the text). Default: eq.
Filter valuefilter_valuetext
The value to compare the field with.
Filter value typefilter_value_typetext
What the value is, so it is compared as a number, date or true/false rather than as text. Defaults to text.One of: text, number, boolean (True or false), datetime (Date and time). Default: text.

Outputs

record_countnumber
How many records were included
statistictext
The calculation that was made
valuenumber
The result, empty if there were no values
Example output
{
  "record_count": 12,
  "statistic": "sum",
  "value": 1280.5
}

Update record fields

Change only the fields given on an existing record and keep all its other fields.

Inputs

TabletabletextRequired
The table. Pick one, or type a name: a table that does not exist yet is created by its first record.
Record IDrecord_idtextRequired
The record's id, such as abc123, or the full id (person:abc123) from an earlier step.
Fields to changedataobjectRequired
The record's fields as names and values, for example {"name": "Ada", "age": 36}. Dates are stored as text; use 'Run SurrealQL query' for a date-and-time field.

Outputs

idtext
The record's id, such as person:abc123
recordobject
The record, with its id
Example output
{
  "id": "person:ada",
  "record": {
    "age": 36,
    "id": "person:ada",
    "name": "Ada Lovelace"
  }
}

On this page