Query Table Data

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

This endpoint serves data from a given table, inside a specific database's branch. For a tutorial on using the Records API, see the Record API documentation.

Expected parameters

NameDescriptionInRequiredSchema
db_branch_name

The DBBranchName matches the pattern {db_name}:{branch_name}.

pathstring
table_name

The Table name

pathstring

Query Table

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

Failed to compile MDX

Request Body Type Definition

type QueryTable = {
    filter?: FilterExpression;
    sort?: SortExpression;
    page?: PageConfig;
    columns?: QueryColumnsProjection;
    /**
     * The consistency level for this request.
     *
     * @default strong
     */
    consistency?: "strong" | "eventual";
};
 
/**
 * @minProperties 1
 */
type FilterExpression = {
    $exists?: string;
    $existsNot?: string;
    $any?: FilterList;
    $all?: FilterList;
    $none?: FilterList;
    $not?: FilterList;
} & {
    [key: string]: FilterColumn;
};
 
type SortExpression = string[] | {
    [key: string]: SortOrder;
} | {
    [key: string]: SortOrder;
}[];
 
/**
 * Pagination settings.
 */
type PageConfig = {
    /**
     * Query the next page that follow the cursor.
     */
    after?: string;
    /**
     * Query the previous page before the cursor.
     */
    before?: string;
    /**
     * Query the first page from the cursor.
     */
    start?: string;
    /**
     * Query the last page from the cursor.
     */
    end?: string;
    /**
     * Set page size. If the size is missing it is read from the cursor. If no cursor is given Xata will choose the default page size.
     *
     * @default 20
     */
    size?: number;
    /**
     * Use offset to skip entries. To skip pages set offset to a multiple of size.
     *
     * @default 0
     */
    offset?: number;
};
 
type QueryColumnsProjection = (string | ProjectionConfig)[];
 
type FilterList = FilterExpression | FilterExpression[];
 
type FilterColumn = FilterColumnIncludes | FilterPredicate | FilterList;
 
type SortOrder = "asc" | "desc" | "random";
 
/**
 * A structured projection that allows for some configuration.
 */
type ProjectionConfig = {
    /**
     * The name of the column to project or a reverse link specification, see [API Guide](https://xata.io/docs/concepts/data-model#links-and-relations).
     */
    name?: string;
    columns?: QueryColumnsProjection;
    /**
     * An alias for the projected field, this is how it will be returned in the response.
     */
    as?: string;
    sort?: SortExpression;
    /**
     * @default 20
     */
    limit?: number;
    /**
     * @default 0
     */
    offset?: number;
};
 
/**
 * @maxProperties 1
 * @minProperties 1
 */
type FilterColumnIncludes = {
    $includes?: FilterPredicate;
    $includesAny?: FilterPredicate;
    $includesAll?: FilterPredicate;
    $includesNone?: FilterPredicate;
};
 
type FilterPredicate = FilterValue | FilterPredicate[] | FilterPredicateOp | FilterPredicateRangeOp;
 
type FilterValue = number | string | boolean;
 
/**
 * @maxProperties 1
 * @minProperties 1
 */
type FilterPredicateOp = {
    $any?: FilterPredicate[];
    $all?: FilterPredicate[];
    $none?: FilterPredicate | FilterPredicate[];
    $not?: FilterPredicate | FilterPredicate[];
    $is?: FilterValue | FilterValue[];
    $isNot?: FilterValue | FilterValue[];
    $lt?: FilterRangeValue;
    $le?: FilterRangeValue;
    $gt?: FilterRangeValue;
    $ge?: FilterRangeValue;
    $contains?: string;
    $startsWith?: string;
    $endsWith?: string;
    $pattern?: string;
};
 
/**
 * @maxProperties 2
 * @minProperties 2
 */
type FilterPredicateRangeOp = {
    $lt?: FilterRangeValue;
    $le?: FilterRangeValue;
    $gt?: FilterRangeValue;
    $ge?: FilterRangeValue;
};
 
type FilterRangeValue = number | string;

Responses

type QueryTable = {
    records: Record[];
    meta: RecordsMetadata;
};
 
/**
 * Xata Table Record Metadata
 */
type Record = RecordMeta & {
    [key: string]: any;
};
 
/**
 * Records metadata
 */
type RecordsMetadata = {
    page: {
        /**
         * last record id
         */
        cursor: string;
        /**
         * true if more records can be fetched
         */
        more: boolean;
        /**
         * the number of records returned per page
         */
        size: number;
    };
};
 
/**
 * Xata Table Record Metadata
 */
type RecordMeta = {
    id: RecordID;
    xata: {
        /**
         * The record's version. Can be used for optimistic concurrency control.
         */
        version: number;
        /**
         * The time when the record was created.
         */
        createdAt?: string;
        /**
         * The time when the record was last updated.
         */
        updatedAt?: string;
        /**
         * The record's table name. APIs that return records from multiple tables will set this field accordingly.
         */
        table?: string;
        /**
         * Highlights of the record. This is used by the search APIs to indicate which fields and parts of the fields have matched the search.
         */
        highlight?: {
            [key: string]: string[] | {
                [key: string]: any;
            };
        };
        /**
         * The record's relevancy score. This is returned by the search APIs.
         */
        score?: number;
        /**
         * Encoding/Decoding errors
         */
        warnings?: string[];
    };
};
 
/**
 * @maxLength 255
 * @minLength 1
 * @pattern [a-zA-Z0-9_-~:]+
 */
type RecordID = string;