Skip to content
rachel/workerd
File

Blob: types/defines/vectorize.d.ts

typescript286 lines
1// Copyright (c) 2022-2023 Cloudflare, Inc.
2// Licensed under the Apache 2.0 license found in the LICENSE file or at:
3//     https://opensource.org/licenses/Apache-2.0
4 
5/**
6 * Data types supported for holding vector metadata.
7 */
8type VectorizeVectorMetadataValue = string | number | boolean | string[];
9/**
10 * Additional information to associate with a vector.
11 */
12type VectorizeVectorMetadata =
13  | VectorizeVectorMetadataValue
14  | Record<string, VectorizeVectorMetadataValue>;
15 
16type VectorFloatArray = Float32Array | Float64Array;
17 
18interface VectorizeError {
19  code?: number;
20  error: string;
21}
22 
23/**
24 * Comparison logic/operation to use for metadata filtering.
25 *
26 * This list is expected to grow as support for more operations are released.
27 */
28type VectorizeVectorMetadataFilterOp =
29  | '$eq'
30  | '$ne'
31  | '$lt'
32  | '$lte'
33  | '$gt'
34  | '$gte';
35type VectorizeVectorMetadataFilterCollectionOp = '$in' | '$nin';
36 
37/**
38 * Filter criteria for vector metadata used to limit the retrieved query result set.
39 */
40type VectorizeVectorMetadataFilter = {
41  [field: string]:
42    | Exclude<VectorizeVectorMetadataValue, string[]>
43    | null
44    | {
45        [Op in VectorizeVectorMetadataFilterOp]?: Exclude<
46          VectorizeVectorMetadataValue,
47          string[]
48        > | null;
49      }
50    | {
51        [Op in VectorizeVectorMetadataFilterCollectionOp]?: Exclude<
52          VectorizeVectorMetadataValue,
53          string[]
54        >[];
55      };
56};
57 
58/**
59 * Supported distance metrics for an index.
60 * Distance metrics determine how other "similar" vectors are determined.
61 */
62type VectorizeDistanceMetric = "euclidean" | "cosine" | "dot-product";
63 
64/**
65 * Metadata return levels for a Vectorize query.
66 *
67 * Default to "none".
68 *
69 * @property all      Full metadata for the vector return set, including all fields (including those un-indexed) without truncation. This is a more expensive retrieval, as it requires additional fetching & reading of un-indexed data.
70 * @property indexed  Return all metadata fields configured for indexing in the vector return set. This level of retrieval is "free" in that no additional overhead is incurred returning this data. However, note that indexed metadata is subject to truncation (especially for larger strings).
71 * @property none     No indexed metadata will be returned.
72 */
73type VectorizeMetadataRetrievalLevel = "all" | "indexed" | "none";
74 
75interface VectorizeQueryOptions {
76  topK?: number;
77  namespace?: string;
78  returnValues?: boolean;
79  returnMetadata?: boolean | VectorizeMetadataRetrievalLevel;
80  filter?: VectorizeVectorMetadataFilter;
81}
82 
83/**
84 * Information about the configuration of an index.
85 */
86type VectorizeIndexConfig =
87  | {
88      dimensions: number;
89      metric: VectorizeDistanceMetric;
90    }
91  | {
92      preset: string; // keep this generic, as we'll be adding more presets in the future and this is only in a read capacity
93    };
94 
95/**
96 * Metadata about an existing index.
97 *
98 * This type is exclusively for the Vectorize **beta** and will be deprecated once Vectorize RC is released.
99 * See {@link VectorizeIndexInfo} for its post-beta equivalent.
100 */
101interface VectorizeIndexDetails {
102  /** The unique ID of the index */
103  readonly id: string;
104  /** The name of the index. */
105  name: string;
106  /** (optional) A human readable description for the index. */
107  description?: string;
108  /** The index configuration, including the dimension size and distance metric. */
109  config: VectorizeIndexConfig;
110  /** The number of records containing vectors within the index. */
111  vectorsCount: number;
112}
113 
114/**
115 * Metadata about an existing index.
116 */
117interface VectorizeIndexInfo {
118  /** The number of records containing vectors within the index. */
119  vectorCount: number;
120  /** Number of dimensions the index has been configured for. */
121  dimensions: number;
122  /** ISO 8601 datetime of the last processed mutation on in the index. All changes before this mutation will be reflected in the index state. */
123  processedUpToDatetime: number;
124  /** UUIDv4 of the last mutation processed by the index. All changes before this mutation will be reflected in the index state. */
125  processedUpToMutation: number;
126}
127 
128/**
129 * Represents a single vector value set along with its associated metadata.
130 */
131interface VectorizeVector {
132  /** The ID for the vector. This can be user-defined, and must be unique. It should uniquely identify the object, and is best set based on the ID of what the vector represents. */
133  id: string;
134  /** The vector values */
135  values: VectorFloatArray | number[];
136  /** The namespace this vector belongs to. */
137  namespace?: string;
138  /** Metadata associated with the vector. Includes the values of other fields and potentially additional details. */
139  metadata?: Record<string, VectorizeVectorMetadata>;
140}
141 
142/**
143 * Represents a matched vector for a query along with its score and (if specified) the matching vector information.
144 */
145type VectorizeMatch = Pick<Partial<VectorizeVector>, "values"> &
146  Omit<VectorizeVector, "values"> & {
147    /** The score or rank for similarity, when returned as a result */
148    score: number;
149  };
150 
151/**
152 * A set of matching {@link VectorizeMatch} for a particular query.
153 */
154interface VectorizeMatches {
155  matches: VectorizeMatch[];
156  count: number;
157}
158 
159/**
160 * Results of an operation that performed a mutation on a set of vectors.
161 * Here, `ids` is a list of vectors that were successfully processed.
162 *
163 * This type is exclusively for the Vectorize **beta** and will be deprecated once Vectorize RC is released.
164 * See {@link VectorizeAsyncMutation} for its post-beta equivalent.
165 */
166interface VectorizeVectorMutation {
167  /* List of ids of vectors that were successfully processed. */
168  ids: string[];
169  /* Total count of the number of processed vectors. */
170  count: number;
171}
172 
173/**
174 * Result type indicating a mutation on the Vectorize Index.
175 * Actual mutations are processed async where the `mutationId` is the unique identifier for the operation.
176 */
177interface VectorizeAsyncMutation {
178  /** The unique identifier for the async mutation operation containing the changeset. */
179  mutationId: string;
180}
181 
182/**
183 * A Vectorize Vector Search Index for querying vectors/embeddings.
184 *
185 * This type is exclusively for the Vectorize **beta** and will be deprecated once Vectorize RC is released.
186 * See {@link Vectorize} for its new implementation.
187 */
188declare abstract class VectorizeIndex {
189  /**
190   * Get information about the currently bound index.
191   * @returns A promise that resolves with information about the current index.
192   */
193  public describe(): Promise<VectorizeIndexDetails>;
194  /**
195   * Use the provided vector to perform a similarity search across the index.
196   * @param vector Input vector that will be used to drive the similarity search.
197   * @param options Configuration options to massage the returned data.
198   * @returns A promise that resolves with matched and scored vectors.
199   */
200  public query(
201    vector: VectorFloatArray | number[],
202    options?: VectorizeQueryOptions
203  ): Promise<VectorizeMatches>;
204  /**
205   * Insert a list of vectors into the index dataset. If a provided id exists, an error will be thrown.
206   * @param vectors List of vectors that will be inserted.
207   * @returns A promise that resolves with the ids & count of records that were successfully processed.
208   */
209  public insert(vectors: VectorizeVector[]): Promise<VectorizeVectorMutation>;
210  /**
211   * Upsert a list of vectors into the index dataset. If a provided id exists, it will be replaced with the new values.
212   * @param vectors List of vectors that will be upserted.
213   * @returns A promise that resolves with the ids & count of records that were successfully processed.
214   */
215  public upsert(vectors: VectorizeVector[]): Promise<VectorizeVectorMutation>;
216  /**
217   * Delete a list of vectors with a matching id.
218   * @param ids List of vector ids that should be deleted.
219   * @returns A promise that resolves with the ids & count of records that were successfully processed (and thus deleted).
220   */
221  public deleteByIds(ids: string[]): Promise<VectorizeVectorMutation>;
222  /**
223   * Get a list of vectors with a matching id.
224   * @param ids List of vector ids that should be returned.
225   * @returns A promise that resolves with the raw unscored vectors matching the id set.
226   */
227  public getByIds(ids: string[]): Promise<VectorizeVector[]>;
228}
229 
230/**
231 * A Vectorize Vector Search Index for querying vectors/embeddings.
232 *
233 * Mutations in this version are async, returning a mutation id.
234 */
235declare abstract class Vectorize {
236  /**
237   * Get information about the currently bound index.
238   * @returns A promise that resolves with information about the current index.
239   */
240  public describe(): Promise<VectorizeIndexInfo>;
241  /**
242   * Use the provided vector to perform a similarity search across the index.
243   * @param vector Input vector that will be used to drive the similarity search.
244   * @param options Configuration options to massage the returned data.
245   * @returns A promise that resolves with matched and scored vectors.
246   */
247  public query(
248    vector: VectorFloatArray | number[],
249    options?: VectorizeQueryOptions
250  ): Promise<VectorizeMatches>;
251  /**
252   * Use the provided vector-id to perform a similarity search across the index.
253   * @param vectorId Id for a vector in the index against which the index should be queried.
254   * @param options Configuration options to massage the returned data.
255   * @returns A promise that resolves with matched and scored vectors.
256   */
257  public queryById(
258    vectorId: string,
259    options?: VectorizeQueryOptions
260  ): Promise<VectorizeMatches>;
261  /**
262   * Insert a list of vectors into the index dataset. If a provided id exists, an error will be thrown.
263   * @param vectors List of vectors that will be inserted.
264   * @returns A promise that resolves with a unique identifier of a mutation containing the insert changeset.
265   */
266  public insert(vectors: VectorizeVector[]): Promise<VectorizeAsyncMutation>;
267  /**
268   * Upsert a list of vectors into the index dataset. If a provided id exists, it will be replaced with the new values.
269   * @param vectors List of vectors that will be upserted.
270   * @returns A promise that resolves with a unique identifier of a mutation containing the upsert changeset.
271   */
272  public upsert(vectors: VectorizeVector[]): Promise<VectorizeAsyncMutation>;
273  /**
274   * Delete a list of vectors with a matching id.
275   * @param ids List of vector ids that should be deleted.
276   * @returns A promise that resolves with a unique identifier of a mutation containing the delete changeset.
277   */
278  public deleteByIds(ids: string[]): Promise<VectorizeAsyncMutation>;
279  /**
280   * Get a list of vectors with a matching id.
281   * @param ids List of vector ids that should be returned.
282   * @returns A promise that resolves with the raw unscored vectors matching the id set.
283   */
284  public getByIds(ids: string[]): Promise<VectorizeVector[]>;
285}