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

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

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;
} | {
    get: TransactionGetOp;
};
 
/**
 * 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;
    /**
     * If set, the call will return the requested fields as part of the response.
     */
    columns?: string[];
};
 
/**
 * 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;
    /**
     * If set, the call will return the requested fields as part of the response.
     */
    columns?: string[];
};
 
/**
 * A delete operation. The transaction will continue if no record matches the ID by default. To override this behaviour, set failIfMissing to true.
 */
type TransactionDeleteOp = {
    /**
     * The table name
     */
    table: string;
    id: RecordID;
    /**
     * If true, the transaction will fail when the record doesn't exist.
     */
    failIfMissing?: boolean;
    /**
     * If set, the call will return the requested fields as part of the response.
     */
    columns?: string[];
};
 
/**
 * Get by id operation.
 */
type TransactionGetOp = {
    /**
     * The table name
     */
    table: string;
    id: RecordID;
    /**
     * If set, the call will return the requested fields as part of the response.
     */
    columns?: string[];
};
 
/**
 * @maxLength 255
 * @minLength 1
 * @pattern [a-zA-Z0-9_-~:]+
 */
type RecordID = string;

Responses

/**
 * An ordered array of results from the submitted operations.
 */
type BranchTransaction = {
    results: (TransactionResultInsert | TransactionResultUpdate | TransactionResultDelete | TransactionResultGet)[];
};
 
/**
 * 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;
    columns?: TransactionResultColumns;
};
 
/**
 * 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;
    columns?: TransactionResultColumns;
};
 
/**
 * 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;
    columns?: TransactionResultColumns;
};
 
/**
 * A result from a get operation.
 */
type TransactionResultGet = {
    /**
     * The type of operation who's result is being returned.
     */
    operation: "get";
    columns?: TransactionResultColumns;
};
 
/**
 * @maxLength 255
 * @minLength 1
 * @pattern [a-zA-Z0-9_-~:]+
 */
type RecordID = string;
 
/**
 * Fields to return in the transaction result.
 */
type TransactionResultColumns = {
    [key: string]: any;
};

/**
 * An array of errors, with indices, from the transaction.
 */
type BranchTransaction = {
    /**
     * The request ID.
     */
    id: string;
    /**
     * 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;
};

{
    "message": "invalid API key"
}

type BranchTransaction = {
    id?: string;
    message: string;
};

type BranchTransaction = {
    id?: string;
    message: string;
};

type BranchTransaction = void;

type BranchTransaction = void;