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.