Skip to content
rachel/workerd
File

Blob: src/cloudflare/internal/vectorize.d.ts

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