Xata Python SDK API Reference
Xata Client
- class xata.XataClient(api_key: str | None = None, region: str = 'us-east-1', workspace_id: str | None = None, db_name: str | None = None, db_url: str | None = None, branch_name: str = 'main', domain_core: str = 'api.xata.io', domain_workspace: str = 'xata.sh')
This is the Xata Client. When initialized, it will attempt to read the relevant configuration (API key, workspace ID, database name, branch name) from the following sources in order:
parameters passed to the constructor
environment variables
.env file
.xatarc configuration file
- Parameters:
api_key – API key to use for authentication.
db_url – The database URL to use. If this is specified, then workspace_id, region and db_name must not be specified.
workspace_id – The workspace ID to use.
region – The region to use.
db_name – The database name to use.
branch_name – The branch name to use. Defaults to main
domain_core – The domain to use for “core”, the control plane. Defaults to api.xata.io.
domain_workspace – The domain to use for “workspace”, data plane. Defaults to xata.sh.
- authentication() Authentication
:returns Authentication
- data() SearchAndFilter
Shorter alias for Search_and_Filter :returns Search_and_filter
- delete_header(name: str) bool
Delete a header from the scope. A header name will be lowercased. :param name: str :returns bool
- get_config() dict
Get the configuration
- get_db_branch_name(db_name: str | None = None, branch_name: str | None = None) str
Get Database with branch name, format: {db_name}:{branch_name} The name can be build with passed params or from config or a combination of both
- Parameters:
db_name – str
- Branch_name:
str
:returns str
- get_headers() dict
Get the static headers that are iniatilized on client init.
- migrations() Migrations
:returns Migrations
- search_and_filter() SearchAndFilter
:returns Search_and_filter
- set_db_and_branch_names(db_name: str | None = None, branch_name: str | None = None)
Set either or both the database - or the branch name
- Parameters:
db_name – str
branch_name – str
- set_header(name: str, value: str)
Set a header value. Every name is lower case and overwrites existing values. This can be useful for some proxies that require certain headers.
- Parameters:
name – str
value – str
- workspaces() Workspaces
:returns Workspaces
- class xata.api_request.ApiRequest(client)
- request(http_method: str, url_path: str, headers: dict = {}, payload: dict | None = None, data: bytes | None = None, is_streaming: bool = False) ApiResponse
- Parameters:
http_method – str
url_path – str
payload – dict = None
data – bytes = None
is_streaming – bool = False
- Headers:
dict = {}
:returns ApiResponse
:raises RateLimitError :raises UnauthorizedError :raises ServerError
- class xata.api_response.ApiResponse(response: Response)
- property content: bytes
For files support, to get the file content :returns bytes
- get_cursor() str | None
If the response has a cursor, return it :returns str or None
- has_more_results() bool
Are there more result pages available? :return bool
- property headers: dict
Get the response headers :returns dict
- is_success() bool
Was the request successful? :returns bool
- json() dict
Legacy support for requests.Response from 0.x :returns dict
Deprecated since version 1.0.0a2: This will be removed in 2.0.0. This method is obsolete as this class directly returns a dict
- server_message() str | None
Get the server message from the response :returns str | None
- property status_code: int
Get the status code of the response :returns int
Data API
- class xata.api.search_and_filter.SearchAndFilter(client)
- aggregate(table_name: str, payload: dict, db_name: str | None = None, branch_name: str | None = None) ApiResponse
This endpoint allows you to run aggregations (analytics) on the data from one table. While the summary endpoint is served from a transactional store and the results are strongly consistent, the aggregate endpoint is served from our columnar store and the results are only eventually consistent. On the other hand, the aggregate endpoint uses a store that is more appropiate for analytics, makes use of approximative algorithms (e.g for cardinality), and is generally faster and can do more complex aggregations.
For usage, see the [API Guide](https://xata.io/docs/api-guide/aggregate).
Reference: https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/aggregate#run-aggregations-over-a-table Path: /db/{db_branch_name}/tables/{table_name}/aggregate Method: POST Response status codes: - 200: OK - 400: Bad Request - 401: Authentication Error - 404: Example response - 5XX: Unexpected Error - default: Unexpected Error
- Parameters:
table_name – str The Table name
payload – dict content
db_name – str = None The name of the database to query. Default: database name from the client.
branch_name – str = None The name of the branch to query. Default: branch name from the client.
:returns ApiResponse
- ask(table_name: str, question: str, rules: list[str] = [], options: dict = {}, streaming_results: bool = False, db_name: str | None = None, branch_name: str | None = None) ApiResponse
Ask your table a question. If the Accept header is set to text/event-stream, Xata will stream the results back as SSE’s.
Reference: https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/ask#ask-your-table-a-question Path: /db/{db_branch_name}/tables/{table_name}/ask Method: POST Response status codes: - 200: Response to the question - 400: Bad Request - 401: Authentication Error - 404: Example response - 429: Rate limit exceeded - 503: ServiceUnavailable - 5XX: Unexpected Error Responses: - application/json - text/event-stream
- Parameters:
table_name – str The Table name
question – str follow up question to ask
rules – list[str] specific rules you want to apply, default: []
options – dict more options to adjust the query, default: {}
streaming_results – bool get the results streamed, default: False
db_name – str = None The name of the database to query. Default: database name from the client.
branch_name – str = None The name of the branch to query. Default: branch name from the client.
:returns ApiResponse
- ask_follow_up(table_name: str, session_id: str, question: str, streaming_results: bool = False, db_name: str | None = None, branch_name: str | None = None) ApiResponse
Ask a follow-up question. If the Accept header is set to text/event-stream, Xata will stream the results back as SSE’s.
Reference: https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/ask/session_id#continue-a-conversation-with-your-data Path: /db/{db_branch_name}/tables/{table_name}/ask/{session_id} Method: POST Response status codes: - 200: Response to the question - 400: Bad Request - 401: Authentication Error - 404: Example response - 429: Rate limit exceeded - 503: ServiceUnavailable - 5XX: Unexpected Error Responses: - application/json - text/event-stream
- Parameters:
table_name – str The Table name
session_id – str Session id from initial question
question – str follow up question to ask
streaming_results – bool get the results streamed, default: False
db_name – str = None The name of the database to query. Default: database name from the client.
branch_name – str = None The name of the branch to query. Default: branch name from the client.
:returns ApiResponse
- query(table_name: str, payload: dict | None = None, db_name: str | None = None, branch_name: str | None = None) ApiResponse
The Query Table API can be used to retrieve all records in a table. The API support filtering, sorting, selecting a subset of columns, and pagination.
The overall structure of the request looks like this:
```json // POST /db/<dbname>:<branch>/tables/<table>/query {
“columns”: […], “filter”: {
“$all”: […], “$any”: […] …
}, “sort”: {
“multiple”: […] …
}, “page”: {
…
}
}
For usage, see also the [API Guide](https://xata.io/docs/api-guide/get).
### Column selection
If the columns array is not specified, all columns are included. For link fields, only the ID column of the linked records is included in the response.
If the columns array is specified, only the selected and internal columns id and xata are included. The * wildcard can be used to select all columns.
For objects and link fields, if the column name of the object is specified, we include all of its sub-keys. If only some sub-keys are specified (via dotted notation, e.g. “settings.plan” ), then only those sub-keys from the object are included.
By the way of example, assuming two tables like this:
- “tables”: [
- {
“name”: “teams”, “columns”: [
- {
“name”: “name”, “type”: “string”
}, {
“name”: “owner”, “type”: “link”, “link”: {
“table”: “users”
}
}, {
“name”: “foundedDate”, “type”: “datetime”
},
]
}, {
“name”: “users”, “columns”: [
- {
“name”: “email”, “type”: “email”
}, {
“name”: “full_name”, “type”: “string”
}, {
“name”: “address”, “type”: “object”, “columns”: [
- {
“name”: “street”, “type”: “string”
}, {
“name”: “number”, “type”: “int”
}, {
“name”: “zipcode”, “type”: “int”
}
]
}, {
“name”: “team”, “type”: “link”, “link”: {
“table”: “teams”
}
}
]
}
]
}
A query like this:
```json POST /db/<dbname>:<branch>/tables/<table>/query {
- “columns”: [
“name”, “address.*”
]
}
returns objects like:
“name”: “Kilian”, “address”: {
“street”: “New street”, “number”: 41, “zipcode”: 10407
}
}
while a query like this:
```json POST /db/<dbname>:<branch>/tables/<table>/query {
- “columns”: [
“name”, “address.street”
]
}
returns objects like:
“id”: “id1” “xata”: {
“version”: 0
} “name”: “Kilian”, “address”: {
“street”: “New street”
}
}
If you want to return all columns from the main table and selected columns from the linked table, you can do it like this:
“columns”: [“*”, “team.name”]
}
The “*” in the above means all columns, including columns of objects. This returns data like:
“id”: “id1” “xata”: {
“version”: 0
} “name”: “Kilian”, “email”: “kilian@gmail.com”, “address”: {
“street”: “New street”, “number”: 41, “zipcode”: 10407
}, “team”: {
“id”: “XX”, “xata”: {
“version”: 0
}, “name”: “first team”
}
}
If you want all columns of the linked table, you can do:
“columns”: [“*”, “team.*”]
}
This returns, for example:
“id”: “id1” “xata”: {
“version”: 0
} “name”: “Kilian”, “email”: “kilian@gmail.com”, “address”: {
“street”: “New street”, “number”: 41, “zipcode”: 10407
}, “team”: {
“id”: “XX”, “xata”: {
“version”: 0
}, “name”: “first team”, “code”: “A1”, “foundedDate”: “2020-03-04T10:43:54.32Z”
}
}
### Filtering
There are two types of operators:
Operators that work on a single column: $is, $contains, $pattern, $includes, $gt, etc.
Control operators that combine multiple conditions: $any, $all, $not , $none, etc.
All operators start with an $ to differentiate them from column names (which are not allowed to start with a dollar sign).
#### Exact matching and control operators
Filter by one column:
- “filter”: {
“<column_name>”: “value”
}
}
This is equivalent to using the $is operator:
- “filter”: {
- “<column_name>”: {
“$is”: “value”
}
}
}
For example:
- “filter”: {
“name”: “r2”
}
}
Or:
- “filter”: {
- “name”: {
“$is”: “r2”
}
}
}
For objects, both dots and nested versions work:
- “filter”: {
“settings.plan”: “free”
}
}
- “filter”: {
- “settings”: {
“plan”: “free”
}
}
}
If you want to OR together multiple values, you can use the $any operator with an array of values:
- “filter”: {
“settings.plan”: { “$any”: [“free”, “paid”] }
}
}
If you specify multiple columns in the same filter, they are logically AND’ed together:
- “filter”: {
“settings.dark”: true, “settings.plan”: “free”
}
}
The above matches if both conditions are met.
To be more explicit about it, you can use $all or $any:
- “filter”: {
- “$any”: {
“settings.dark”: true, “settings.plan”: “free”
}
}
}
The $all and $any operators can also receive an array of objects, which allows for repeating column names:
- “filter”: {
- “$any”: [
- {
“name”: “r1”
}, {
“name”: “r2”
}
]
}
}
You can check for a value being not-null with $exists:
- “filter”: {
“$exists”: “settings”
}
}
This can be combined with $all or $any :
- “filter”: {
- “$all”: [
- {
“$exists”: “settings”
}, {
“$exists”: “name”
}
]
}
}
Or you can use the inverse operator $notExists:
- “filter”: {
“$notExists”: “settings”
}
}
#### Partial match
$contains is the simplest operator for partial matching. Note that $contains operator can cause performance issues at scale, because indices cannot be used.
- “filter”: {
- “<column_name>”: {
“$contains”: “value”
}
}
}
Wildcards are supported via the $pattern operator:
- “filter”: {
- “<column_name>”: {
“$pattern”: “v*alu?”
}
}
}
The $pattern operator accepts two wildcard characters: * * matches zero or more characters * ? matches exactly one character
If you want to match a string that contains a wildcard character, you can escape them using a backslash (``). You can escape a backslash by usign another backslash.
You can also use the $endsWith and $startsWith operators:
- “filter”: {
- “<column_name>”: {
“$endsWith”: “.gz”
}, “<column_name>”: {
“$startsWith”: “tmp-”
}
}
}
#### Numeric or datetime ranges
- “filter”: {
- “<column_name>”: {
“$ge”: 0, “$lt”: 100
}
}
}
Date ranges support the same operators, with the date using the format defined in [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339): ```json {
- “filter”: {
- “<column_name>”: {
“$gt”: “2019-10-12T07:20:50.52Z”, “$lt”: “2021-10-12T07:20:50.52Z”
}
}
}
The supported operators are $gt, $lt, $ge, $le.
#### Negations
A general $not operator can inverse any operation.
- “filter”: {
- “$not”: {
“<column_name1>”: “value1”, “<column_name2>”: “value1”
}
}
}
Note: in the above the two condition are AND together, so this does (NOT ( … AND …))
Or more complex:
- “filter”: {
- “$not”: {
- “$any”: [
- {
“<column_name1>”: “value1”
}, {
- “$all”: [
- {
“<column_name2>”: “value2”
}, {
“<column_name3>”: “value3”
}
]
}
]
}
}
}
The $not: { $any: {}} can be shorted using the $none operator:
- “filter”: {
- “$none”: {
“<column_name1>”: “value1”, “<column_name2>”: “value1”
}
}
}
In addition, you can use operators like $isNot or $notExists to simplify expressions:
- “filter”: {
- “<column_name>”: {
“$isNot”: “2019-10-12T07:20:50.52Z”
}
}
}
#### Working with arrays
To test that an array contains a value, use $includesAny.
- “filter”: {
- “<array_name>”: {
“$includesAny”: “value”
}
}
}
##### includesAny
The $includesAny operator accepts a custom predicate that will check if any value in the array column matches the predicate. The $includes operator is a synonym for the $includesAny operator.
For example a complex predicate can include the $all , $contains and $endsWith operators:
- “filter”: {
- “<array name>”: {
- “$includes”: {
- “$all”: [
{ “$contains”: “label” }, { “$not”: { “$endsWith”: “-debug” } }
]
}
}
}
}
##### includesNone
The $includesNone operator succeeds if no array item matches the predicate.
- “filter”: {
- “settings.labels”: {
“$includesNone”: [{ “$contains”: “label” }]
}
}
}
The above matches if none of the array values contain the string “label”.
##### includesAll
The $includesAll operator succeeds if all array items match the predicate.
Here is an example of using the $includesAll operator:
- “filter”: {
- “settings.labels”: {
“$includesAll”: [{ “$contains”: “label” }]
}
}
}
The above matches if all array values contain the string “label”.
### Sorting
Sorting by one element:
```json POST /db/demo:main/tables/table/query {
- “sort”: {
“index”: “asc”
}
}
or descendently:
```json POST /db/demo:main/tables/table/query {
- “sort”: {
“index”: “desc”
}
}
Sorting by multiple fields:
```json POST /db/demo:main/tables/table/query {
- “sort”: [
- {
“index”: “desc”
}, {
“createdAt”: “desc”
}
]
}
It is also possible to sort results randomly:
```json POST /db/demo:main/tables/table/query {
- “sort”: {
“*”: “random”
}
}
Note that a random sort does not apply to a specific column, hence the special column name “*”.
A random sort can be combined with an ascending or descending sort on a specific column:
```json POST /db/demo:main/tables/table/query {
- “sort”: [
- {
“name”: “desc”
}, {
“*”: “random”
}
]
}
This will sort on the name column, breaking ties randomly.
### Pagination
We offer cursor pagination and offset pagination. The cursor pagination method can be used for sequential scrolling with unrestricted depth. The offset pagination can be used to skip pages and is limited to 1000 records.
Example of cursor pagination:
```json POST /db/demo:main/tables/table/query {
- “page”: {
“after”:”fMoxCsIwFIDh3WP8c4amDai5hO5SJCRNfaVSeC9b6d1FD”
}
}
In the above example, the value of the page.after parameter is the cursor returned by the previous query. A sample response is shown below:
- “meta”: {
- “page”: {
“cursor”: “fMoxCsIwFIDh3WP8c4amDai5hO5SJCRNfaVSeC9b6d1FD”, “more”: true
}
}, “records”: […]
}
The page object might contain the follow keys, in addition to size and offset that were introduced before:
after: Return the next page ‘after’ the current cursor
before: Return the previous page ‘before’ the current cursor.
start: Resets the given cursor position to the beginning of the query result set.
Will return the first N records from the query result, where N is the page.size parameter. - end: Resets the give cursor position to the end for the query result set. Returns the last N records from the query result, where N is the page.size parameter.
The request will fail if an invalid cursor value is given to page.before, page.after, page.start , or page.end. No other cursor setting can be used if page.start or page.end is set in a query.
If both page.before and page.after parameters are present we treat the request as a range query. The range query will return all entries after page.after, but before page.before, up to page.size or the maximum page size. This query requires both cursors to use the same filters and sort settings, plus we require page.after < page.before. The range query returns a new cursor. If the range encompass multiple pages the next page in the range can be queried by update page.after to the returned cursor while keeping the page.before cursor from the first range query.
The filter , columns, sort , and page.size configuration will be encoded with the cursor. The pagination request will be invalid if filter or sort is set. The columns returned and page size can be changed anytime by passing the columns or page.size settings to the next query.
In the following example of size + offset pagination we retrieve the third page of up to 100 results:
```json POST /db/demo:main/tables/table/query {
- “page”: {
“size”: 100, “offset”: 200
}
}
The page.size parameter represents the maximum number of records returned by this query. It has a default value of 20 and a maximum value of 200. The page.offset parameter represents the number of matching records to skip. It has a default value of 0 and a maximum value of 800.
Cursor pagination also works in combination with offset pagination. For example, starting from a specific cursor position, using a page size of 200 and an offset of 800, you can skip up to 5 pages of 200 records forwards or backwards from the cursor’s position:
```json POST /db/demo:main/tables/table/query {
- “page”: {
“size”: 200, “offset”: 800, “after”: “fMoxCsIwFIDh3WP8c4amDai5hO5SJCRNfaVSeC9b6d1FD”
}
}
Special cursors:
page.after=end: Result points past the last entry. The list of records returned is empty, but page.meta.cursor will include a cursor that can be used to “tail” the table from the end waiting for new data to be inserted.
page.before=end: This cursor returns the last page.
page.start=$cursor: Start at the beginning of the result set of the $cursor query. This is equivalent to querying the first page without a cursor but applying filter and sort . Yet the page.start cursor can be convenient at times as user code does not need to remember the filter, sort, columns or page size configuration. All these information are read from the cursor.
page.end=$cursor: Move to the end of the result set of the $cursor query. This is equivalent to querying the last page with page.before=end, filter, and sort . Yet the page.end cursor can be more convenient at times as user code does not need to remember the filter, sort, columns or page size configuration. All these information are read from the cursor.
When using special cursors like page.after=”end” or page.before=”end”, we still allow filter and sort to be set.
Example of getting the last page:
```json POST /db/demo:main/tables/table/query {
- “page”: {
“size”: 10, “before”: “end”
}
}
Reference: https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/query#query-table Path: /db/{db_branch_name}/tables/{table_name}/query Method: POST Response status codes: - 200: OK - 400: Bad Request - 401: Authentication Error - 404: Example response - 503: ServiceUnavailable - 5XX: Unexpected Error - default: Unexpected Error
- param table_name:
str The Table name
- param payload:
dict content
- param db_name:
str = None The name of the database to query. Default: database name from the client.
- param branch_name:
str = None The name of the branch to query. Default: branch name from the client.
:returns ApiResponse
- search_branch(payload: dict, db_name: str | None = None, branch_name: str | None = None) ApiResponse
Run a free text search operation across the database branch.
Reference: https://xata.io/docs/api-reference/db/db_branch_name/search#free-text-search Path: /db/{db_branch_name}/search Method: POST Response status codes: - 200: OK - 400: Bad Request - 401: Authentication Error - 404: Example response - 503: ServiceUnavailable - 5XX: Unexpected Error - default: Unexpected Error
- Parameters:
payload – dict content
db_name – str = None The name of the database to query. Default: database name from the client.
branch_name – str = None The name of the branch to query. Default: branch name from the client.
:returns ApiResponse
- search_table(table_name: str, payload: dict, db_name: str | None = None, branch_name: str | None = None) ApiResponse
Run a free text search operation in a particular table.
The endpoint accepts a query parameter that is used for the free text search and a set of structured filters (via the filter parameter) that are applied before the search. The filter parameter uses the same syntax as the [query endpoint](/api-reference/db/db_branch_name/tables/table_name/) with the following exceptions: * filters $contains, $startsWith, $endsWith don’t work on columns of type text * filtering on columns of type multiple is currently unsupported
Reference: https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/search#free-text-search-in-a-table Path: /db/{db_branch_name}/tables/{table_name}/search Method: POST Response status codes: - 200: OK - 400: Bad Request - 401: Authentication Error - 404: Example response - 5XX: Unexpected Error - default: Unexpected Error
- Parameters:
table_name – str The Table name
payload – dict content
db_name – str = None The name of the database to query. Default: database name from the client.
branch_name – str = None The name of the branch to query. Default: branch name from the client.
:returns ApiResponse
- summarize(table_name: str, payload: dict, db_name: str | None = None, branch_name: str | None = None) ApiResponse
This endpoint allows you to (optionally) define groups, and then to run calculations on the values in each group. This is most helpful when you’d like to understand the data you have in your database.
A group is a combination of unique values. If you create a group for sold_by, product_name, we will return one row for every combination of sold_by and product_name you have in your database. When you want to calculate statistics, you define these groups and ask Xata to calculate data on each group.
Some questions you can ask of your data:
How many records do I have in this table? - Set columns: [] as we we want data from the entire table, so we ask for no groups. - Set summaries: {“total”: {“count”: “*”}} in order to see the count of all records. We use count: * here we’d like to know the total amount of rows; ignoring whether they are null or not.
What are the top total sales for each product in July 2022 and sold more than 10 units? - Set `filter: {soldAt: {
“$ge”: “2022-07-01T00:00:00.000Z”, “$lt”: “2022-08-01T00:00:00.000Z”}
}` in order to limit the result set to sales recorded in July 2022. - Set columns: [product_name] as we’d like to run calculations on each unique product name in our table. Setting columns like this will produce one row per unique product name. - Set summaries: {“total_sales”: {“count”: “product_name”}} as we’d like to create a field called “total_sales” for each group. This field will count all rows in each group with non-null product names. - Set sort: [{“total_sales”: “desc”}] in order to bring the rows with the highest total_sales field to the top. - Set summariesFilter: {“total_sales”: {“$ge”: 10}} to only send back data with greater than or equal to 10 units.
columns: tells Xata how to create each group. If you add product_id we will create a new group for every unique product_id.
summaries: tells Xata which calculations to run on each group. Xata currently supports count, min, max, sum, average.
sort: tells Xata in which order you’d like to see results. You may sort by fields specified in columns as well as the summary names defined in summaries.
note: Sorting on summarized values can be slower on very large tables; this will impact your rate limit significantly more than other queries. Try use filter to reduce the amount of data being processed in order to reduce impact on your limits.
summariesFilter: tells Xata how to filter the results of a summary. It has the same syntax as filter, however, by using summariesFilter you may also filter on the results of a query.
note: This is a much slower to use than filter. We recommend using filter wherever possible and summariesFilter when it’s not possible to use filter.
page.size: tells Xata how many records to return. If unspecified, Xata will return the default size.
Reference: https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/summarize#summarize-table Path: /db/{db_branch_name}/tables/{table_name}/summarize Method: POST Response status codes: - 200: OK - 400: Bad Request - 401: Authentication Error - 404: Example response - 5XX: Unexpected Error - default: Unexpected Error
- Parameters:
table_name – str The Table name
payload – dict content
db_name – str = None The name of the database to query. Default: database name from the client.
branch_name – str = None The name of the branch to query. Default: branch name from the client.
:returns ApiResponse
- vector_search(table_name: str, payload: dict, db_name: str | None = None, branch_name: str | None = None) ApiResponse
This endpoint can be used to perform vector-based similarity searches in a table. It can be used for implementing semantic search and product recommendation. To use this endpoint, you need a column of type vector. The input vector must have the same dimension as the vector column.
Reference: https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/vectorSearch#vector-similarity-search-in-a-table Path: /db/{db_branch_name}/tables/{table_name}/vectorSearch Method: POST Response status codes: - 200: OK - 400: Bad Request - 401: Authentication Error - 404: Example response - 5XX: Unexpected Error - default: Unexpected Error
- Parameters:
table_name – str The Table name
payload – dict content
db_name – str = None The name of the database to query. Default: database name from the client.
branch_name – str = None The name of the branch to query. Default: branch name from the client.
:returns ApiResponse
- class xata.api.records.Records(client)
- bulk_insert(table_name: str, payload: dict, db_name: str | None = None, branch_name: str | None = None, columns: list | None = None) ApiResponse
Bulk insert records
Reference: https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/bulk#bulk-insert-records Path: /db/{db_branch_name}/tables/{table_name}/bulk Method: POST Status: Experimental Response status codes: - 200: OK - 400: Response with multiple errors of the bulk execution - 401: Authentication Error - 404: Example response - 422: Example response - 5XX: Unexpected Error - default: Unexpected Error
- Parameters:
table_name – str The Table name
payload – dict content
db_name – str = None The name of the database to query. Default: database name from the client.
branch_name – str = None The name of the branch to query. Default: branch name from the client.
columns – list = None Column filters
:returns ApiResponse
- delete(table_name: str, record_id: str, db_name: str | None = None, branch_name: str | None = None, columns: list | None = None) ApiResponse
Delete record from table
Reference: https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/data/record_id#delete-record-from-table Path: /db/{db_branch_name}/tables/{table_name}/data/{record_id} Method: DELETE Response status codes: - 200: Table Record Reponse - 204: No Content - 400: Bad Request - 401: Authentication Error - 404: Example response - 5XX: Unexpected Error - default: Unexpected Error
- Parameters:
table_name – str The Table name
record_id – str The Record name
db_name – str = None The name of the database to query. Default: database name from the client.
branch_name – str = None The name of the branch to query. Default: branch name from the client.
columns – list = None Column filters
:returns ApiResponse
- get(table_name: str, record_id: str, db_name: str | None = None, branch_name: str | None = None, columns: list | None = None) ApiResponse
Retrieve record by ID
Reference: https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/data/record_id#get-record-by-id Path: /db/{db_branch_name}/tables/{table_name}/data/{record_id} Method: GET Response status codes: - 200: Table Record Reponse - 400: Bad Request - 401: Authentication Error - 404: Example response - 5XX: Unexpected Error - default: Unexpected Error
- Parameters:
table_name – str The Table name
record_id – str The Record name
db_name – str = None The name of the database to query. Default: database name from the client.
branch_name – str = None The name of the branch to query. Default: branch name from the client.
columns – list = None Column filters
:returns ApiResponse
- insert(table_name: str, payload: dict, db_name: str | None = None, branch_name: str | None = None, columns: list | None = None) ApiResponse
Insert a new Record into the Table
Reference: https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/data#insert-record Path: /db/{db_branch_name}/tables/{table_name}/data Method: POST Response status codes: - 201: Record ID and metadata - 400: Bad Request - 401: Authentication Error - 404: Example response - 5XX: Unexpected Error - default: Unexpected Error
- Parameters:
table_name – str The Table name
payload – dict content
db_name – str = None The name of the database to query. Default: database name from the client.
branch_name – str = None The name of the branch to query. Default: branch name from the client.
columns – list = None Column filters
:returns ApiResponse
- insert_with_id(table_name: str, record_id: str, payload: dict, db_name: str | None = None, branch_name: str | None = None, columns: list | None = None, create_only: bool | None = None, if_version: int | None = None) ApiResponse
By default, IDs are auto-generated when data is insterted into Xata. Sending a request to this endpoint allows us to insert a record with a pre-existing ID, bypassing the default automatic ID generation.
Reference: https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/data/record_id#insert-record-with-id Path: /db/{db_branch_name}/tables/{table_name}/data/{record_id} Method: PUT Response status codes: - 200: Record ID and metadata - 201: Record ID and metadata - 400: Bad Request - 401: Authentication Error - 404: Example response - 422: Example response - 5XX: Unexpected Error - default: Unexpected Error
- Parameters:
table_name – str The Table name
record_id – str The Record name
payload – dict content
db_name – str = None The name of the database to query. Default: database name from the client.
branch_name – str = None The name of the branch to query. Default: branch name from the client.
columns – list = None Column filters
create_only – bool = None
if_version – int = None
:returns ApiResponse
- transaction(payload: dict, db_name: str | None = None, branch_name: str | None = None) ApiResponse
Execute a transaction on a branch
Reference: https://xata.io/docs/api-reference/db/db_branch_name/transaction#execute-a-transaction-on-a-branch Path: /db/{db_branch_name}/transaction Method: POST Response status codes: - 200: Returns the results of a successful transaction. - 400: Returns errors from a failed transaction. - 401: Authentication Error - 404: Example response - 429: Rate limit exceeded - 5XX: Unexpected Error - default: Unexpected Error Response: application/json
- Parameters:
payload – dict content
db_name – str = None The name of the database to query. Default: database name from the client.
branch_name – str = None The name of the branch to query. Default: branch name from the client.
:returns ApiResponse
- update(table_name: str, record_id: str, payload: dict, db_name: str | None = None, branch_name: str | None = None, columns: list | None = None, if_version: int | None = None) ApiResponse
Update record with ID
Reference: https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/data/record_id#update-record-with-id Path: /db/{db_branch_name}/tables/{table_name}/data/{record_id} Method: PATCH Response status codes: - 200: Record ID and metadata - 400: Bad Request - 401: Authentication Error - 404: Example response - 422: Example response - 5XX: Unexpected Error - default: Unexpected Error
- Parameters:
table_name – str The Table name
record_id – str The Record name
payload – dict content
db_name – str = None The name of the database to query. Default: database name from the client.
branch_name – str = None The name of the branch to query. Default: branch name from the client.
columns – list = None Column filters
if_version – int = None
:returns ApiResponse
- upsert(table_name: str, record_id: str, payload: dict, db_name: str | None = None, branch_name: str | None = None, columns: list | None = None, if_version: int | None = None) ApiResponse
Upsert record with ID
Reference: https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/data/record_id#upsert-record-with-id Path: /db/{db_branch_name}/tables/{table_name}/data/{record_id} Method: POST Response status codes: - 200: Record ID and metadata - 201: Record ID and metadata - 400: Bad Request - 401: Authentication Error - 404: Example response - 422: Example response - 5XX: Unexpected Error - default: Unexpected Error
- Parameters:
table_name – str The Table name
record_id – str The Record name
payload – dict content
db_name – str = None The name of the database to query. Default: database name from the client.
branch_name – str = None The name of the branch to query. Default: branch name from the client.
columns – list = None Column filters
if_version – int = None
:returns ApiResponse
- class xata.api.files.Files(client)
- delete(table_name: str, record_id: str, column_name: str, db_name: str | None = None, branch_name: str | None = None) ApiResponse
Deletes a file referred in a file column
Path: /db/{db_branch_name}/tables/{table_name}/data/{record_id}/column/{column_name}/file Method: DELETE Response status codes: - 200: OK - 400: Bad Request - 401: Authentication Error - 404: Example response - 5XX: Unexpected Error
- Parameters:
table_name – str The Table name
record_id – str The Record name
column_name – str The Column name
db_name – str = None The name of the database to query. Default: database name from the client.
branch_name – str = None The name of the branch to query. Default: branch name from the client.
:return ApiResponse
- delete_item(table_name: str, record_id: str, column_name: str, file_id: str, db_name: str | None = None, branch_name: str | None = None) ApiResponse
Deletes an item from an file array column given the file ID
Path: /db/{db_branch_name}/tables/{table_name}/data/{record_id}/column/{column_name}/file/{file_id} Method: DELETE Response status codes: - 200: OK - 400: Bad Request - 401: Authentication Error - 404: Example response - 5XX: Unexpected Error
- Parameters:
table_name – str The Table name
record_id – str The Record name
column_name – str The Column name
file_id – str The File Identifier
db_name – str = None The name of the database to query. Default: database name from the client.
branch_name – str = None The name of the branch to query. Default: branch name from the client.
:return ApiResponse
- get(table_name: str, record_id: str, column_name: str, db_name: str | None = None, branch_name: str | None = None) ApiResponse
Retrieves the file content from a file column
Path: /db/{db_branch_name}/tables/{table_name}/data/{record_id}/column/{column_name}/file Method: GET Response status codes: - 200: OK - 204: no content - 400: Bad Request - 401: Authentication Error - 404: Example response - 5XX: Unexpected Error Response: /
- Parameters:
table_name – str The Table name
record_id – str The Record name
column_name – str The Column name
db_name – str = None The name of the database to query. Default: database name from the client.
branch_name – str = None The name of the branch to query. Default: branch name from the client.
:return ApiResponse
- get_item(table_name: str, record_id: str, column_name: str, file_id: str, db_name: str | None = None, branch_name: str | None = None) ApiResponse
Retrieves file content from an array by file ID
Path: /db/{db_branch_name}/tables/{table_name}/data/{record_id}/column/{column_name}/file/{file_id} Method: GET Response status codes: - 200: OK - 400: Bad Request - 401: Authentication Error - 404: Example response - 5XX: Unexpected Error Response: /
- Parameters:
table_name – str The Table name
record_id – str The Record name
column_name – str The Column name
file_id – str The File Identifier
db_name – str = None The name of the database to query. Default: database name from the client.
branch_name – str = None The name of the branch to query. Default: branch name from the client.
:return ApiResponse
- put(table_name: str, record_id: str, column_name: str, data: bytes, content_type: str = 'application/octet-stream', db_name: str | None = None, branch_name: str | None = None) ApiResponse
Uploads the file content to the given file column
Path: /db/{db_branch_name}/tables/{table_name}/data/{record_id}/column/{column_name}/file Method: PUT Response status codes: - 200: OK - 201: OK - 400: Bad Request - 401: Authentication Error - 404: Example response - 422: Example response - 5XX: Unexpected Error
- Parameters:
table_name – str The Table name
record_id – str The Record name
column_name – str The Column name
data – bytes
db_name – str = None The name of the database to query. Default: database name from the client.
branch_name – str = None The name of the branch to query. Default: branch name from the client.
:return ApiResponse
- put_item(table_name: str, record_id: str, column_name: str, file_id: str, data: bytes, content_type: str = 'application/octet-stream', db_name: str | None = None, branch_name: str | None = None) ApiResponse
Uploads the file content to an array given the file ID
Path: /db/{db_branch_name}/tables/{table_name}/data/{record_id}/column/{column_name}/file/{file_id} Method: PUT Response status codes: - 200: OK - 201: OK - 400: Bad Request - 401: Authentication Error - 404: Example response - 422: Example response - 5XX: Unexpected Error
- Parameters:
table_name – str The Table name
record_id – str The Record name
column_name – str The Column name
file_id – str The File Identifier
data – bytes content
content_type – str Default: “application/octet-stream”
db_name – str = None The name of the database to query. Default: database name from the client.
branch_name – str = None The name of the branch to query. Default: branch name from the client.
:return ApiResponse
- transform(url: str, operations: dict[str, any]) bytes
Image transformations All possible combinations: https://xata.io/docs/concepts/file-storage#image-transformations
- Parameters:
url – str Public or signed URL of the image
operations – dict Image operations
:return Response
Management API
- class xata.api.databases.Databases(client)
- create(db_name: str, workspace_id: str | None = None, region: str | None = None, branch_name: str | None = None) ApiResponse
Create Database with identifier name
Reference: https://xata.io/docs/api-reference/workspaces/workspace_id/dbs/db_name#create-database Path: /workspaces/{workspace_id}/dbs/{db_name} Method: PUT Response status codes: - 201: Created - 400: Bad Request - 401: Authentication Error - 422: Example response - 423: Example response - 5XX: Unexpected Error Response: application/json
- Parameters:
db_name – str The Database Name
workspace_id – str = None The workspace identifier. Default: workspace Id from the client.
region – str = None Which region to deploy. Default: region defined in the client, if not specified: us-east-1
branch_name – str = None Which branch to create. Default: branch name used from the client, if not speicifed: main
:return Response
- delete(db_name: str, workspace_id: str | None = None) ApiResponse
Delete a database and all of its branches and tables permanently.
Reference: https://xata.io/docs/api-reference/workspaces/workspace_id/dbs/db_name#delete-database Path: /workspaces/{workspace_id}/dbs/{db_name} Method: DELETE Response status codes: - 200: OK - 400: Bad Request - 401: Authentication Error - 404: Example response - 5XX: Unexpected Error Response: application/json
- Parameters:
db_name – str The Database Name
workspace_id – str = None The workspace identifier. Default: workspace Id from the client.
:returns ApiResponse
- get_metadata(db_name: str, workspace_id: str | None = None) ApiResponse
Retrieve metadata of the given database
Reference: https://xata.io/docs/api-reference/workspaces/workspace_id/dbs/db_name#get-database-metadata Path: /workspaces/{workspace_id}/dbs/{db_name} Method: GET Response status codes: - 200: OK - 400: Bad Request - 401: Authentication Error - 404: Example response - 5XX: Unexpected Error Response: application/json
- Parameters:
db_name – str The Database Name
workspace_id – str = None The workspace identifier. Default: workspace Id from the client.
:returns ApiResponse
- get_regions(workspace_id: str | None = None) ApiResponse
List regions available to create a database on
Reference: https://xata.io/docs/api-reference/workspaces/workspace_id/regions#list-available-regions Path: /workspaces/{workspace_id}/regions Method: GET Response status codes: - 200: OK - 400: Bad Request - 401: Authentication Error - 5XX: Unexpected Error Response: application/json
- Parameters:
workspace_id – str = None The workspace identifier. Default: workspace Id from the client.
:returns ApiResponse
- list(workspace_id: str | None = None) ApiResponse
List all databases available in your Workspace.
Reference: https://xata.io/docs/api-reference/workspaces/workspace_id/dbs#list-databases Path: /workspaces/{workspace_id}/dbs Method: GET Response status codes: - 200: OK - 400: Bad Request - 401: Authentication Error - 5XX: Unexpected Error Response: application/json
- Parameters:
workspace_id – str = None The workspace identifier. Default: workspace Id from the client.
:returns ApiResponse
- rename(db_name: str, new_name: str, workspace_id: str | None = None) ApiResponse
Change the name of an existing database
Reference: https://xata.io/docs/api-reference/workspaces/workspace_id/dbs/db_name/rename#rename-database Path: /workspaces/{workspace_id}/dbs/{db_name}/rename Method: POST Response status codes: - 200: OK - 400: Bad Request - 401: Authentication Error - 422: Example response - 423: Example response - 5XX: Unexpected Error Response: application/json
- Parameters:
db_name – str Current database name
new_name – str New database name
workspace_id – str = None The workspace identifier. Default: workspace Id from the client.
:return Response
- update_metadata(db_name: str, payload: dict, workspace_id: str | None = None) ApiResponse
Update the color of the selected database
Reference: https://xata.io/docs/api-reference/workspaces/workspace_id/dbs/db_name#update-database-metadata Path: /workspaces/{workspace_id}/dbs/{db_name} Method: PATCH Response status codes: - 200: OK - 400: Bad Request - 401: Authentication Error - 404: Example response - 5XX: Unexpected Error Response: application/json
- Parameters:
db_name – str The Database Name
payload – dict content
workspace_id – str = None The workspace identifier. Default: workspace Id from the client.
:returns ApiResponse
- class xata.api.branch.Branch(client)
- add_git_branches_entry(db_name: str, payload: dict) ApiResponse
Adds an entry to the mapping of git branches to Xata branches. The git branch and the Xata branch must be present in the body of the request. If the Xata branch doesn’t exist, a 400 error is returned.
If the git branch is already present in the mapping, the old entry is overwritten, and a warning message is included in the response. If the git branch is added and didn’t exist before, the response code is 204. If the git branch existed and it was overwritten, the response code is 201.
Example request:
```json // POST https://tutorial-ng7s8c.xata.sh/dbs/demo/gitBranches {
“gitBranch”: “fix/bug123”, “xataBranch”: “fix_bug”
}
Reference: https://xata.io/docs/api-reference/dbs/db_name/gitBranches#link-a-git-branch-to-a-xata-branch Path: /dbs/{db_name}/gitBranches Method: POST Response status codes: - 201: Operation was successful with warnings - 204: Operation was successful without warnings - 400: Bad Request - 401: Authentication Error - 5XX: Unexpected Error - default: Unexpected Error Response: application/json
- param db_name:
str The Database Name
- param payload:
dict content
:returns ApiResponse
- create(payload: dict, db_name: str | None = None, branch_name: str | None = None, from_: str | None = None) ApiResponse
Create Database branch
Reference: https://xata.io/docs/api-reference/db/db_branch_name#create-database-branch Path: /db/{db_branch_name} Method: PUT Response status codes: - 201: Created - 400: Bad Request - 401: Authentication Error - 404: Example response - 423: Example response - 5XX: Unexpected Error - default: Unexpected Error Response: application/json
- Parameters:
payload – dict content
db_name – str = None The name of the database to query. Default: database name from the client.
branch_name – str = None The name of the branch to query. Default: branch name from the client.
from – str = None Name of source branch to branch the new schema from
:returns ApiResponse
- delete(db_name: str | None = None, branch_name: str | None = None) ApiResponse
Delete the branch in the database and all its resources
Reference: https://xata.io/docs/api-reference/db/db_branch_name#delete-database-branch Path: /db/{db_branch_name} Method: DELETE Response status codes: - 200: OK - 400: Bad Request - 401: Authentication Error - 404: Example response - 409: Example response - 5XX: Unexpected Error - default: Unexpected Error Response: application/json
- Parameters:
db_name – str = None The name of the database to query. Default: database name from the client.
branch_name – str = None The name of the branch to query. Default: branch name from the client.
:returns ApiResponse
- get_details(db_name: str | None = None, branch_name: str | None = None) ApiResponse
Get branch schema and metadata
Reference: https://xata.io/docs/api-reference/db/db_branch_name#get-branch-schema-and-metadata Path: /db/{db_branch_name} Method: GET Response status codes: - 200: OK - 400: Bad Request - 401: Authentication Error - 404: Example response - 5XX: Unexpected Error - default: Unexpected Error Response: application/json
- Parameters:
db_name – str = None The name of the database to query. Default: database name from the client.
branch_name – str = None The name of the branch to query. Default: branch name from the client.
:returns ApiResponse
- get_git_branches_mapping(db_name: str) ApiResponse
Lists all the git branches in the mapping, and their associated Xata branches.
Example response:
- “mappings”: [
- {
“gitBranch”: “main”, “xataBranch”: “main”
}, {
“gitBranch”: “gitBranch1”, “xataBranch”: “xataBranch1”
“gitBranch”: “xataBranch2”, “xataBranch”: “xataBranch2”
}
]
}
Reference: https://xata.io/docs/api-reference/dbs/db_name/gitBranches#list-git-branches-mapping Path: /dbs/{db_name}/gitBranches Method: GET Response status codes: - 200: OK - 400: Bad Request - 401: Authentication Error - 5XX: Unexpected Error - default: Unexpected Error Response: application/json
- param db_name:
str The Database Name
:returns ApiResponse
- get_metadata(db_name: str | None = None, branch_name: str | None = None) ApiResponse
Get Branch Metadata
Reference: https://xata.io/docs/api-reference/db/db_branch_name/metadata#get-branch-metadata Path: /db/{db_branch_name}/metadata Method: GET Response status codes: - 200: OK - 400: Bad Request - 401: Authentication Error - 404: Example response - 5XX: Unexpected Error - default: Unexpected Error Response: application/json
- Parameters:
db_name – str = None The name of the database to query. Default: database name from the client.
branch_name – str = None The name of the branch to query. Default: branch name from the client.
:returns ApiResponse
- get_stats(db_name: str | None = None, branch_name: str | None = None) ApiResponse
Get branch usage metrics.
Reference: https://xata.io/docs/api-reference/db/db_branch_name/stats#branch-stats Path: /db/{db_branch_name}/stats Method: GET Response status codes: - 200: OK - 400: Example response - 401: Authentication Error - 404: Example response - 5XX: Unexpected Error - default: Unexpected Error Response: application/json
- Parameters:
db_name – str = None The name of the database to query. Default: database name from the client.
branch_name – str = None The name of the branch to query. Default: branch name from the client.
:returns ApiResponse
- list(db_name: str) ApiResponse
List all available Branches
Reference: https://xata.io/docs/api-reference/dbs/db_name#list-branches Path: /dbs/{db_name} Method: GET Response status codes: - 200: OK - 400: Bad Request - 401: Authentication Error - 404: Example response - 5XX: Unexpected Error - default: Unexpected Error Response: application/json
- Parameters:
db_name – str The Database Name
:returns ApiResponse
- remove_git_branches_entry(db_name: str, git_branch: str) ApiResponse
Removes an entry from the mapping of git branches to Xata branches. The name of the git branch must be passed as a query parameter. If the git branch is not found, the endpoint returns a 404 status code.
Example request:
`json // DELETE https://tutorial-ng7s8c.xata.sh/dbs/demo/gitBranches?gitBranch=fix%2Fbug123 `Reference: https://xata.io/docs/api-reference/dbs/db_name/gitBranches#unlink-a-git-branch-to-a-xata-branch Path: /dbs/{db_name}/gitBranches Method: DELETE Response status codes: - 204: OK - 400: Bad Request - 401: Authentication Error - 404: The git branch was not found in the mapping - 5XX: Unexpected Error - default: Unexpected Error
- Parameters:
db_name – str The Database Name
git_branch – str The Git Branch to remove from the mapping
:returns ApiResponse
- resolve(db_name: str, git_branch: str | None = None, fallback_branch: str | None = None) ApiResponse
In order to resolve the database branch, the following algorithm is used: * if the gitBranch was provided and is found in the [git branches mapping](/api-reference/dbs/db_name/gitBranches), the associated Xata branch is returned * else, if a Xata branch with the exact same name as gitBranch exists, return it * else, if fallbackBranch is provided and a branch with that name exists, return it * else, return the default branch of the DB (main or the first branch)
Example call:
`json // GET https://tutorial-ng7s8c.xata.sh/dbs/demo/dbs/demo/resolveBranch?gitBranch=test&fallbackBranch=tsg `Example response:
“branch”: “main”, “reason”: {
“code”: “DEFAULT_BRANCH”, “message”: “Default branch for this database (main)”
}
}
Reference: https://xata.io/docs/api-reference/dbs/db_name/resolveBranch#resolve-a-git-branch-to-a-xata-branch Path: /dbs/{db_name}/resolveBranch Method: GET Response status codes: - 200: OK - 400: Bad Request - 401: Authentication Error - 5XX: Unexpected Error - default: Unexpected Error Response: application/json
- param db_name:
str The Database Name
- param git_branch:
str = None The Git Branch
- param fallback_branch:
str = None Default branch to fallback to
:returns ApiResponse
- update_metadata(payload: dict, db_name: str | None = None, branch_name: str | None = None) ApiResponse
Update the branch metadata
Reference: https://xata.io/docs/api-reference/db/db_branch_name/metadata#update-branch-metadata Path: /db/{db_branch_name}/metadata Method: PUT Response status codes: - 204: No Content - 400: Bad Request - 401: Authentication Error - 404: Example response - 5XX: Unexpected Error - default: Unexpected Error
- Parameters:
payload – dict content
db_name – str = None The name of the database to query. Default: database name from the client.
branch_name – str = None The name of the branch to query. Default: branch name from the client.
:returns ApiResponse
- class xata.api.table.Table(client)
- add_column(table_name: str, payload: dict, db_name: str | None = None, branch_name: str | None = None) ApiResponse
Adds a new column to the table. The body of the request should contain the column definition.
Reference: https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/columns#create-new-column Path: /db/{db_branch_name}/tables/{table_name}/columns Method: POST Response status codes: - 200: Schema migration response with ID and migration status. - 400: Bad Request - 401: Authentication Error - 404: Example response - 5XX: Unexpected Error - default: Unexpected Error
- Parameters:
table_name – str The Table name
payload – dict content
db_name – str = None The name of the database to query. Default: database name from the client.
branch_name – str = None The name of the branch to query. Default: branch name from the client.
:returns ApiResponse
- create(table_name: str, db_name: str | None = None, branch_name: str | None = None) ApiResponse
Creates a new table with the given name. Returns 422 if a table with the same name already exists.
Reference: https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name#create-table Path: /db/{db_branch_name}/tables/{table_name} Method: PUT Response status codes: - 201: Created - 204: No Content - 400: Bad Request - 401: Authentication Error - 404: Example response - 422: Example response - 5XX: Unexpected Error - default: Unexpected Error Response: application/json
- Parameters:
table_name – str The Table name
db_name – str = None The name of the database to query. Default: database name from the client.
branch_name – str = None The name of the branch to query. Default: branch name from the client.
:returns ApiResponse
- delete(table_name: str, db_name: str | None = None, branch_name: str | None = None) ApiResponse
Deletes the table with the given name.
Reference: https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name#delete-table Path: /db/{db_branch_name}/tables/{table_name} Method: DELETE Response status codes: - 200: OK - 400: Bad Request - 401: Authentication Error - 404: Not Found - 5XX: Unexpected Error - default: Unexpected Error Response: application/json
- Parameters:
table_name – str The Table name
db_name – str = None The name of the database to query. Default: database name from the client.
branch_name – str = None The name of the branch to query. Default: branch name from the client.
:returns ApiResponse
- delete_column(table_name: str, column_name: str, db_name: str | None = None, branch_name: str | None = None) ApiResponse
Deletes the specified column.
Reference: https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/columns/column_name#delete-column Path: /db/{db_branch_name}/tables/{table_name}/columns/{column_name} Method: DELETE Response status codes: - 200: Schema migration response with ID and migration status. - 400: Bad Request - 401: Authentication Error - 404: Example response - 5XX: Unexpected Error - default: Unexpected Error
- Parameters:
table_name – str The Table name
column_name – str The Column name
db_name – str = None The name of the database to query. Default: database name from the client.
branch_name – str = None The name of the branch to query. Default: branch name from the client.
:returns ApiResponse
- get_column(table_name: str, column_name: str, db_name: str | None = None, branch_name: str | None = None) ApiResponse
Get the definition of a single column.
Reference: https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/columns/column_name#get-column-information Path: /db/{db_branch_name}/tables/{table_name}/columns/{column_name} Method: GET Response status codes: - 200: OK - 400: Bad Request - 401: Authentication Error - 404: Example response - 5XX: Unexpected Error - default: Unexpected Error Response: application/json
- Parameters:
table_name – str The Table name
column_name – str The Column name
db_name – str = None The name of the database to query. Default: database name from the client.
branch_name – str = None The name of the branch to query. Default: branch name from the client.
:returns ApiResponse
- get_columns(table_name: str, db_name: str | None = None, branch_name: str | None = None) ApiResponse
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).
Reference: https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/columns#list-table-columns Path: /db/{db_branch_name}/tables/{table_name}/columns Method: GET Response status codes: - 200: OK - 400: Bad Request - 401: Authentication Error - 404: Example response - 5XX: Unexpected Error - default: Unexpected Error Response: application/json
- Parameters:
table_name – str The Table name
db_name – str = None The name of the database to query. Default: database name from the client.
branch_name – str = None The name of the branch to query. Default: branch name from the client.
:returns ApiResponse
- get_schema(table_name: str, db_name: str | None = None, branch_name: str | None = None) ApiResponse
Get table schema
Reference: https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/schema#get-table-schema Path: /db/{db_branch_name}/tables/{table_name}/schema Method: GET Response status codes: - 200: OK - 400: Bad Request - 401: Authentication Error - 404: Example response - 5XX: Unexpected Error - default: Unexpected Error Response: application/json
- Parameters:
table_name – str The Table name
db_name – str = None The name of the database to query. Default: database name from the client.
branch_name – str = None The name of the branch to query. Default: branch name from the client.
:returns ApiResponse
- set_schema(table_name: str, payload: dict, db_name: str | None = None, branch_name: str | None = None) ApiResponse
Update table schema
Reference: https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/schema#update-table-schema Path: /db/{db_branch_name}/tables/{table_name}/schema Method: PUT Response status codes: - 200: Schema migration response with ID and migration status. - 204: No Content - 400: Bad Request - 401: Authentication Error - 404: Example response - 409: Example response - 5XX: Unexpected Error - default: Unexpected Error
- Parameters:
table_name – str The Table name
payload – dict content
db_name – str = None The name of the database to query. Default: database name from the client.
branch_name – str = None The name of the branch to query. Default: branch name from the client.
:returns ApiResponse
- update(table_name: str, payload: dict, db_name: str | None = None, branch_name: str | None = None) ApiResponse
Update table. Currently there is only one update operation supported: renaming the table by providing a new name.
In the example below, we rename a table from “users” to “people”:
```json // PATCH /db/test:main/tables/users
- {
“name”: “people”
}
Reference: https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name#update-table Path: /db/{db_branch_name}/tables/{table_name} Method: PATCH Response status codes: - 200: Schema migration response with ID and migration status. - 400: Bad Request - 401: Authentication Error - 404: Example response - 422: Example response - 5XX: Unexpected Error - default: Unexpected Error
- param table_name:
str The Table name
- param payload:
dict content
- param db_name:
str = None The name of the database to query. Default: database name from the client.
- param branch_name:
str = None The name of the branch to query. Default: branch name from the client.
:returns ApiResponse
- update_column(table_name: str, column_name: str, payload: dict, db_name: str | None = None, branch_name: str | None = None) ApiResponse
Update column with partial data. Can be used for renaming the column by providing a new “name” field.
Reference: https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/columns/column_name#update-column Path: /db/{db_branch_name}/tables/{table_name}/columns/{column_name} Method: PATCH Response status codes: - 200: Schema migration response with ID and migration status. - 400: Bad Request - 401: Authentication Error - 404: Example response - 5XX: Unexpected Error - default: Unexpected Error
- Parameters:
table_name – str The Table name
column_name – str The Column name
payload – dict content
db_name – str = None The name of the database to query. Default: database name from the client.
branch_name – str = None The name of the branch to query. Default: branch name from the client.
:returns ApiResponse
- class xata.api.authentication.Authentication(client)
- create_user_api_keys(key_name: str) ApiResponse
Create and return new API key
Reference: https://xata.io/docs/api-reference/user/keys/key_name#create-and-return-new-api-key Path: /user/keys/{key_name} Method: POST Response status codes: - 201: OK - 400: Bad Request - 401: Authentication Error - 404: Example response - 5XX: Unexpected Error Response: application/json
- Parameters:
key_name – str API Key name
:returns ApiResponse
- delete_user_api_keys(key_name: str) ApiResponse
Delete an existing API key
Reference: https://xata.io/docs/api-reference/user/keys/key_name#delete-an-existing-api-key Path: /user/keys/{key_name} Method: DELETE Response status codes: - 204: No Content - 400: Bad Request - 401: Authentication Error - 404: Example response - 5XX: Unexpected Error
- Parameters:
key_name – str API Key name
:returns ApiResponse
- get_user_api_keys() ApiResponse
Retrieve a list of existing user API keys
Reference: https://xata.io/docs/api-reference/user/keys#get-the-list-of-user-api-keys Path: /user/keys Method: GET Response status codes: - 200: OK - 400: Bad Request - 401: Authentication Error - 404: Example response - 5XX: Unexpected Error Response: application/json
:returns ApiResponse
- class xata.api.users.Users(client)
- delete() ApiResponse
Delete the user making the request
Reference: https://xata.io/docs/api-reference/user#delete-user Path: /user Method: DELETE Response status codes: - 204: No Content - 400: Bad Request - 401: Authentication Error - 404: Example response - 5XX: Unexpected Error
:returns ApiResponse
- get() ApiResponse
Return details of the user making the request
Reference: https://xata.io/docs/api-reference/user#get-user-details Path: /user Method: GET Response status codes: - 200: OK - 400: Bad Request - 401: Authentication Error - 404: Example response - 5XX: Unexpected Error Response: application/json
:returns ApiResponse
- update(payload: dict) ApiResponse
Update user info
Reference: https://xata.io/docs/api-reference/user#update-user-info Path: /user Method: PUT Response status codes: - 200: OK - 400: Bad Request - 401: Authentication Error - 404: Example response - 5XX: Unexpected Error Response: application/json
- Parameters:
payload – dict content
:returns ApiResponse
- class xata.api.workspaces.Workspaces(client)
- create(name: str, slug: str | None = None) ApiResponse
Creates a new workspace with the user requesting it as its single owner.
Path: /workspaces Method: POST Response status codes: - 201: Created - 400: Bad Request - 401: Authentication Error - 404: Example response - 5XX: Unexpected Error Response: application/json
- Parameters:
name – str Workspace name
slug – str = None Slug to use
:return Response
- delete(workspace_id: str | None = None) ApiResponse
Delete the workspace with the provided ID
Reference: https://xata.io/docs/api-reference/workspaces/workspace_id#delete-an-existing-workspace Path: /workspaces/{workspace_id} Method: DELETE Response status codes: - 204: No Content - 400: Bad Request - 401: Authentication Error - 403: Authentication Error - 404: Example response - 5XX: Unexpected Error
- Parameters:
workspace_id – str = None The workspace identifier. Default: workspace Id from the client.
:returns ApiResponse
- get(workspace_id: str | None = None) ApiResponse
Retrieve workspace info from a workspace ID
Reference: https://xata.io/docs/api-reference/workspaces/workspace_id#get-an-existing-workspace Path: /workspaces/{workspace_id} Method: GET Response status codes: - 200: OK - 400: Bad Request - 401: Authentication Error - 403: Authentication Error - 404: Example response - 5XX: Unexpected Error Response: application/json
- Parameters:
workspace_id – str = None The workspace identifier. Default: workspace Id from the client.
:returns ApiResponse
- get_members(workspace_id: str | None = None) ApiResponse
Retrieve the list of members of the given workspace
Reference: https://xata.io/docs/api-reference/workspaces/workspace_id/members#get-the-list-members-of-a-workspace Path: /workspaces/{workspace_id}/members Method: GET Response status codes: - 200: OK - 400: Bad Request - 401: Authentication Error - 403: Authentication Error - 404: Example response - 5XX: Unexpected Error Response: application/json
- Parameters:
workspace_id – str = None The workspace identifier. Default: workspace Id from the client.
:returns ApiResponse
- list() ApiResponse
Retrieve the list of workspaces the user belongs to
Reference: https://xata.io/docs/api-reference/workspaces#get-list-of-workspaces Path: /workspaces Method: GET Response status codes: - 200: OK - 400: Bad Request - 401: Authentication Error - 404: Example response - 5XX: Unexpected Error Response: application/json
:returns ApiResponse
- remove_member(user_id: str, workspace_id: str | None = None) ApiResponse
Remove the member from the workspace
Reference: https://xata.io/docs/api-reference/workspaces/workspace_id/members/user_id#remove-a-member-from-the-workspace Path: /workspaces/{workspace_id}/members/{user_id} Method: DELETE Response status codes: - 204: No Content - 400: Bad Request - 401: Authentication Error - 403: Authentication Error - 404: Example response - 5XX: Unexpected Error
- Parameters:
user_id – str UserID
workspace_id – str = None The workspace identifier. Default: workspace Id from the client.
:returns ApiResponse
- update(payload: dict, workspace_id: str | None = None) ApiResponse
Update workspace info
Reference: https://xata.io/docs/api-reference/workspaces/workspace_id#update-an-existing-workspace Path: /workspaces/{workspace_id} Method: PUT Response status codes: - 200: OK - 400: Bad Request - 401: Authentication Error - 403: Authentication Error - 404: Example response - 5XX: Unexpected Error Response: application/json
- Parameters:
payload – dict content
workspace_id – str = None The workspace identifier. Default: workspace Id from the client.
:returns ApiResponse
- update_member(user_id: str, payload: dict, workspace_id: str | None = None) ApiResponse
Update a workspace member role. Workspaces must always have at least one owner, so this operation will fail if trying to remove owner role from the last owner in the workspace.
Reference: https://xata.io/docs/api-reference/workspaces/workspace_id/members/user_id#update-workspace-member-role Path: /workspaces/{workspace_id}/members/{user_id} Method: PUT Response status codes: - 204: No Content - 400: Bad Request - 401: Authentication Error - 403: Authentication Error - 404: Example response - 5XX: Unexpected Error
- Parameters:
user_id – str UserID
payload – dict content
workspace_id – str = None The workspace identifier. Default: workspace Id from the client.
:returns ApiResponse
- class xata.api.invites.Invites(client)
- accept(invite_key: str, workspace_id: str | None = None) ApiResponse
Accept the invitation to join a workspace. If the operation succeeds the user will be a member of the workspace
Reference: https://xata.io/docs/api-reference/workspaces/workspace_id/invites/invite_key/accept#accept-the-invitation-to-join-a-workspace Path: /workspaces/{workspace_id}/invites/{invite_key}/accept Method: POST Response status codes: - 204: OK - 400: Bad Request - 401: Authentication Error - 403: Authentication Error - 404: Example response - 5XX: Unexpected Error
- Parameters:
invite_key – str Invite Key (secret) for the invited user
workspace_id – str = None The workspace identifier. Default: workspace Id from the client.
:returns ApiResponse
- cancel(invite_id: str, workspace_id: str | None = None) ApiResponse
This operation provides a way to cancel invites by deleting them. Already accepted invites cannot be deleted.
Reference: https://xata.io/docs/api-reference/workspaces/workspace_id/invites/invite_id#deletes-an-invite Path: /workspaces/{workspace_id}/invites/{invite_id} Method: DELETE Response status codes: - 204: No Content - 400: Bad Request - 401: Authentication Error - 403: Authentication Error - 404: Example response - 5XX: Unexpected Error
- Parameters:
invite_id – str Invite identifier
workspace_id – str = None The workspace identifier. Default: workspace Id from the client.
:returns ApiResponse
- new(payload: dict, workspace_id: str | None = None) ApiResponse
Invite some user to join the workspace with the given role
Reference: https://xata.io/docs/api-reference/workspaces/workspace_id/invites#invite-a-user-to-join-the-workspace Path: /workspaces/{workspace_id}/invites Method: POST Response status codes: - 201: Created - 400: Bad Request - 401: Authentication Error - 403: Authentication Error - 404: Example response - 409: Example response - 5XX: Unexpected Error Response: application/json
- Parameters:
payload – dict content
workspace_id – str = None The workspace identifier. Default: workspace Id from the client.
:returns ApiResponse
- resend(invite_id: str, workspace_id: str | None = None) ApiResponse
This operation provides a way to resend an Invite notification. Invite notifications can only be sent for Invites not yet accepted.
Reference: https://xata.io/docs/api-reference/workspaces/workspace_id/invites/invite_id/resend#resend-invite-notification Path: /workspaces/{workspace_id}/invites/{invite_id}/resend Method: POST Response status codes: - 204: OK - 400: Bad Request - 401: Authentication Error - 403: Authentication Error - 404: Example response - 5XX: Unexpected Error
- Parameters:
invite_id – str Invite identifier
workspace_id – str = None The workspace identifier. Default: workspace Id from the client.
:returns ApiResponse
- update(invite_id: str, payload: dict, workspace_id: str | None = None) ApiResponse
This operation provides a way to update an existing invite. Updates are performed in-place; they do not change the invite link, the expiry time, nor do they re-notify the recipient of the invite.
Reference: https://xata.io/docs/api-reference/workspaces/workspace_id/invites/invite_id#updates-an-existing-invite Path: /workspaces/{workspace_id}/invites/{invite_id} Method: PATCH Response status codes: - 200: Updated successfully. - 400: Bad Request - 401: Authentication Error - 403: Authentication Error - 404: Example response - 422: Example response - 5XX: Unexpected Error Response: application/json
- Parameters:
invite_id – str Invite identifier
payload – dict content
workspace_id – str = None The workspace identifier. Default: workspace Id from the client.
:returns ApiResponse
Helpers
- class xata.helpers.BulkProcessor(client: XataClient, thread_pool_size: int = 4, batch_size: int = 25, flush_interval: int = 5, processing_timeout: float = 0.025, throw_exception: bool = False)
Additional abstraction for bulk requests that process’ requests in parallel :stability beta
- class Records(batch_size: int, flush_interval: int, logger)
Thread safe storage for records to persist by the bulk processor
- length(table_name: str) int
Get record count of a table
- Parameters:
table_name – str
- next_batch() dict
Get the next batch of records to persist
:returns dict
- put(table_name: str, records: list[dict])
- Parameters:
table_name – str
records – list[dict]
- size() int
Get total size of stored records
- flush_queue()
Flush all records from the queue.
- get_failed_batches() list[dict]
Get the batched records that could not be processed with the error :returns list[dict]
- get_stats()
Get processing statistics
:returns dict
- process(id: int)
Process the records
- put_record(table_name: str, record: dict)
Put a record to the processing queue
- Parameters:
table_name – str
record – dict
- put_records(table_name: str, records: list[dict])
Put multtiple records to the processing queue
- Parameters:
table_name – str
records – list[dict]
- class xata.helpers.Transaction(client: XataClient)
Additional abstraction for bulk requests that process’ requests in parallel :stability beta
- delete(table: str, record_id: str, columns: list[str] = [], fail_if_missing: bool = False) None
A delete is used to remove records. Delete can operate on records from the same transaction, and will not cancel a transaction if no record is found. https://xata.io/docs/api-reference/db/db_branch_name/transaction#execute-a-transaction-on-a-branch
- Parameters:
table – str
record_id – str
columns – list of columns to retrieve
fail_if_missing – bool, Default: False
:raises Exception if limit of 1000 operations is exceeded
- get(table: str, record_id: str, columns: list[str] = []) None
A get is used to retrieve a record by id. A get operation can retrieve records created in the same transaction but will not cancel a transaction if no record is found.
- Parameters:
table – str
record_id – str
columns – list of columns to retrieve
:raises Exception if limit of 1000 operations is exceeded
- insert(table: str, record: dict, create_only: bool = False) None
Inserts can be used to insert records across any number of tables in your database. As with the insert endpoints, you can explicitly set an ID, or omit it and have Xata auto-generate one for you. Either way, on a successful transaction, Xata will return the ID to you.
- Parameters:
table – str
record – dict
create_only – bool By default, if a record exists with the same explicit ID, Xata will overwrite the record. You can adjust this behavior by setting create_only to true for the operation. Default: False
:raises Exception if limit of 1000 operations is exceeded
- run(branch_name: str | None = None, retry: bool = True, flush_on_error: bool = False) dict
Commit the transactions. Flushes the operations queue if no error happened. In case of too many connections, hitting rate limits, two extra attempts are taken with an incremental back off.
- Parameters:
branch_name – str Override the branch name from the client init
retry – bool Retry rate limit errors, Default: True
flush_on_error – bool Flush the operations if an error happened, Default: False
:returns dict
- size() int
Get amount of operations in queue :returns int
- update(table: str, record_id: str, fields: dict, upsert: bool = False) None
Updates can be used to update records in any number of tables in your database. The update operation requires an ID parameter explicitly defined. The operation will only replace the fields explicitly specified in your operation. The update operation also supports the upsert flag. Off by default, but if set to true, the update operation will insert the record if no record is found with the provided ID.
- Parameters:
table – str
record_id – str
fields – dict
upsert – bool Default: False
:raises Exception if limit of 1000 operations is exceeded
Errors
- class xata.errors.XataServerError(status_code, message='n/a')