Execute a transaction on a branch

https://{your-workspace-slug}.{region}.xata.sh/db/db_branch_name/transaction

Executes multiple operations together as one. This allows you to run a number of operations that succeed as a single group; or fail with no changes to your database.

Expected Parameters
NameDescriptionInRequiredSchema
db_branch_nameThe DBBranchName matches the pattern `{db_name}:{branch_name}`. pathstring

Execute a Transaction on a Branch

POST  https://{your-workspace-slug}.{region}.xata.sh/db/db_branch_name/transaction
Request Body Type Definition
type BranchTransaction = {
    operations: TransactionOperation[];
};

/**
 * A transaction operation
 */
type TransactionOperation = {
    insert: TransactionInsertOp;
} | {
    update: TransactionUpdateOp;
} | {
    ["delete"]: TransactionDeleteOp;
};

/**
 * Insert operation
 */
type TransactionInsertOp = {
    /*
     * The table name
     */
    table: string;
    /*
     * The record to insert. The `id` field is optional; when specified, it will be used as the ID for the record.
     */
    record: {
        [key: string]: any;
    };
    /*
     * The version of the record you expect to be overwriting. Only valid with an
     * explicit ID is also set in the `record` key.
     */
    ifVersion?: number;
    /*
     * createOnly is used to change how Xata acts when an explicit ID is set in the `record` key.
     *
     * If `createOnly` is set to `true`, Xata will only attempt to insert the record. If there's a conflict, Xata
     * will cancel the transaction.
     *
     * If `createOnly` is set to `false`, Xata will attempt to insert the record. If there's no
     * conflict, the record is inserted. If there is a conflict, Xata will replace the record.
     */
    createOnly?: boolean;
};

/**
 * Update operation
 */
type TransactionUpdateOp = {
    /*
     * The table name
     */
    table: string;
    id: RecordID;
    /*
     * The fields of the record you'd like to update
     */
    fields: {
        [key: string]: any;
    };
    /*
     * The version of the record you expect to be updating
     */
    ifVersion?: number;
    /*
     * Xata will insert this record if it cannot be found.
     */
    upsert?: boolean;
};

/**
 * A delete operation. The transaction will continue if no record matches the ID.
 */
type TransactionDeleteOp = {
    /*
     * The table name
     */
    table: string;
    id: RecordID;
};

/**
 * @pattern [a-zA-Z0-9_-~:]+
 */
type RecordID = string;
Possible Responses
Status CodeDescriptionExample Response/Type Definition
200Returns the results of a successful transaction.
type BranchTransaction = {
    /*
     * An ordered array of results from the submitted operations that were executed
     */
    results: (TransactionResultInsert | TransactionResultUpdate | TransactionResultDelete)[];
};

/**
 * A result from an insert operation.
 */
type TransactionResultInsert = {
    /*
     * The type of operation who's result is being returned.
     */
    operation: "insert";
    /*
     * The number of affected rows
     */
    rows: number;
    id: RecordID;
};

/**
 * A result from an update operation.
 */
type TransactionResultUpdate = {
    /*
     * The type of operation who's result is being returned.
     */
    operation: "update";
    /*
     * The number of updated rows
     */
    rows: number;
    id: RecordID;
};

/**
 * A result from a delete operation.
 */
type TransactionResultDelete = {
    /*
     * The type of operation who's result is being returned.
     */
    operation: "delete";
    /*
     * The number of deleted rows
     */
    rows: number;
};

/**
 * @pattern [a-zA-Z0-9_-~:]+
 */
type RecordID = string;
400Returns errors from a failed transaction.
type BranchTransaction = {
    /*
     * An array of errors from the submitted operations.
     */
    errors: TransactionError[];
};

/**
 * An error message from a failing transaction operation
 */
type TransactionError = {
    /*
     * The index of the failing operation
     */
    index?: number;
    /*
     * The error message
     */
    message: string;
};
401Authentication Error
{
  "message": "invalid API key"
}
404Example response
type BranchTransaction = {
    id?: string;
    message: string;
};
5XXUnexpected Error