# SurrealDB

> 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.

App · 16 actions. Web page: https://docs.lodol.com/docs/integrations/surrealdb

## Actions

### 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**

- `healthy` (true/false): True if the server answered 200
- `status_code` (number): The HTTP status the server answered

**Example output**

```json
{
  "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**

- Table (`table`, text, required): The table. Pick one, or type a name: a table that does not exist yet is created by its first record.
- Filter field (`filter_field`, text): Only records whose field matches the value below, such as status or address.city. Leave empty for every record.
- Filter operator (`filter_operator`, text): 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 value (`filter_value`, text): The value to compare the field with.
- Filter value type (`filter_value_type`, text): 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**

- `count` (number): How many records

**Example output**

```json
{
  "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**

- Table (`table`, text, required): The table. Pick one, or type a name: a table that does not exist yet is created by its first record.
- Record ID (`record_id`, text): Your own id for the record, such as ada. Leave empty to have SurrealDB make one.
- Fields (`data`, object): 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**

- `id` (text): The record's id, such as person:abc123
- `record` (object): The record, with its id

**Example output**

```json
{
  "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**

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

**Outputs**

- `deleted` (true/false): True if a record was deleted, false if none existed
- `id` (text): The record's id, such as person:abc123
- `record` (object): The record as it was before, empty if none existed

**Example output**

```json
{
  "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**

- Table (`table`, text, required): The table. Pick one, or type a name: a table that does not exist yet is created by its first record.
- Filter field (`filter_field`, text): Only records whose field matches the value below, such as status or address.city. Leave empty for every record.
- Filter operator (`filter_operator`, text): 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 value (`filter_value`, text): The value to compare the field with.
- Filter value type (`filter_value_type`, text): 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 return (`fields`, text): Field names separated by commas, such as name, age. The id is always included. Leave empty for every field.
- Sort by (`order_by`, text): The field to sort by. Leave empty for no sorting.
- Sort order (`order_direction`, text): Which way to sort. Defaults to smallest first. One of: `asc` (Smallest or oldest first), `desc` (Largest or newest first). Default: `asc`.
- Page size (`limit`, number): How many records to return, 1 to 1000. Defaults to 100. From 1 to 1000.
- Skip (`start`, number): 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**

- `count` (number): How many records are in this page
- `has_more` (true/false): True if the page is full, so there may be more
- `next_start` (number): The Skip value for the next page, empty on the last page
- `records` (list): The matching records
- `start` (number): How many records were skipped

**Example output**

```json
{
  "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**

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

**Outputs**

- `found` (true/false): True if the record exists
- `record` (object): The record, empty if it does not exist

**Example output**

```json
{
  "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**

- `server` (text): What the server reports, such as surrealdb-3.0.0
- `version` (text): The version, such as 3.0.0

**Example output**

```json
{
  "server": "surrealdb-3.0.0",
  "version": "3.0.0"
}
```

### Get table structure

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

**Inputs**

- Table (`table`, text, required): The table. Pick one, or type a name: a table that does not exist yet is created by its first record.

**Outputs**

- `events` (list): The defined events
- `fields` (list): The defined fields
- `indexes` (list): The defined indexes
- `table` (text): The table

**Example output**

```json
{
  "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**

- Table (`table`, text, required): The table. Pick one, or type a name: a table that does not exist yet is created by its first record.
- Records (`records`, list, required): A list of objects, one per record, such as [{"name": "Ada"}, {"name": "Grace"}]. A list from an earlier step works too.

**Outputs**

- `count` (number): How many were created
- `ids` (list): The ids of the records
- `records` (list): The records created

**Example output**

```json
{
  "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**

- `count` (number): How many databases
- `databases` (list): The databases

**Example output**

```json
{
  "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**

- Table (`table`, text, required): The table. Pick one, or type a name: a table that does not exist yet is created by its first record.
- Page size (`limit`, number): How many records to return, 1 to 1000. Defaults to 100. From 1 to 1000.
- Skip (`start`, number): 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**

- `count` (number): How many records are in this page
- `has_more` (true/false): True if the page is full, so there may be more
- `next_start` (number): The Skip value for the next page, empty on the last page
- `records` (list): The records in this page
- `start` (number): How many records were skipped

**Example output**

```json
{
  "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**

- `count` (number): How many tables
- `tables` (list): The tables

**Example output**

```json
{
  "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**

- Table (`table`, text, required): The table. Pick one, or type a name: a table that does not exist yet is created by its first record.
- Record ID (`record_id`, text, required): The record's id, such as abc123, or the full id (person:abc123) from an earlier step.
- Fields (`data`, object, required): 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**

- `id` (text): The record's id, such as person:abc123
- `record` (object): The record, with its id

**Example output**

```json
{
  "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**

- Query (`query`, text, required): SurrealQL, such as SELECT * FROM person WHERE age > $min_age; Refer to a variable below as $name.
- Variables (`variables`, object): 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**

- `result` (object): The result of the last statement
- `results` (list): The result of each statement, in order
- `statement_count` (number): How many statements ran

**Example output**

```json
{
  "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**

- Table (`table`, text, required): The table. Pick one, or type a name: a table that does not exist yet is created by its first record.
- Field (`field_name`, text, required): The number field, such as price or stats.score.
- Calculation (`statistic`, text): What to work out. Defaults to the total. One of: `sum` (Total), `mean` (Average), `min` (Smallest), `max` (Largest). Default: `sum`.
- Filter field (`filter_field`, text): Only records whose field matches the value below, such as status or address.city. Leave empty for every record.
- Filter operator (`filter_operator`, text): 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 value (`filter_value`, text): The value to compare the field with.
- Filter value type (`filter_value_type`, text): 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_count` (number): How many records were included
- `statistic` (text): The calculation that was made
- `value` (number): The result, empty if there were no values

**Example output**

```json
{
  "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**

- Table (`table`, text, required): The table. Pick one, or type a name: a table that does not exist yet is created by its first record.
- Record ID (`record_id`, text, required): The record's id, such as abc123, or the full id (person:abc123) from an earlier step.
- Fields to change (`data`, object, required): 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**

- `id` (text): The record's id, such as person:abc123
- `record` (object): The record, with its id

**Example output**

```json
{
  "id": "person:ada",
  "record": {
    "age": 36,
    "id": "person:ada",
    "name": "Ada Lovelace"
  }
}
```
