Query database using SQL

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

This endpoint performs the SQL query across the entire database branch. Set your SQL query in the parameter query.

Expected parameters

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

SQL Query

POST

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

Run an SQL query across the database branch.

Request Body Type Definition

/**
 * @example {"statement":"select * from users;"}
 */
type SqlQuery = {
    /**
     * The SQL statement.
     *
     * @minLength 1
     */
    statement: string;
    /**
     * The query parameter list.
     */
    params?: any[] | null;
    /**
     * The consistency level for this request.
     *
     * @default strong
     */
    consistency?: "strong" | "eventual";
};

Responses

type SqlQuery = {
    records?: SQLRecord[];
    /**
     * Name of the column and its PostgreSQL type
     */
    columns?: Record<string, any>;
    /**
     * Number of selected columns
     */
    total?: number;
    warning?: string;
};
 
/**
 * Xata Table SQL Record
 */
type SQLRecord = {
    [key: string]: any;
};
 
/**
 * Xata Table Record Metadata
 */
type Record = RecordMeta & {
    [key: string]: any;
};
 
/**
 * 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;

type SqlQuery = {
    records?: SQLRecord[];
    /**
     * Name of the column and its PostgreSQL type
     */
    columns?: Record<string, any>;
    /**
     * Number of selected columns
     */
    total?: number;
    warning?: string;
};
 
/**
 * Xata Table SQL Record
 */
type SQLRecord = {
    [key: string]: any;
};
 
/**
 * Xata Table Record Metadata
 */
type Record = RecordMeta & {
    [key: string]: any;
};
 
/**
 * 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;

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

{
    "message": "invalid API key"
}

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

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

type SqlQuery = void;

type SqlQuery = void;