Vector similarity search

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

This endpoint can be used to perform vector-based similarity searches.

Expected parameters

NameDescriptionInRequiredSchema
db_branch_name

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

pathstring
table_name

The Table name

pathstring

Vector Similarity Search in a Table

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

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.

Request Body Type Definition

type VectorSearchTable = {
    /**
     * The vector to search for similarities. Must have the same dimension as
     * the vector column used.
     */
    queryVector: number[];
    /**
     * The vector column in which to search. It must be of type `vector`.
     */
    column: string;
    /**
     * The function used to measure the distance between two points. Can be one of:
     * `cosineSimilarity`, `l1`, `l2`. The default is `cosineSimilarity`.
     *
     * @default cosineSimilarity
     */
    similarityFunction?: string;
    /**
     * Number of results to return.
     *
     * @default 10
     * @maximum 100
     * @minimum 1
     */
    size?: number;
    filter?: FilterExpression;
};
 
/**
 * @minProperties 1
 */
type FilterExpression = {
    $exists?: string;
    $existsNot?: string;
    $any?: FilterList;
    $all?: FilterList;
    $none?: FilterList;
    $not?: FilterList;
} & {
    [key: string]: FilterColumn;
};
 
type FilterList = FilterExpression | FilterExpression[];
 
type FilterColumn = FilterColumnIncludes | FilterPredicate | FilterList;
 
/**
 * @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 VectorSearchTable = {
    records: Record[];
    warning?: string;
    /**
     * The total count of records matched. It will be accurately returned up to 10000 records.
     */
    totalCount: number;
};
 
/**
 * 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;