Search Database

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

This endpoint performs full text search across an entire database branch. You can filter down to particular table by using the tables parameter. The tables parameter accepts a mixed array of strings and objects. Using a string (the table name) selects the full table. Using an object allows one to specify a filter as well. The supported filters are the same as documented for the query endpoint 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
Expected Parameters
NameDescriptionInRequiredSchema
db_branch_nameThe DBBranchName matches the pattern `{db_name}:{branch_name}`. pathstring
POST  https://{your-workspace-slug}.xata.sh/db/{db_branch_name}/search/

Run a free text search operation across the database branch.

Request Body Example
{
  "tables": [
    "users",
    {
      "table": "articles",
      "filter": {
        "author": "Abigail"
      }
    }
  ],
  "query": "after a long day"
}
Request Body Type Definition
/**
 * @example {"tables":["users",{"table":"articles","filter":{"author":"Abigail"}}],"query":"after a long day"}
 */
type SearchBranch = {
    /*
     * An array with the tables in which to search. By default, all tables are included. Optionally, filters can be included that apply to each table.
     */
    tables?: (string | {
        /*
         * The name of the table.
         */
        table: string;
        filter?: FilterExpression;
        boosters?: BoosterExpression[];
    })[];
    /*
     * The query string.
     *
     * @minLength 1
     */
    query: string;
    fuzziness?: FuzzinessExpression;
    highlight?: HighlightExpression;
};

/**
 * @minProperties 1
 */
type FilterExpression = {
    $exists?: string;
    $existsNot?: string;
    $any?: FilterList;
    $all?: FilterList;
    $none?: FilterList;
    $not?: FilterList;
} & {
    [key: string]: FilterColumn;
};

/**
 * Booster Expression
 */
type BoosterExpression = {
    valueBooster?: ValueBooster;
} | {
    numericBooster?: NumericBooster;
} | {
    dateBooster?: DateBooster;
};

/**
 * Maximum [Levenshtein distance](https://en.wikipedia.org/wiki/Levenshtein_distance) for the search terms. The Levenshtein
 * distance is the number of one charcter changes needed to make two strings equal. The default is 1, meaning that single
 * character typos per word are tollerated by search. You can set it to 0 to remove the typo tollerance or set it to 2 
 * to allow two typos in a word.
 * 
 * @default 1
 * @maximum 2
 * @minimum 0
 */
type FuzzinessExpression = number;

type HighlightExpression = {
    /*
     * Set to `false` to disable highlighting. By default it is `true`.
     */
    enabled?: boolean;
    /*
     * Set to `false` to disable HTML encoding in highlight snippets. By default it is `true`.
     */
    encodeHTML?: boolean;
};

type FilterList = FilterExpression | FilterExpression[];

type FilterColumn = FilterColumnIncludes | FilterPredicate | FilterList;

/**
 * Boost records with a particular value for a column.
 */
type ValueBooster = {
    /*
     * The column in which to look for the value.
     */
    column: string;
    /*
     * The exact value to boost.
     */
    value: string | number | boolean;
    /*
     * The factor with which to multiply the score of the record.
     */
    factor: number;
};

/**
 * Boost records based on the value of a numeric column.
 */
type NumericBooster = {
    /*
     * The column in which to look for the value.
     */
    column: string;
    /*
     * The factor with which to multiply the value of the column before adding it to the item score.
     */
    factor: number;
};

/**
 * Boost records based on the value of a datetime column. It is configured via "origin", "scale", and "decay". The further away from the "origin", 
 * the more the score is decayed. The decay function uses an exponential function. For example if origin is "now", and scale is 10 days and decay is 0.5, it
 * should be interpreted as: a record with a date 10 days before/after origin will score 2 times less than a record with the date at origin.
 */
type DateBooster = {
    /*
     * The column in which to look for the value.
     */
    column: string;
    /*
     * The datetime (formatted as RFC3339) from where to apply the score decay function. The maximum boost will be applied for records with values at this time.
     * If it is not specified, the current date and time is used.
     */
    origin?: string;
    /*
     * The duration at which distance from origin the score is decayed with factor, using an exponential function. It is fromatted as number + units, for example: `5d`, `20m`, `10s`.
     *
     * @pattern ^(\d+)(d|h|m|s|ms)$
     */
    scale: string;
    /*
     * The decay factor to expect at "scale" distance from the "origin".
     */
    decay: 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;
Possible Responses
Status CodeDescriptionExample Response/Type Definition
200OK
type SearchBranch = {
    records: Record[];
};

/**
 * 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 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[];
    };
};

/**
 * @pattern [a-zA-Z0-9_-~:]+
 */
type RecordID = string;
400Bad Request
type SearchBranch = {
    id?: string;
    message: string;
};
401Authentication Error
{
  "message": "invalid API key"
}
404Example response
type SearchBranch = {
    id?: string;
    message: string;
};
5XXUnexpected Error