Agentic Platform
Documentation API reference Tools Skills

Tools

Tables Schema

tables_schema MCP

Agent that retrieves the schema (field names and types) for a given table

List all fields from a given table, including enum values when known.

Playground

POST
item
table_name required

Name of the table to get schema for. Wildcard not allowed.

Credits

Fixed cost per item requested. Reading a table's schema is a metadata lookup and scans none of its data.

These usage SKUs can be charged on a call.

SKU Credits Description
Tool call 1 per request Charged once per successful item.

Schemas

item is what you send, config how the tool behaves, and the response is what you get back.

Item

object
Properties
table_name string required

Name of the table to get schema for. Wildcard not allowed.

Example
{
  "table_name": "string"
}

Response

object
Properties
table_name string required

Name of the table

fields array required

List of field definitions with name, type, and enum values when known. A field name containing `{a|b|...}` groups is a compact notation for several columns sharing the same type and mode: expand every group (cartesian product) to get the real column names, e.g. `x__{a|b}__{c|d}` stands for `x__a__c`, `x__a__d`, `x__b__c` and `x__b__d`. Use the expanded names in SQL, never the braces.

Items: TableField

found boolean required

Whether the table was found in the available tables

time_filter TimeFilter

Set when the table grows without bound over time: a query reading it must filter on this column, or it is rejected. Absent otherwise.

Type: TimeFilter

Default: null

retention_floor RetentionFloor

Set when this table only serves part of its history: data before this date is no longer served, here or anywhere else in Botify, and a query asking for it comes back empty. Absent when the whole table is served.

Type: RetentionFloor

Default: null

Example
{
  "table_name": "string",
  "fields": [
    {
      "name": "string",
      "type": "string",
      "mode": "nullable",
      "fields": null,
      "description": null,
      "enum": null,
      "bitmask": null
    }
  ],
  "found": true,
  "time_filter": null,
  "retention_floor": null
}

Type Definitions

4 types

These are the available sub-object types that can be used in the properties above.

RetentionFloor object
#

Oldest data a table serves, the same as everywhere else in Botify.

column string required

Column the floor applies to

date string (date) required

Oldest date served: data before it is no longer served

TableField object
#
name string required
type string required
mode string

`repeated` or `required`; omitted when `nullable` (the default)

Default: "nullable"

fields TableField

Items: TableField

Default: null

description string | null

Optional documentation for this field

Default: null

enum TableFieldEnumValue

Known discrete values for this field. Each entry has value, name, and optional extra; for name columns, entries only carry value. Absent when the field is not an enum.

Items: TableFieldEnumValue

Default: null

bitmask boolean | null

If true, enum values are combinable flags. Test a nonzero flag with `column & value != 0`; for a zero/no-flags value, use `column = 0`.

Default: null

TableFieldEnumValue object
#

One known discrete value of a table field (regular enum or bitmask flag).

value integer | string required
name string required
extra string | null

Default: null

TimeFilter object
#

Column a query must filter on to read a table that grows without bound over time.

column string required

Column to filter on in the WHERE clause of the SELECT reading the table, or the query is rejected

type string required

BigQuery type of the column

example string required

Example of such a filter

date_start string | null

First day with data in the project. Absent when unknown.

Default: null

date_end string | null

Last day with data in the project. Absent when unknown.

Default: null

Endpoints

POST http://agents.botify.com/{organization}/{project}/tables_schema/process
POST http://agents.botify.com/{organization}/{project}/tables_schema/batch_process
POST http://agents.botify.com/{organization}/{project}/tables_schema/async_process
POST http://agents.botify.com/{organization}/{project}/tables_schema/async_batch_process

See running a long job in the background for the polling flow.

cURL

curl -X POST "http://agents.botify.com/{organization}/{project}/tables_schema/process" \
  -H "Authorization: Bearer $BOTIFY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "item": {
    "table_name": "<table_name>"
  }
}'

Over MCP

This tool is exposed as the MCP tool tables_schema. An MCP client passes organization, project and item as tool arguments. Set up MCP →

Raw metadata