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

NameDescriptionInRequiredSchema
db_branch_name

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

pathstring

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";
    /**
     * The response type.
     *
     * @default json
     */
    responseType?: "json" | "array";
};

Responses

type SqlQuery = {
    records?: SQLRecord[];
    rows?: any[][];
    /**
     * Name of the column and its PostgreSQL type
     */
    columns?: {
        name?: string;
        type?: string;
    }[];
    /**
     * Number of selected columns
     */
    total?: number;
    warning?: string;
};
 
/**
 * Xata Table SQL Record
 */
type SQLRecord = {
    [key: string]: any;
};