Table Columns

https://{your-workspace-slug}.{region}.xata.sh/db/db_branch_name/tables/table_name/columns

This endpoint allows working with a table's columns.

Expected Parameters

Name	Description	In	Required	Schema
`db_branch_name`	The DBBranchName matches the pattern `{db_name}:{branch_name}`.	path	✅	string
`table_name`	The Table name	path	✅	string

List Table Columns

GET

https://{your-workspace-slug}.{region}.xata.sh/db/db_branch_name/tables/table_name/columns

Retrieves the list of table columns and their definition. This endpoint returns the column list with object columns being reported with their full dot-separated path (flattened).

Status Code	Description	Example Response/Type Definition
200	OK	`{ "columns": [ { "name": "name", "type": "string" }, { "name": "email", "type": "email" }, { "name": "settings.plan", "type": "string" }, { "name": "settings.dark", "type": "bool" } ] }`
400	Bad Request	`type GetTableColumns = { id?: string; message: string; };`
401	Authentication Error	`{ "message": "invalid API key" }`
404	Example response	`type GetTableColumns = { id?: string; message: string; };`
5XX	Unexpected Error

Create New Column

POST

https://{your-workspace-slug}.{region}.xata.sh/db/db_branch_name/tables/table_name/columns

Adds a new column to the table. The body of the request should contain the column definition. In the column definition, the 'name' field should contain the full path separated by dots. If the parent objects do not exists, they will be automatically created. For example, passing "name": "address.city" will auto-create the address object if it doesn't exist.

Request Body Example

{
  "name": "columnName",
  "type": "string"
}

Request Body Type Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
/**
 * @example {"name":"columnName","type":"string"}
 */
type AddTableColumn = Column;

type Column = {
    name: string;
    type: "bool" | "int" | "float" | "string" | "text" | "email" | "multiple" | "link" | "object" | "datetime" | "vector" | "file[]" | "file";
    link?: ColumnLink;
    vector?: ColumnVector;
    notNull?: boolean;
    defaultValue?: string;
    unique?: boolean;
    columns?: Column[];
};

type ColumnLink = {
    table: string;
};

type ColumnVector = {
    /*
     * @maximum 10000
     * @minimum 2
     */
    dimension: number;
};

Status Code	Description	Example Response/Type Definition
200	Schema migration response with ID and migration status.	`type AddTableColumn = { /* * @minLength 1 */ migrationID: string; parentMigrationID: string; status: MigrationStatus; }; type MigrationStatus = "completed" \| "pending" \| "failed";`
400	Bad Request	`type AddTableColumn = { id?: string; message: string; };`
401	Authentication Error	`{ "message": "invalid API key" }`
404	Example response	`type AddTableColumn = { id?: string; message: string; };`
5XX	Unexpected Error