# Table

User-defined data tables

Tables allow you to create and manage custom data tables directly within SteelEngine. Store, query, and manipulate structured data within your workflows without needing external database integrations.

**Why Use Tables?**

* **No external setup**: Create tables instantly without configuring external databases
* **Workflow-native**: Data persists across workflow executions and is accessible from any workflow in your workspace
* **Organized into databases**: Every table lives in a [database](/tables/databases) — a flat container that groups your workspace's tables
* **Flexible schema**: Define columns with types (string, number, boolean, date, json) and constraints (required, unique)
* **Powerful querying**: Filter, sort, and paginate data using MongoDB-style operators
* **Agent-friendly**: Tables can be used as tools by AI agents for dynamic data storage and retrieval

**Key Features:**

* Create tables with custom schemas
* Insert, update, upsert, and delete rows
* Query with filters and sorting
* Batch operations for bulk inserts and upserts
* Bulk updates, deletes, and replacements by filter
* Tables per workspace and rows per table are plan-based — see [Limits](/tables#limits)

## Creating Tables

Tables are created from the **Databases** section in the sidebar: open (or create) a database, then click **New table**. Workflows can also create tables with the **Create Table** operation (`table_create`). Each table requires:

* **Name**: Alphanumeric with underscores (e.g., `customer_leads`), unique within its database
* **Description**: Optional description of the table's purpose
* **Schema**: Define columns with name, type, and optional constraints

### Column Types

| Type      | Description         | Example Values                 |
| --------- | ------------------- | ------------------------------ |
| `string`  | Text data           | `"John Doe"`, `"active"`       |
| `number`  | Numeric data        | `42`, `99.99`                  |
| `boolean` | True/false values   | `true`, `false`                |
| `date`    | Date/time values    | `"2024-01-15T10:30:00Z"`       |
| `json`    | Complex nested data | `{"address": {"city": "NYC"}}` |

### Column Constraints

* **Required**: Column must have a value (cannot be null)
* **Unique**: Values must be unique across all rows (enables upsert matching)

## Filter Operators

Filters use MongoDB-style operators for flexible querying:

| Operator    | Description           | Example                                                   |
| ----------- | --------------------- | --------------------------------------------------------- |
| `$eq`       | Equals                | `{"status": {"$eq": "active"}}` or `{"status": "active"}` |
| `$ne`       | Not equals            | `{"status": {"$ne": "deleted"}}`                          |
| `$gt`       | Greater than          | `{"age": {"$gt": 18}}`                                    |
| `$gte`      | Greater than or equal | `{"score": {"$gte": 80}}`                                 |
| `$lt`       | Less than             | `{"price": {"$lt": 100}}`                                 |
| `$lte`      | Less than or equal    | `{"quantity": {"$lte": 10}}`                              |
| `$in`       | In array              | `{"status": {"$in": ["active", "pending"]}}`              |
| `$nin`      | Not in array          | `{"type": {"$nin": ["spam", "blocked"]}}`                 |
| `$contains` | String contains       | `{"email": {"$contains": "@gmail.com"}}`                  |

### Combining Filters

Multiple field conditions are combined with AND logic:

```json
{
  "status": "active",
  "age": {"$gte": 18}
}
```

Use `$or` for OR logic:

```json
{
  "$or": [
    {"status": "active"},
    {"status": "pending"}
  ]
}
```

## Sort Specification

Specify sort order with column names and direction:

```json
{
  "createdAt": "desc"
}
```

Multi-column sorting:

```json
{
  "priority": "desc",
  "name": "asc"
}
```

## Built-in Columns

Every row automatically includes:

| Column      | Type   | Description                    |
| ----------- | ------ | ------------------------------ |
| `id`        | string | Unique row identifier          |
| `createdAt` | date   | When the row was created       |
| `updatedAt` | date   | When the row was last modified |

These can be used in filters and sorting.

## Limits

| Resource                       | Limit                                                                                                 |
| ------------------------------ | ----------------------------------------------------------------------------------------------------- |
| Databases per workspace        | 50                                                                                                    |
| Tables per workspace           | Plan-based — 3 (Free), 25 (Pro), 100 (Team), 10,000 (Enterprise)                                      |
| Rows per table                 | Plan-based — 100,000 (Free, Pro, Team) or 1,000,000 (Enterprise); see [Tables limits](/tables#limits) |
| Columns per table              | 1,000                                                                                                 |
| Max row size                   | 100 KB                                                                                                |
| String value length            | 100 KB (the row size is the binding limit)                                                            |
| Query limit                    | 1,000 rows (default 100)                                                                              |
| Batch insert / upsert size     | 1,000 rows                                                                                            |
| Bulk update / delete / replace | 1,000 rows                                                                                            |

## Notes

* Every table lives in a [database](/tables/databases) within your workspace and is accessible from any workflow in that workspace
* Use the [Database block](/tools/database) to list databases, create databases, list tables, and run read-only queries
* Data persists across workflow executions
* Use unique constraints to enable upsert functionality
* The visual filter/sort builder provides an easy way to construct queries without writing JSON

## Usage Instructions

Create and manage custom data tables. Store, query, and manipulate structured data within workflows.

## Tools

### `table_insert_row`

Insert a new row into a table. IMPORTANT: You must use the "data" parameter (not "values", "row", "fields", or other variations) to specify the row contents.

#### Input

| Parameter | Type   | Required | Description             |
| --------- | ------ | -------- | ----------------------- |
| `tableId` | string | Yes      | Table ID                |
| `data`    | object | Yes      | Row data as JSON object |

#### Output

| Parameter | Type    | Description              |
| --------- | ------- | ------------------------ |
| `success` | boolean | Whether row was inserted |
| `row`     | json    | Inserted row data        |
| `message` | string  | Status message           |

### `table_batch_insert_rows`

Insert multiple rows into a table at once (up to rows)

#### Input

| Parameter | Type   | Required | Description                                                                     |
| --------- | ------ | -------- | ------------------------------------------------------------------------------- |
| `tableId` | string | Yes      | Table ID                                                                        |
| `rows`    | array  | Yes      | Array of row data objects (max $\{TABLE\_LIMITS.MAX\_BATCH\_INSERT\_SIZE} rows) |

#### Output

| Parameter       | Type    | Description                |
| --------------- | ------- | -------------------------- |
| `success`       | boolean | Whether rows were inserted |
| `rows`          | array   | Inserted rows data         |
| `insertedCount` | number  | Number of rows inserted    |
| `message`       | string  | Status message             |

### `table_batch_upsert_rows`

Insert or update multiple rows by conflict target (up to rows). Updates require exactly one matching row; ambiguous matches are returned as per-row failures so workflows can route them without custom code.

#### Input

| Parameter         | Type    | Required | Description                                                                                                                              |
| ----------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `tableId`         | string  | Yes      | Table ID                                                                                                                                 |
| `rows`            | array   | Yes      | Array of row data objects to insert or update (max $\{TABLE\_LIMITS.MAX\_BATCH\_INSERT\_SIZE} rows)                                      |
| `conflictTarget`  | string  | No       | Column used to match existing rows. Required when the table has no single unique column; if multiple rows match a value, that row fails. |
| `continueOnError` | boolean | No       | When true, continue processing remaining rows and return per-row failures. Defaults to true.                                             |

#### Output

| Parameter       | Type    | Description                                    |
| --------------- | ------- | ---------------------------------------------- |
| `success`       | boolean | Whether the batch request completed            |
| `rows`          | array   | Successfully upserted rows                     |
| `results`       | array   | Per-row upsert results with operation or error |
| `insertedCount` | number  | Number of rows inserted                        |
| `updatedCount`  | number  | Number of rows updated                         |
| `failedCount`   | number  | Number of rows that failed                     |
| `message`       | string  | Status message                                 |

### `table_upsert_row`

Insert or update a row based on unique column constraints. If a row with matching unique field exists, update it; otherwise insert a new row. IMPORTANT: You must use the "data" parameter (not "values", "row", "fields", or other variations) to specify the row contents.

#### Input

| Parameter        | Type   | Required | Description                                                                                                                   |
| ---------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `tableId`        | string | Yes      | Table ID                                                                                                                      |
| `data`           | object | Yes      | Row data to insert or update                                                                                                  |
| `conflictTarget` | string | No       | Unique column to match when the table has multiple unique columns. If omitted, the table must have exactly one unique column. |

#### Output

| Parameter   | Type    | Description                           |
| ----------- | ------- | ------------------------------------- |
| `success`   | boolean | Whether row was upserted              |
| `row`       | json    | Upserted row data                     |
| `operation` | string  | Operation performed: insert or update |
| `message`   | string  | Status message                        |

### `table_update_row`

Update an existing row in a table. Supports partial updates - only include the fields you want to change. IMPORTANT: You must use the "data" parameter (not "values", "row", "fields", or other variations) to specify the fields to update.

#### Input

| Parameter | Type   | Required | Description      |
| --------- | ------ | -------- | ---------------- |
| `tableId` | string | Yes      | Table ID         |
| `rowId`   | string | Yes      | Row ID to update |
| `data`    | object | Yes      | Updated row data |

#### Output

| Parameter | Type    | Description             |
| --------- | ------- | ----------------------- |
| `success` | boolean | Whether row was updated |
| `row`     | json    | Updated row data        |
| `message` | string  | Status message          |

### `table_update_rows_by_filter`

Update multiple rows that match filter criteria. Data is merged into each row. Unique columns cannot be changed; use Update Row for those fields.

#### Input

| Parameter | Type   | Required | Description                                                                                             |
| --------- | ------ | -------- | ------------------------------------------------------------------------------------------------------- |
| `tableId` | string | Yes      | Table ID                                                                                                |
| `filter`  | object | Yes      | Filter criteria using operators like $eq, $ne, $gt, $lt, $contains, $in, etc.                           |
| `data`    | object | Yes      | Fields to update (merged with existing data)                                                            |
| `limit`   | number | No       | Maximum number of rows to update (default: no limit, max: $\{TABLE\_LIMITS.MAX\_BULK\_OPERATION\_SIZE}) |

#### Output

| Parameter       | Type    | Description               |
| --------------- | ------- | ------------------------- |
| `success`       | boolean | Whether rows were updated |
| `updatedCount`  | number  | Number of rows updated    |
| `updatedRowIds` | array   | IDs of updated rows       |
| `message`       | string  | Status message            |

### `table_delete_row`

Delete a row from a table

#### Input

| Parameter | Type   | Required | Description      |
| --------- | ------ | -------- | ---------------- |
| `tableId` | string | Yes      | Table ID         |
| `rowId`   | string | Yes      | Row ID to delete |

#### Output

| Parameter      | Type    | Description             |
| -------------- | ------- | ----------------------- |
| `success`      | boolean | Whether row was deleted |
| `deletedCount` | number  | Number of rows deleted  |
| `message`      | string  | Status message          |

### `table_delete_rows_by_filter`

Delete multiple rows that match filter criteria. Use with caution - supports optional limit for safety.

#### Input

| Parameter | Type   | Required | Description                                                                                             |
| --------- | ------ | -------- | ------------------------------------------------------------------------------------------------------- |
| `tableId` | string | Yes      | Table ID                                                                                                |
| `filter`  | object | Yes      | Filter criteria using operators like $eq, $ne, $gt, $lt, $contains, $in, etc.                           |
| `limit`   | number | No       | Maximum number of rows to delete (default: no limit, max: $\{TABLE\_LIMITS.MAX\_BULK\_OPERATION\_SIZE}) |

#### Output

| Parameter       | Type    | Description               |
| --------------- | ------- | ------------------------- |
| `success`       | boolean | Whether rows were deleted |
| `deletedCount`  | number  | Number of rows deleted    |
| `deletedRowIds` | array   | IDs of deleted rows       |
| `message`       | string  | Status message            |

### `table_replace_rows_by_filter`

Delete rows matching filter criteria and insert replacement rows atomically. Empty replacement rows are allowed and clear the matching rows.

#### Input

| Parameter | Type   | Required | Description                                                                                                           |
| --------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `tableId` | string | Yes      | Table ID                                                                                                              |
| `filter`  | object | Yes      | Filter criteria using operators like $eq, $ne, $gt, $lt, $contains, $in, etc.                                         |
| `rows`    | array  | Yes      | Replacement row data objects (max $\{TABLE\_LIMITS.MAX\_BATCH\_INSERT\_SIZE} rows). Empty array clears matching rows. |
| `limit`   | number | No       | Maximum number of existing rows to replace (default: no limit, max: $\{TABLE\_LIMITS.MAX\_BULK\_OPERATION\_SIZE})     |

#### Output

| Parameter       | Type    | Description                         |
| --------------- | ------- | ----------------------------------- |
| `success`       | boolean | Whether rows were replaced          |
| `deletedCount`  | number  | Number of rows deleted              |
| `deletedRowIds` | array   | IDs of deleted rows                 |
| `insertedCount` | number  | Number of replacement rows inserted |
| `rows`          | array   | Inserted replacement rows data      |
| `message`       | string  | Status message                      |

### `table_query_rows`

Query rows from a table with filtering, sorting, and pagination

#### Input

| Parameter | Type   | Required | Description                                                                                                         |
| --------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------- |
| `tableId` | string | Yes      | Table ID                                                                                                            |
| `filter`  | object | No       | Filter conditions (MongoDB-style operators: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $contains)                   |
| `sort`    | object | No       | Sort order as \{field: "asc"\|"desc"}                                                                               |
| `limit`   | number | No       | Maximum rows to return (default: $\{TABLE\_LIMITS.DEFAULT\_QUERY\_LIMIT}, max: $\{TABLE\_LIMITS.MAX\_QUERY\_LIMIT}) |
| `offset`  | number | No       | Number of rows to skip (default: 0)                                                                                 |

#### Output

| Parameter    | Type    | Description                |
| ------------ | ------- | -------------------------- |
| `success`    | boolean | Whether query succeeded    |
| `rows`       | array   | Query result rows          |
| `rowCount`   | number  | Number of rows returned    |
| `totalCount` | number  | Total rows matching filter |
| `limit`      | number  | Limit used in query        |
| `offset`     | number  | Offset used in query       |

### `table_get_row`

Get a single row by ID

#### Input

| Parameter | Type   | Required | Description        |
| --------- | ------ | -------- | ------------------ |
| `tableId` | string | Yes      | Table ID           |
| `rowId`   | string | Yes      | Row ID to retrieve |

#### Output

| Parameter | Type    | Description               |
| --------- | ------- | ------------------------- |
| `success` | boolean | Whether row was retrieved |
| `row`     | json    | Row data                  |
| `message` | string  | Status message            |

### `table_get_schema`

Get the schema configuration of a table

#### Input

| Parameter | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| `tableId` | string | Yes      | Table ID    |

#### Output

| Parameter | Type    | Description                  |
| --------- | ------- | ---------------------------- |
| `success` | boolean | Whether schema was retrieved |
| `name`    | string  | Table name                   |
| `columns` | array   | Column definitions           |
| `message` | string  | Status message               |

### `table_create`

Create a new user-defined table with schema

#### Input

| Parameter     | Type   | Required | Description                                        |
| ------------- | ------ | -------- | -------------------------------------------------- |
| `name`        | string | Yes      | Table name (alphanumeric, underscores, 1-50 chars) |
| `description` | string | No       | Optional table description                         |
| `schema`      | object | Yes      | Table schema with column definitions               |
| `databaseId`  | string | No       | Optional database ID to create the table in        |

#### Output

| Parameter | Type    | Description               |
| --------- | ------- | ------------------------- |
| `success` | boolean | Whether table was created |
| `table`   | json    | Created table metadata    |
| `message` | string  | Status message            |
