@upstash/vector 1.2.0 → 1.2.1

package/dist/nodejs.js

@@ -131,18 +131,28 @@ var Command = class {
 
 // src/commands/client/delete/index.ts
 var DeleteCommand = class extends Command {
-  constructor(id, options) {
+  constructor(payload, options) {
     let endpoint = "delete";
     if (options?.namespace) {
       endpoint = `${endpoint}/${options.namespace}`;
     }
-    const finalArr = [];
-    if (Array.isArray(id)) {
-      finalArr.push(...id);
-    } else {
-      finalArr.push(id);
+    if (typeof payload === "string" || typeof payload === "number") {
+      super(
+        {
+          ids: [payload]
+        },
+        endpoint
+      );
+    } else if (Array.isArray(payload)) {
+      super(
+        {
+          ids: payload
+        },
+        endpoint
+      );
+    } else if (typeof payload === "object") {
+      super(payload, endpoint);
     }
-    super(finalArr, endpoint);
   }
 };
 
@@ -214,13 +224,19 @@ var isVectorPayload = (payload) => {
 
 // src/commands/client/fetch/index.ts
 var FetchCommand = class extends Command {
-  constructor([ids, opts]) {
+  constructor([payload, opts]) {
     let endpoint = "fetch";
     if (opts?.namespace) {
       endpoint = `${endpoint}/${opts.namespace}`;
       delete opts.namespace;
     }
-    super({ ids, ...opts }, endpoint);
+    if (Array.isArray(payload)) {
+      super({ ids: payload, ...opts }, endpoint);
+    } else if (typeof payload === "object") {
+      super({ ...payload, ...opts }, endpoint);
+    } else {
+      throw new Error("Invalid payload");
+    }
   }
 };
 
@@ -256,6 +272,67 @@ var InfoCommand = class extends Command {
   }
 };
 
+// src/commands/client/resumable-query/resume.ts
+var ResumeQueryCommand = class extends Command {
+  constructor(payload) {
+    super(payload, "resumable-query-next");
+  }
+};
+
+// src/commands/client/resumable-query/start.ts
+var StartResumableQueryCommand = class extends Command {
+  constructor(payload, namespace) {
+    let endpoint = "resumable-query";
+    if ("data" in payload) {
+      endpoint = "resumable-query-data";
+    }
+    if (namespace) {
+      endpoint = `${endpoint}/${namespace}`;
+    }
+    super(payload, endpoint);
+  }
+};
+
+// src/commands/client/resumable-query/stop.ts
+var StopResumableQueryCommand = class extends Command {
+  constructor(payload) {
+    super(payload, "resumable-query-end");
+  }
+};
+
+// src/commands/client/resumable-query/index.ts
+var ResumableQuery = class {
+  uuid;
+  start;
+  fetchNext;
+  stop;
+  constructor(payload, client, namespace) {
+    this.start = async () => {
+      const result = await new StartResumableQueryCommand(payload, namespace).exec(
+        client
+      );
+      this.uuid = result.uuid;
+      return result;
+    };
+    this.fetchNext = (additionalK) => {
+      if (!this.uuid) {
+        throw new Error(
+          "The resumable query has already been stopped. Please start another resumable query."
+        );
+      }
+      return new ResumeQueryCommand({ uuid: this.uuid, additionalK }).exec(client);
+    };
+    this.stop = async () => {
+      if (!this.uuid) {
+        throw new Error("Resumable query has not been started. Call start() first.");
+      }
+      const result = await new StopResumableQueryCommand({ uuid: this.uuid }).exec(client);
+      this.uuid = "";
+      return result;
+    };
+  }
+};
+
 // src/commands/client/namespace/index.ts
 var Namespace = class {
   client;
@@ -323,19 +400,21 @@ var Namespace = class {
    */
   update = (args) => new UpdateCommand(args, { namespace: this.namespace }).exec(this.client);
   /**
-   * 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.
@@ -376,34 +455,82 @@ var Namespace = class {
    */
   query = (args) => new QueryCommand(args, { namespace: this.namespace }).exec(this.client);
   /**
-   * 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
-   * ```js
-   * await index.namespace("ns").delete('test-id')
-   * // { deleted: 1 }
-   * ```
+   * 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' });
    *
-   * @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.
+   * const firstBatch = await fetchNext(10);
+   * const secondBatch = await fetchNext(10);
+   * await stop(); // End the query session
    */
+  resumableQuery = async (args) => {
+    const resumableQuery = new ResumableQuery(args, this.client, this.namespace);
+    const initialQuery = await resumableQuery.start();
+    const { fetchNext, stop } = resumableQuery;
+    return { fetchNext, stop, result: initialQuery.scores };
+  };
+  /**
+     * Deletes items from the index namespace by id, by id prefix, or by filter.
+     *
+     * @example
+     * ```js
+     * // 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 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) => new DeleteCommand(args, { namespace: this.namespace }).exec(this.client);
   /**
-   * 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.
@@ -437,67 +564,6 @@ var UpdateCommand = class extends Command {
   }
 };
 
-// src/commands/client/resumable-query/resume.ts
-var ResumeQueryCommand = class extends Command {
-  constructor(payload) {
-    super(payload, "resumable-query-next");
-  }
-};
-
-// src/commands/client/resumable-query/start.ts
-var StartResumableQueryCommand = class extends Command {
-  constructor(payload, namespace) {
-    let endpoint = "resumable-query";
-    if ("data" in payload) {
-      endpoint = "resumable-query-data";
-    }
-    if (namespace) {
-      endpoint = `${endpoint}/${namespace}`;
-    }
-    super(payload, endpoint);
-  }
-};
-
-// src/commands/client/resumable-query/stop.ts
-var StopResumableQueryCommand = class extends Command {
-  constructor(payload) {
-    super(payload, "resumable-query-end");
-  }
-};
-
-// src/commands/client/resumable-query/index.ts
-var ResumableQuery = class {
-  uuid;
-  start;
-  fetchNext;
-  stop;
-  constructor(payload, client, namespace) {
-    this.start = async () => {
-      const result = await new StartResumableQueryCommand(payload, namespace).exec(
-        client
-      );
-      this.uuid = result.uuid;
-      return result;
-    };
-    this.fetchNext = (additionalK) => {
-      if (!this.uuid) {
-        throw new Error(
-          "The resumable query has already been stopped. Please start another resumable query."
-        );
-      }
-      return new ResumeQueryCommand({ uuid: this.uuid, additionalK }).exec(client);
-    };
-    this.stop = async () => {
-      if (!this.uuid) {
-        throw new Error("Resumable query has not been started. Call start() first.");
-      }
-      const result = await new StopResumableQueryCommand({ uuid: this.uuid }).exec(client);
-      this.uuid = "";
-      return result;
-    };
-  }
-};
-
 // src/commands/management/namespaces/list/index.ts
 var ListNamespacesCommand = class extends Command {
   constructor() {
@@ -533,17 +599,26 @@ var Index = class {
   }
   namespace = (namespace) => new Namespace(this.client, namespace);
   /**
-   * Deletes a specific item or items from the index by their ID(s).   *
-   *
-   * @example
-   * ```js
-   * const result = await index.delete('test-id');
-   * // { deleted: 1 }
-   * ```
-   *
-   * @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.
-   */
+     * Deletes items from the index by id, by id prefix, or by filter.
+     *
+     * @example
+     * ```js
+     * // 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 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, options) => new DeleteCommand(args, options).exec(this.client);
   /**
    * Queries an index with specified parameters.
@@ -685,23 +760,25 @@ var Index = class {
    */
   update = (args, options) => new UpdateCommand(args, options).exec(this.client);
   /**
-   * 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.
    */
@@ -737,27 +814,28 @@ var Index = class {
    */
   reset = (options) => new ResetCommand(options).exec(this.client);
   /**
-   * 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.
@@ -805,6 +883,16 @@ var Index = class {
   deleteNamespace = (namespace) => new DeleteNamespaceCommand(namespace).exec(this.client);
 };
 
+// version.ts
+var VERSION = "v1.2.1";
+
+// src/utils/get-runtime.ts
+function getRuntime() {
+  if (typeof process === "object" && typeof process.versions == "object" && process.versions.bun)
+    return `bun@${process.versions.bun}`;
+  return typeof EdgeRuntime === "string" ? "edge-light" : `node@${process.version}`;
+}
+
 // src/platforms/nodejs.ts
 var Index2 = class _Index extends Index {
   constructor(configOrRequester) {
@@ -826,10 +914,16 @@ var Index2 = class _Index extends Index {
     if (token.startsWith(" ") || token.endsWith(" ") || /\r|\n/.test(token)) {
       console.warn("The vector token contains whitespace or newline, which can cause errors!");
     }
+    const enableTelemetry = process.env.UPSTASH_DISABLE_TELEMETRY ? false : configOrRequester?.enableTelemetry ?? true;
+    const telemetryHeaders = enableTelemetry ? {
+      "Upstash-Telemetry-Sdk": `upstash-vector-js@${VERSION}`,
+      "Upstash-Telemetry-Platform": process.env.VERCEL ? "vercel" : process.env.AWS_REGION ? "aws" : "unknown",
+      "Upstash-Telemetry-Runtime": getRuntime()
+    } : {};
     const client = new HttpClient({
       baseUrl: url,
       retry: configOrRequester?.retry,
-      headers: { authorization: `Bearer ${token}` },
+      headers: { authorization: `Bearer ${token}`, ...telemetryHeaders },
       cache: configOrRequester?.cache === false ? void 0 : configOrRequester?.cache || "no-store",
       signal: configOrRequester?.signal
     });

package/dist/nodejs.mjs

@@ -3,8 +3,16 @@ import {
   HttpClient,
   Index,
   QueryMode,
+  VERSION,
   WeightingStrategy
-} from "./chunk-4AKSNQD7.mjs";
+} from "./chunk-HESEGT2A.mjs";
+
+// src/utils/get-runtime.ts
+function getRuntime() {
+  if (typeof process === "object" && typeof process.versions == "object" && process.versions.bun)
+    return `bun@${process.versions.bun}`;
+  return typeof EdgeRuntime === "string" ? "edge-light" : `node@${process.version}`;
+}
 
 // src/platforms/nodejs.ts
 var Index2 = class _Index extends Index {
@@ -27,10 +35,16 @@ var Index2 = class _Index extends Index {
     if (token.startsWith(" ") || token.endsWith(" ") || /\r|\n/.test(token)) {
       console.warn("The vector token contains whitespace or newline, which can cause errors!");
     }
+    const enableTelemetry = process.env.UPSTASH_DISABLE_TELEMETRY ? false : configOrRequester?.enableTelemetry ?? true;
+    const telemetryHeaders = enableTelemetry ? {
+      "Upstash-Telemetry-Sdk": `upstash-vector-js@${VERSION}`,
+      "Upstash-Telemetry-Platform": process.env.VERCEL ? "vercel" : process.env.AWS_REGION ? "aws" : "unknown",
+      "Upstash-Telemetry-Runtime": getRuntime()
+    } : {};
     const client = new HttpClient({
       baseUrl: url,
       retry: configOrRequester?.retry,
-      headers: { authorization: `Bearer ${token}` },
+      headers: { authorization: `Bearer ${token}`, ...telemetryHeaders },
       cache: configOrRequester?.cache === false ? void 0 : configOrRequester?.cache || "no-store",
       signal: configOrRequester?.signal
     });