> ## Documentation Index
> Fetch the complete documentation index at: https://botpress-ak-docs-20-document-updating-variables-from-outsid.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Tables

Tables define data storage schemas for your agent. They provide structured storage that's automatically synced with Botpress Cloud and accessible throughout your agent.

## Creating a table

Create a table definition in `src/tables/`:

```typescript theme={null}
import { Table, z } from "@botpress/runtime";

export default new Table({
  name: "PricingTable",
  columns: {
    itemName: z.string(),
    price: z.string(),
  },
});
```

### Naming a table

To properly deploy your agent, make sure your table name follows the correct convention:

* Cannot start with a number
* Must be 30 characters or less
* Can contain only letters, numbers, and underscores
* Must end with `Table`

## Table schema

### Simple definition

Define your table using Zod schemas:

```typescript theme={null}
export default new Table({
  name: "OrderTable",
  columns: {
    userId: z.string(),
    items: z.array(z.string()),
    total: z.number(),
    status: z.string(),
    createdAt: z.string().datetime(),
    updatedAt: z.string().datetime(),
  },
});
```

### Extended definition

You can also define table columns with additional options for each column:

```ts highlight={5-14} theme={null}
import { Table, z } from "@botpress/runtime";

export default new Table({
  name: "OrderTable",
  columns: {
    itemName: {
      schema: z.string(),
      searchable: true
    },
    price: {
      schema: z.string(),
      searchable: true
    }
  },
});
```

Check out the [column options](#table-props) in the Table props reference for a full overview of the available options.

## Using tables

Tables are automatically created and synced when you deploy. You can import them and interact with them directly using the table instance methods, which provide type-safe operations:

```ts src/workflows/create-order.ts highlight={8-10, 13-18, 21-23} theme={null}
import { Workflow } from "@botpress/runtime";
import OrderTable from "../tables/order-table";

export default new Workflow({
  name: "createOrder",
  handler: async ({ step }) => {
    // Create rows
    const { rows } = await OrderTable.createRows({
      rows: [{ userId: "user123", total: 99.99, status: "pending" }],
    });

    // Find rows with filters
    const { rows: orders } = await OrderTable.findRows({
      filter: { status: "pending" },
      orderBy: "createdAt",
      orderDirection: "desc",
      limit: 10,
    });

    // Update rows
    await OrderTable.updateRows({
      rows: [{ id: orders[0].id, status: "completed" }],
    });
  },
});
```

## Reference

<Expandable title="Table props">
  <ResponseField name="name" type="string" required>
    Unique name for the table. Must be 30 characters or less, cannot start with a number, can contain only letters, numbers, and underscores, and must end with 'Table'.
  </ResponseField>

  <ResponseField name="description" type="string">
    Optional description of what the table stores.
  </ResponseField>

  <ResponseField name="factor" type="number">
    Optional factor for table operations. Defaults to 1.
  </ResponseField>

  <ResponseField name="columns" type="object" required>
    Object mapping column names to their definitions. Each key is a column name. Values can be either a simple Zod schema or an object with advanced column configuration options.

    <Expandable title="simple column definition">
      <ResponseField name="{key}" type="z.ZodTypeAny" required>
        Zod schema defining the column's data type and validation rules.
      </ResponseField>
    </Expandable>

    <Expandable title="advanced column definition">
      <ResponseField name="schema" type="z.ZodTypeAny" required>
        Zod schema defining the column's data type and validation rules.
      </ResponseField>

      <ResponseField name="computed" type="boolean">
        Whether this column is computed from other columns. Defaults to false.
      </ResponseField>

      <ResponseField name="searchable" type="boolean">
        Whether this column should be searchable. Defaults to false.
      </ResponseField>

      <ResponseField name="dependencies" type="string[]">
        Array of column names this computed column depends on. Required for computed columns.
      </ResponseField>

      <ResponseField name="value" type="(row: any) => Promise<any>">
        Async function that computes the column value from the row data. Required for computed columns.
      </ResponseField>
    </Expandable>
  </ResponseField>
</Expandable>

<Tip>
  Tables are automatically synced with Botpress Cloud. When you deploy your agent, table schemas are created or updated to match your definitions.
</Tip>