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/:

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:

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:

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

src/workflows/create-order.ts

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

Show Table props

name

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

description

string

Optional description of what the table stores.

factor

number

Optional factor for table operations. Defaults to 1.

columns

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.

Show simple column definition

{key}

z.ZodTypeAny

required

Zod schema defining the column’s data type and validation rules.

Show advanced column definition

schema

z.ZodTypeAny

required

Zod schema defining the column’s data type and validation rules.

computed

boolean

Whether this column is computed from other columns. Defaults to false.

searchable

boolean

Whether this column should be searchable. Defaults to false.

dependencies

string[]

Array of column names this computed column depends on. Required for computed columns.

value

(row: any) => Promise<any>

Async function that computes the column value from the row data. Required for computed columns.

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

Get started

ADK

Studio

Integrations

Webchat

Desk

Creating a table

Naming a table

Table schema

Simple definition

Extended definition

Using tables

Reference

​Creating a table

​Naming a table

​Table schema

​Simple definition

​Extended definition

​Using tables

​Reference

Creating a table

Naming a table

Table schema

Simple definition

Extended definition

Using tables

Reference