Xata

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}`. 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

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
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
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;
Status CodeDescriptionExample Response/Type Definition
200Returns the results of a successful transaction.
/**
 * 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;
};
400Returns errors from a failed transaction.
/**
 * 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;
};
401Authentication Error
{
  "message": "invalid API key"
}
404Example response
type BranchTransaction = {
    id?: string;
    message: string;
};
5XXUnexpected Error
defaultUnexpected Error