Bulk Table Operations

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

This endpoint enables bulk operations on a given table. For now, we only allow bulk inserting.

An example bulk request looks like this:

// POST https://tutorial-ng7s8c.xata.sh/db/tutorial:main/tables/users/bulk

{
  "records": [
    {
      "email": "laurence@example.com",
      "full_name": "Laurence Fishburne",
      "team": "rec_c8hng2h26un90p8sr7k0"
    },
    {
      "email": "hugo@example.com",
      "full_name": "Hugo Weaving",
      "team": "rec_c8hng2h26un90p8sr7k0"
    },
    {
      "email": "joe@example.com",
      "full_name": "Joe Pantoliano",
      "team": "rec_c8hng2h26un90p8sr7k0"
    }
  ]
}

For more details, see the this section from the tutorial.

Expected Parameters
NameDescriptionInRequiredSchema
db_branch_nameThe DBBranchName matches the pattern `{db_name}:{branch_name}`. pathstring
table_nameThe Table namepathstring
columnsColumn filtersquery-array

Bulk Insert Records

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

Bulk insert records

Request Body Type Definition
type BulkInsertTableRecords = {
    records: Record<string, any>[];
};

/**
 * Xata Table Record Metadata
 */
type Record = RecordMeta & {
    [key: string]: any;
};

/**
 * Xata Table Record Metadata
 */
type RecordMeta = {
    id: RecordID;
    xata: {
        /*
         * The record's version. Can be used for optimistic concurrency control.
         */
        version: number;
        /*
         * The record's table name. APIs that return records from multiple tables will set this field accordingly.
         */
        table?: string;
        /*
         * Highlights of the record. This is used by the search APIs to indicate which fields and parts of the fields have matched the search.
         */
        highlight?: {
            [key: string]: string[] | {
                [key: string]: any;
            };
        };
        /*
         * The record's relevancy score. This is returned by the search APIs.
         */
        score?: number;
        /*
         * Encoding/Decoding errors
         */
        warnings?: string[];
    };
};

/**
 * @pattern [a-zA-Z0-9_-~:]+
 */
type RecordID = string;
Possible Responses
Status CodeDescriptionExample Response/Type Definition
200OK
type BulkInsertTableRecords = {
    recordIDs: string[];
} | {
    records: Record[];
};

/**
 * Xata Table Record Metadata
 */
type Record = RecordMeta & {
    [key: string]: any;
};

/**
 * Xata Table Record Metadata
 */
type RecordMeta = {
    id: RecordID;
    xata: {
        /*
         * The record's version. Can be used for optimistic concurrency control.
         */
        version: number;
        /*
         * The record's table name. APIs that return records from multiple tables will set this field accordingly.
         */
        table?: string;
        /*
         * Highlights of the record. This is used by the search APIs to indicate which fields and parts of the fields have matched the search.
         */
        highlight?: {
            [key: string]: string[] | {
                [key: string]: any;
            };
        };
        /*
         * The record's relevancy score. This is returned by the search APIs.
         */
        score?: number;
        /*
         * Encoding/Decoding errors
         */
        warnings?: string[];
    };
};

/**
 * @pattern [a-zA-Z0-9_-~:]+
 */
type RecordID = string;
400Response with multiple errors of the bulk execution
type BulkInsertTableRecords = {
    errors: {
        message?: string;
        status?: number;
    }[];
};
401Authentication Error
{
  "message": "invalid API key"
}
404Example response
type BulkInsertTableRecords = {
    id?: string;
    message: string;
};
422Example response
type BulkInsertTableRecords = {
    id?: string;
    message: string;
};
5XXUnexpected Error