1import type * as runtime from "@cloudflare/workers-types";
2import * as Effect from "effect/Effect";
3import * as Binding from "../../Binding.ts";
4import type { Index } from "./VectorizeIndex.ts";
5
6/**
7 * Bind a {@link Index} to a Worker and obtain the Effect-native Vectorize
8 * client (`describe`, `query`, `upsert`, …).
9 *
10 * `SearchIndex` is a single identifier that is simultaneously the binding's
11 * Context tag, its type, and the callable —
12 * `yield* Cloudflare.Vectorize.SearchIndex(index)`.
13 *
14 * **Example:** Querying an index inside a Worker
15 * ```typescript
16 * const vec = yield* Cloudflare.Vectorize.SearchIndex(MyIndex);
17 * const matches = yield* vec.query([0.1, 0.2, 0.3], { topK: 5 });
18 * ```
19 *
20 * @binding
21 * @product Vectorize
22 * @category AI
23 */
24export interface SearchIndex extends Binding.Service<
25 SearchIndex,
26 "Cloudflare.Vectorize.SearchIndex",
27 (index: Index) => Effect.Effect<SearchIndexClient>
28> {}
29
30export const SearchIndex = Binding.Service<SearchIndex>(
31 "Cloudflare.Vectorize.SearchIndex",
32);
33
34export interface SearchIndexClient {
35 /**
36 * An Effect that resolves to the raw underlying Cloudflare Vectorize
37 * binding. Use this for direct access not covered by the helpers below.
38 */
39 raw: Effect.Effect<runtime.Vectorize>;
40 /** Get information about the bound index (dimensions, vector count). */
41 describe: () => Effect.Effect<runtime.VectorizeIndexInfo>;
42 /** Find the nearest neighbors of `vector`. */
43 query: (
44 vector: runtime.VectorFloatArray | number[],
45 options?: runtime.VectorizeQueryOptions,
46 ) => Effect.Effect<runtime.VectorizeMatches>;
47 /** Find the nearest neighbors of an existing vector by its id. */
48 queryById: (
49 vectorId: string,
50 options?: runtime.VectorizeQueryOptions,
51 ) => Effect.Effect<runtime.VectorizeMatches>;
52 /** Insert vectors. Throws if any provided id already exists. */
53 insert: (
54 vectors: runtime.VectorizeVector[],
55 ) => Effect.Effect<runtime.VectorizeAsyncMutation>;
56 /** Upsert vectors, replacing any existing vectors with matching ids. */
57 upsert: (
58 vectors: runtime.VectorizeVector[],
59 ) => Effect.Effect<runtime.VectorizeAsyncMutation>;
60 /** Delete vectors by id. */
61 deleteByIds: (ids: string[]) => Effect.Effect<runtime.VectorizeAsyncMutation>;
62 /** Fetch vectors by id. */
63 getByIds: (ids: string[]) => Effect.Effect<runtime.VectorizeVector[]>;
64}