@upstash/vector 1.2.0 → 1.2.2

package/dist/{vector-FeePts30.d.ts → vector-7jBuY6ad.d.ts}

@@ -41,6 +41,12 @@ type RequesterConfig = {
      */
     cache?: CacheSetting;
 };
+type HttpClientConfig = {
+    headers?: Record<string, string>;
+    baseUrl: string;
+    retry?: RetryConfig;
+    signal?: AbortSignal | (() => AbortSignal);
+} & RequesterConfig;
 
 type Vector<TMetadata = Dict> = {
     id: string;
@@ -71,10 +77,20 @@ declare class Command<TResult> {
     exec(client: Requester): Promise<TResult>;
 }
 
+type IdsPayload = (number[] | string[]) | number | string;
+type ObjectPayload = {
+    ids: number[] | string[];
+} | {
+    prefix: string;
+} | {
+    filter: string;
+};
+type DeleteCommandPayload = IdsPayload | ObjectPayload;
+
 declare class DeleteCommand extends Command<{
     deleted: number;
 }> {
-    constructor(id: (number[] | string[]) | number | string, options?: {
+    constructor(payload: DeleteCommandPayload, options?: {
         namespace?: string;
     });
 }
@@ -238,6 +254,7 @@ type RangeCommandPayload = {
     includeVectors?: boolean;
     includeMetadata?: boolean;
     includeData?: boolean;
+    prefix?: string;
 };
 type RangeCommandOptions = {
     namespace?: string;
@@ -259,19 +276,34 @@ type ResetCommandOptions = {
 };
 
 type NamespaceTitle = string;
+type SimilarityFunction = "COSINE" | "EUCLIDEAN" | "DOT_PRODUCT";
 type NamespaceInfo = {
     vectorCount: number;
     pendingVectorCount: number;
 };
+type DenseIndexInfo = {
+    dimension: number;
+    similarityFunction: SimilarityFunction;
+    embeddingModel?: string;
+};
+type SparseIndexInfo = {
+    embeddingModel?: string;
+};
 type InfoResult = {
     vectorCount: number;
     pendingVectorCount: number;
     indexSize: number;
     dimension: number;
-    similarityFunction: "COSINE" | "EUCLIDEAN" | "DOT_PRODUCT";
+    similarityFunction: SimilarityFunction;
+    denseIndex?: DenseIndexInfo;
+    sparseIndex?: SparseIndexInfo;
     namespaces: Record<NamespaceTitle, NamespaceInfo>;
 };
 
+type ResumableQueryPayload = {
+    maxIdle: number;
+} & QueryCommandPayload;
+
 declare class Namespace<TIndexMetadata extends Dict = Dict> {
     protected client: Requester;
     protected namespace: string;
@@ -366,19 +398,21 @@ declare class Namespace<TIndexMetadata extends Dict = Dict> {
         updated: number;
     }>;
     /**
-     * It's used for retrieving specific items from the index namespace, optionally including
-     * their metadata and feature vectors.
+     * Fetches specific items from the index by their IDs or by an id prefix.
+     *
+     * Note: While using id prefix, the paginated `range` command is recommended to prevent timeouts on large result sets.
      *
      * @example
      * ```js
-     * const fetchIds = ['123', '456'];
-     * const fetchOptions = { includeMetadata: true, includeVectors: false };
-     * const fetchResults = await index.namespace("ns").fetch(fetchIds, fetchOptions);
-     * console.log(fetchResults); // Outputs the fetched items
+     * // Using ids
+     * await index.namespace("ns").fetch(["test-1", "test-2"], { includeMetadata: true });
+     *
+     * // Using id prefix
+     * await index.namespace("ns").fetch({ prefix: "test-" });
      * ```
      *
      * @param {...CommandArgs<typeof FetchCommand>} args - The arguments for the fetch command.
-     * @param {(number[]|string[])} args[0] - An array of IDs of the items to be fetched.
+     * @param {FetchPayload} args[0] - An array of IDs or the id prefix of the items to be fetched.
      * @param {FetchCommandOptions} args[1] - Options for the fetch operation.
      * @param {boolean} [args[1].includeMetadata=false] - Optionally include metadata of the fetched items.
      * @param {boolean} [args[1].includeVectors=false] - Optionally include feature vectors of the fetched items.
@@ -386,7 +420,11 @@ declare class Namespace<TIndexMetadata extends Dict = Dict> {
      *
      * @returns {Promise<FetchReturnResponse<TMetadata>[]>} A promise that resolves with an array of fetched items or null if not found, after the command is executed.
      */
-    fetch: <TMetadata extends Dict = TIndexMetadata>(ids: number[] | string[], opts?: {
+    fetch: <TMetadata extends Dict = TIndexMetadata>(payload: (number[] | string[]) | ({
+        ids: number[] | string[];
+    } | {
+        prefix: string;
+    }), opts?: {
         includeMetadata?: boolean | undefined;
         includeVectors?: boolean | undefined;
         includeData?: boolean | undefined;
@@ -417,36 +455,83 @@ declare class Namespace<TIndexMetadata extends Dict = Dict> {
      */
     query: <TMetadata extends Dict = TIndexMetadata>(args: CommandArgs<typeof QueryCommand>) => Promise<QueryResult<TMetadata>[]>;
     /**
-     * Deletes a specific item or items from the index namespace by their ID(s).   *
+     * Initializes a resumable query operation on the vector database.
+     * This method allows for querying large result sets in multiple chunks or implementing pagination.
+     *
+     * @template TMetadata
+     * @param {ResumableQueryPayload} args - The arguments for the resumable query.
+     * @param {number} args.maxIdle - The maximum idle time in seconds before the query session expires.
+     * @param {number} args.topK - The number of top results to return in each fetch operation.
+     * @param {number[]} args.vector - The query vector used for similarity search.
+     * @param {boolean} [args.includeMetadata] - Whether to include metadata in the query results.
+     * @param {boolean} [args.includeVectors] - Whether to include vectors in the query results.
+     * @param {Object} [options] - Additional options for the query.
+     * @returns {Promise<ResumableQuery<TMetadata>>} A promise that resolves to a ResumableQuery object.
+     * @example
+     * const { result, fetchNext, stop } = await index.namespace("ns").resumableQuery({
+     *   maxIdle: 3600,
+     *   topK: 50,
+     *   vector: [0.1, 0.2, 0.3, ...],
+     *   includeMetadata: true,
+     *   includeVectors: true
+     * }, { namespace: 'my-namespace' });
+     *
+     * const firstBatch = await fetchNext(10);
+     * const secondBatch = await fetchNext(10);
+     * await stop(); // End the query session
+     */
+    resumableQuery: <TMetadata extends Dict = TIndexMetadata>(args: ResumableQueryPayload) => Promise<{
+        fetchNext: (additionalK: number) => Promise<QueryResult[]>;
+        stop: () => Promise<string>;
+        result: QueryResult<TMetadata>[];
+    }>;
+    /**
+     * Deletes items from the index namespace by id, by id prefix, or by filter.
      *
      * @example
      * ```js
-     * await index.namespace("ns").delete('test-id')
-     * // { deleted: 1 }
+     * // Delete by id
+     * await index.namespace("ns").delete("test-id");
+  
+     * // Delete by ids
+     * await index.namespace("ns").delete(["test-id1", "test-id2"]);
+  
+     * // Delete by id prefix
+     * await index.namespace("ns").delete({ prefix: "test-" });
+  
+     * // Delete by filter
+     * await index.namespace("ns").delete({ filter: "age >= 23" });
      * ```
      *
-     * @param id - List of ids or single id
-     * @returns Number of deleted vectors like `{ deleted: number }`. The number will be 0 if no vectors are deleted.
+     * @param args - A single id, an array of ids, a prefix, or a filter to delete items from the index.
+     * @returns Number of deleted vectors in the format `{ deleted: number }`.If no vectors are deleted, returns `{ deleted: 0 }`.
      */
     delete: (args: CommandArgs<typeof DeleteCommand>) => Promise<{
         deleted: number;
     }>;
     /**
-     * Retrieves a range of items from the index.
+     * Retrieves a paginated range of items from the index. Optionally filter results by an id prefix.
+     * Returns items in batches with a cursor for pagination.
      *
      * @example
      * ```js
-     * const rangeArgs = {
-     *   cursor: 0,
+     * const args = {
      *   limit: 10,
      *   includeVectors: true,
      *   includeMetadata: false
      * };
-     * const rangeResults = await index.namespace("ns").range(rangeArgs);
-     * console.log(rangeResults); // Outputs the result of the range operation
+     * await index.namespace("ns").range(args);
+     *
+     * // Use the cursor to get the next page of results
+     * const nextPage = await index.namespace("ns").range({
+     *   // You have to pass the arguments from the first call
+     *   ...args,
+     *   cursor: rangeResult.nextCursor,
+     * });
      * ```
      *
      * @param {CommandArgs<typeof RangeCommand>} args - The arguments for the range command.
+     * @param {string} [args.prefix] - The prefix of the items to be fetched.
      * @param {number|string} args.cursor - The starting point (cursor) for the range query.
      * @param {number} args.limit - The maximum number of items to return in this range.
      * @param {boolean} [args.includeVectors=false] - Optionally include the feature vectors of the items in the response.
@@ -469,10 +554,6 @@ declare class Namespace<TIndexMetadata extends Dict = Dict> {
     reset: () => Promise<string>;
 }
 
-type ResumableQueryPayload = {
-    maxIdle: number;
-} & QueryCommandPayload;
-
 type CommandArgs<TCommand extends new (_args: any) => any> = ConstructorParameters<TCommand>[0];
 /**
  * Serverless vector client for upstash vector db.
@@ -493,16 +574,25 @@ declare class Index<TIndexMetadata extends Dict = Dict> {
     constructor(client: Requester);
     namespace: (namespace: string) => Namespace<TIndexMetadata>;
     /**
-     * Deletes a specific item or items from the index by their ID(s).   *
+     * Deletes items from the index by id, by id prefix, or by filter.
      *
      * @example
      * ```js
-     * const result = await index.delete('test-id');
-     * // { deleted: 1 }
+     * // Delete by id
+     * await index.delete("test-id");
+  
+     * // Delete by ids
+     * await index.delete(["test-id1", "test-id2"]);
+  
+     * // Delete by id prefix
+     * await index.delete({ prefix: "test-" });
+  
+     * // Delete by filter
+     * await index.delete({ filter: "age >= 23" });
      * ```
      *
-     * @param id - List of ids or single id
-     * @returns Number of deleted vectors like `{ deleted: number }`. The number will be 0 if no vectors are deleted.
+     * @param args - A single id, an array of ids, a prefix, or a filter to delete items from the index.
+     * @returns Number of deleted vectors in the format `{ deleted: number }`.If no vectors are deleted, returns `{ deleted: 0 }`.
      */
     delete: (args: CommandArgs<typeof DeleteCommand>, options?: {
         namespace?: string;
@@ -687,27 +777,33 @@ declare class Index<TIndexMetadata extends Dict = Dict> {
         updated: number;
     }>;
     /**
-     * It's used for retrieving specific items from the index, optionally including
-     * their metadata and feature vectors.
+     * Fetches specific items from the index by their IDs or by an id prefix.
+     *
+     * Note: While using id prefix, the paginated `range` command is recommended to prevent timeouts on large result sets.
      *
      * @example
      * ```js
-     * const fetchIds = ['123', '456'];
-     * const fetchOptions = { includeMetadata: true, includeVectors: false };
-     * const fetchResults = await index.fetch(fetchIds, fetchOptions);
-     * console.log(fetchResults); // Outputs the fetched items
+     * // Using ids
+     * await index.fetch(["test-1", "test-2"], { includeMetadata: true });
+     *
+     * // Using id prefix
+     * await index.fetch({ prefix: "test-" });
      * ```
      *
      * @param {...CommandArgs<typeof FetchCommand>} args - The arguments for the fetch command.
-     * @param {(number[]|string[])} args - An array of IDs of the items to be fetched.
-     * @param {FetchCommandOptions} args - Options for the fetch operation.
-     * @param {boolean} [args.includeMetadata=false] - Optionally include metadata of the fetched items.
-     * @param {boolean} [args.includeVectors=false] - Optionally include feature vectors of the fetched items.
-     * @param {boolean} [args.metadataUpdateMode="OVERWRITE"] - Specifies whether to overwrite or patch the metadata values.
+     * @param {FetchPayload} args[0] - An array of IDs or the id prefix of the items to be fetched.
+     * @param {FetchCommandOptions} args[1] - Options for the fetch operation.
+     * @param {boolean} [args[1].includeMetadata=false] - Optionally include metadata of the fetched items.
+     * @param {boolean} [args[1].includeVectors=false] - Optionally include feature vectors of the fetched items.
+     * @param {string} [args[1].namespace = ""] - The namespace of the index to fetch items from.
      *
      * @returns {Promise<FetchReturnResponse<TMetadata>[]>} A promise that resolves with an array of fetched items or null if not found, after the command is executed.
      */
-    fetch: <TMetadata extends Dict = TIndexMetadata>(ids: number[] | string[], opts?: {
+    fetch: <TMetadata extends Dict = TIndexMetadata>(payload: (number[] | string[]) | ({
+        ids: number[] | string[];
+    } | {
+        prefix: string;
+    }), opts?: {
         includeMetadata?: boolean | undefined;
         includeVectors?: boolean | undefined;
         includeData?: boolean | undefined;
@@ -744,27 +840,28 @@ declare class Index<TIndexMetadata extends Dict = Dict> {
      */
     reset: (options?: ResetCommandOptions) => Promise<string>;
     /**
-     * Retrieves a range of items from the index.
+     * Retrieves a paginated range of items from the index. Optionally filter results by an id prefix.
+     * Returns items in batches with a cursor for pagination.
      *
      * @example
      * ```js
-     * const rangeArgs = {
-     *   cursor: 0,
+     * const args = {
      *   limit: 10,
      *   includeVectors: true,
      *   includeMetadata: false
      * };
-     * const rangeResults = await index.range(rangeArgs);
-     * console.log(rangeResults); // Outputs the result of the range operation
-     * ```
+     * await index.range(args);
      *
-     * You can also pass a namespace like:
-     *
-     * ```js
-     * const rangeResults = await index.range(rangeArgs, { namespace: "ns" });
+     * // Use the cursor to get the next page of results
+     * const nextPage = await index.range({
+     *   // You have to pass the arguments from the first call
+     *   ...args,
+     *   cursor: rangeResult.nextCursor,
+     * });
      * ```
      *
      * @param {CommandArgs<typeof RangeCommand>} args - The arguments for the range command.
+     * @param {string} [args.prefix] - The prefix of the items to be fetched.
      * @param {number|string} args.cursor - The starting point (cursor) for the range query.
      * @param {number} args.limit - The maximum number of items to return in this range.
      * @param {boolean} [args.includeVectors=false] - Optionally include the feature vectors of the items in the response.
@@ -814,4 +911,4 @@ declare class Index<TIndexMetadata extends Dict = Dict> {
     deleteNamespace: (namespace: string) => Promise<string>;
 }
 
-export { type Dict as D, FusionAlgorithm as F, Index as I, QueryMode as Q, type RequesterConfig as R, type SparseVector as S, type UpstashRequest as U, type Vector as V, WeightingStrategy as W, type Requester as a, type UpstashResponse as b, type RangeResult as c, type FetchResult as d, type QueryResult as e, type InfoResult as f };
+export { type Dict as D, FusionAlgorithm as F, type HttpClientConfig as H, Index as I, QueryMode as Q, type RequesterConfig as R, type SparseVector as S, type UpstashRequest as U, type Vector as V, WeightingStrategy as W, type Requester as a, type UpstashResponse as b, type RangeResult as c, type FetchResult as d, type QueryResult as e, type InfoResult as f };

package/package.json

@@ -1 +1 @@
-{ "name": "@upstash/vector", "version": "v1.2.0", "author": "Oguzhan Olguncu <oguzhan@upstash.com>", "repository": { "type": "git", "url": "https://github.com/upstash/vector-js" }, "exports": { ".": { "import": "./dist/nodejs.mjs", "require": "./dist/nodejs.js" }, "./cloudflare": { "import": "./dist/cloudflare.mjs", "require": "./dist/cloudflare.js" }, "./nodejs": { "import": "./dist/nodejs.mjs", "require": "./dist/nodejs.js" } }, "main": "./dist/nodejs.js", "module": "./dist/nodejs.mjs", "types": "./dist/nodejs.d.ts", "devDependencies": { "@commitlint/cli": "^18.6.0", "@commitlint/config-conventional": "^18.6.0", "@typescript-eslint/eslint-plugin": "^8.4.0", "bun-types": "latest", "eslint": "9.10.0", "eslint-plugin-unicorn": "^55.0.0", "husky": "^8.0.3", "prettier": "^3.3.3", "tsup": "latest", "typescript": "^5.0.0", "vitest": "^1.2.2" }, "bugs": { "url": "https://github.com/upstash/vector/issues" }, "description": "An HTTP/REST based Vector DB client built on top of Upstash REST API.", "files": [ "dist" ], "homepage": "https://upstash.com/vector", "keywords": [ "vector", "upstash", "db" ], "license": "MIT", "scripts": { "test": "bun test src --coverage --bail --coverageSkipTestFiles=[test-utils.ts] --timeout 20000", "fmt": "prettier --write .", "lint": "tsc && eslint \"src/**/*.{js,ts,tsx}\" --quiet --fix", "build": "tsup ", "prepare": "husky install" } }
+{ "name": "@upstash/vector", "version": "v1.2.2", "author": "Oguzhan Olguncu <oguzhan@upstash.com>", "repository": { "type": "git", "url": "https://github.com/upstash/vector-js" }, "exports": { ".": { "import": "./dist/nodejs.mjs", "require": "./dist/nodejs.js" }, "./cloudflare": { "import": "./dist/cloudflare.mjs", "require": "./dist/cloudflare.js" }, "./nodejs": { "import": "./dist/nodejs.mjs", "require": "./dist/nodejs.js" } }, "main": "./dist/nodejs.js", "module": "./dist/nodejs.mjs", "types": "./dist/nodejs.d.ts", "devDependencies": { "@commitlint/cli": "^18.6.0", "@commitlint/config-conventional": "^18.6.0", "@typescript-eslint/eslint-plugin": "^8.4.0", "bun-types": "latest", "eslint": "9.10.0", "eslint-plugin-unicorn": "^55.0.0", "husky": "^8.0.3", "prettier": "^3.3.3", "tsup": "latest", "typescript": "^5.0.0", "vitest": "^1.2.2" }, "bugs": { "url": "https://github.com/upstash/vector/issues" }, "description": "An HTTP/REST based Vector DB client built on top of Upstash REST API.", "files": [ "dist" ], "homepage": "https://upstash.com/vector", "keywords": [ "vector", "upstash", "db" ], "license": "MIT", "scripts": { "test": "bun test src --coverage --bail --coverageSkipTestFiles=[test-utils.ts] --timeout 20000", "fmt": "prettier --write .", "lint": "tsc && eslint \"src/**/*.{js,ts,tsx}\" --quiet --fix", "build": "tsup ", "prepare": "husky install" } }