Xata

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_nameThe DBBranchName matches the pattern `{db_name}:{branch_name}`. path✅string
table_nameThe Table namepath✅string

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
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;
Status CodeDescriptionExample Response/Type Definition
200OK
type VectorSearchTable = {
    records: Record[];
    warning?: string;
};

/**
 * 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;
400Bad Request
type VectorSearchTable = {
    id?: string;
    message: string;
};
401Authentication Error
{
  "message": "invalid API key"
}
404Example response
type VectorSearchTable = {
    id?: string;
    message: string;
};
5XXUnexpected Error