@upstash/vector 1.1.7 → 1.2.0-canary-hybrid

package/dist/{chunk-XN6MKCVR.mjs → chunk-6XOYYLIG.mjs}

@@ -58,7 +58,9 @@ var HttpClient = class {
           break;
         }
         error = error_;
-        await new Promise((r) => setTimeout(r, this.retry.backoff(i)));
+        if (i < this.retry.attempts) {
+          await new Promise((r) => setTimeout(r, this.retry.backoff(i)));
+        }
       }
     }
     if (!res) {
@@ -72,6 +74,23 @@ var HttpClient = class {
   }
 };
 
+// src/commands/client/query/types.ts
+var WeightingStrategy = /* @__PURE__ */ ((WeightingStrategy2) => {
+  WeightingStrategy2["IDF"] = "IDF";
+  return WeightingStrategy2;
+})(WeightingStrategy || {});
+var FusionAlgorithm = /* @__PURE__ */ ((FusionAlgorithm2) => {
+  FusionAlgorithm2["RRF"] = "RRF";
+  FusionAlgorithm2["DBSF"] = "DBSF";
+  return FusionAlgorithm2;
+})(FusionAlgorithm || {});
+var QueryMode = /* @__PURE__ */ ((QueryMode2) => {
+  QueryMode2["HYBRID"] = "HYBRID";
+  QueryMode2["DENSE"] = "DENSE";
+  QueryMode2["SPARSE"] = "SPARSE";
+  return QueryMode2;
+})(QueryMode || {});
+
 // src/commands/command.ts
 var Command = class {
   payload;
@@ -98,23 +117,6 @@ var Command = class {
   }
 };
 
-// src/commands/client/delete/index.ts
-var DeleteCommand = class extends Command {
-  constructor(id, options) {
-    let endpoint = "delete";
-    if (options?.namespace) {
-      endpoint = `${endpoint}/${options.namespace}`;
-    }
-    const finalArr = [];
-    if (Array.isArray(id)) {
-      finalArr.push(...id);
-    } else {
-      finalArr.push(id);
-    }
-    super(finalArr, endpoint);
-  }
-};
-
 // src/commands/client/query/query-many/index.ts
 var QueryManyCommand = class extends Command {
   constructor(payload, options) {
@@ -134,6 +136,8 @@ var QueryCommand = class extends Command {
     let endpoint = "query";
     if ("data" in payload) {
       endpoint = "query-data";
+    } else if (!payload.vector && !payload.sparseVector) {
+      throw new UpstashError("Either data, vector or sparseVector should be provided.");
     }
     if (options?.namespace) {
       endpoint = `${endpoint}/${options.namespace}`;
@@ -142,6 +146,23 @@ var QueryCommand = class extends Command {
   }
 };
 
+// src/commands/client/delete/index.ts
+var DeleteCommand = class extends Command {
+  constructor(id, options) {
+    let endpoint = "delete";
+    if (options?.namespace) {
+      endpoint = `${endpoint}/${options.namespace}`;
+    }
+    const finalArr = [];
+    if (Array.isArray(id)) {
+      finalArr.push(...id);
+    } else {
+      finalArr.push(id);
+    }
+    super(finalArr, endpoint);
+  }
+};
+
 // src/commands/client/upsert/index.ts
 var UpsertCommand = class extends Command {
   constructor(payload, opts) {
@@ -159,7 +180,7 @@ var UpsertCommand = class extends Command {
   }
 };
 var isVectorPayload = (payload) => {
-  return "vector" in payload;
+  return "vector" in payload || "sparseVector" in payload;
 };
 
 // src/commands/client/fetch/index.ts
@@ -380,6 +401,11 @@ var Namespace = class {
 var UpdateCommand = class extends Command {
   constructor(payload, opts) {
     let endpoint = "update";
+    if (!("metadata" in payload) && !("vector" in payload) && !("sparseVector" in payload) && !("data" in payload)) {
+      throw new UpstashError(
+        `Error while updating vector with id ${payload.id}.At least one of 'metadata', 'vector', 'sparseVector' or 'data' should be provided.`
+      );
+    }
     if (opts?.namespace) {
       endpoint = `${endpoint}/${opts.namespace}`;
     }
@@ -757,5 +783,8 @@ var Index = class {
 
 export {
   HttpClient,
+  WeightingStrategy,
+  FusionAlgorithm,
+  QueryMode,
   Index
 };

package/dist/cloudflare.d.mts

@@ -1,5 +1,5 @@
-import { R as RequesterConfig, D as Dict, I as Index$1 } from './vector-gR6tGrYi.mjs';
-export { F as FetchResult, d as InfoResult, Q as QueryResult, c as RangeResult, a as Requester, U as UpstashRequest, b as UpstashResponse, V as Vector } from './vector-gR6tGrYi.mjs';
+import { R as RequesterConfig, D as Dict, I as Index$1 } from './vector-uKwku_iy.mjs';
+export { d as FetchResult, F as FusionAlgorithm, f as InfoResult, Q as QueryMode, e as QueryResult, c as RangeResult, a as Requester, U as UpstashRequest, b as UpstashResponse, V as Vector, W as WeightingStrategy } from './vector-uKwku_iy.mjs';
 
 /**
  * Connection credentials for upstash vector.

package/dist/cloudflare.d.ts

@@ -1,5 +1,5 @@
-import { R as RequesterConfig, D as Dict, I as Index$1 } from './vector-gR6tGrYi.js';
-export { F as FetchResult, d as InfoResult, Q as QueryResult, c as RangeResult, a as Requester, U as UpstashRequest, b as UpstashResponse, V as Vector } from './vector-gR6tGrYi.js';
+import { R as RequesterConfig, D as Dict, I as Index$1 } from './vector-uKwku_iy.js';
+export { d as FetchResult, F as FusionAlgorithm, f as InfoResult, Q as QueryMode, e as QueryResult, c as RangeResult, a as Requester, U as UpstashRequest, b as UpstashResponse, V as Vector, W as WeightingStrategy } from './vector-uKwku_iy.js';
 
 /**
  * Connection credentials for upstash vector.

package/dist/cloudflare.js

@@ -20,7 +20,10 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/platforms/cloudflare.ts
 var cloudflare_exports = {};
 __export(cloudflare_exports, {
-  Index: () => Index2
+  FusionAlgorithm: () => FusionAlgorithm,
+  Index: () => Index2,
+  QueryMode: () => QueryMode,
+  WeightingStrategy: () => WeightingStrategy
 });
 module.exports = __toCommonJS(cloudflare_exports);
 
@@ -84,7 +87,9 @@ var HttpClient = class {
           break;
         }
         error = error_;
-        await new Promise((r) => setTimeout(r, this.retry.backoff(i)));
+        if (i < this.retry.attempts) {
+          await new Promise((r) => setTimeout(r, this.retry.backoff(i)));
+        }
       }
     }
     if (!res) {
@@ -160,6 +165,8 @@ var QueryCommand = class extends Command {
     let endpoint = "query";
     if ("data" in payload) {
       endpoint = "query-data";
+    } else if (!payload.vector && !payload.sparseVector) {
+      throw new UpstashError("Either data, vector or sparseVector should be provided.");
     }
     if (options?.namespace) {
       endpoint = `${endpoint}/${options.namespace}`;
@@ -168,6 +175,23 @@ var QueryCommand = class extends Command {
   }
 };
 
+// src/commands/client/query/types.ts
+var WeightingStrategy = /* @__PURE__ */ ((WeightingStrategy2) => {
+  WeightingStrategy2["IDF"] = "IDF";
+  return WeightingStrategy2;
+})(WeightingStrategy || {});
+var FusionAlgorithm = /* @__PURE__ */ ((FusionAlgorithm2) => {
+  FusionAlgorithm2["RRF"] = "RRF";
+  FusionAlgorithm2["DBSF"] = "DBSF";
+  return FusionAlgorithm2;
+})(FusionAlgorithm || {});
+var QueryMode = /* @__PURE__ */ ((QueryMode2) => {
+  QueryMode2["HYBRID"] = "HYBRID";
+  QueryMode2["DENSE"] = "DENSE";
+  QueryMode2["SPARSE"] = "SPARSE";
+  return QueryMode2;
+})(QueryMode || {});
+
 // src/commands/client/upsert/index.ts
 var UpsertCommand = class extends Command {
   constructor(payload, opts) {
@@ -185,7 +209,7 @@ var UpsertCommand = class extends Command {
   }
 };
 var isVectorPayload = (payload) => {
-  return "vector" in payload;
+  return "vector" in payload || "sparseVector" in payload;
 };
 
 // src/commands/client/fetch/index.ts
@@ -406,6 +430,11 @@ var Namespace = class {
 var UpdateCommand = class extends Command {
   constructor(payload, opts) {
     let endpoint = "update";
+    if (!("metadata" in payload) && !("vector" in payload) && !("sparseVector" in payload) && !("data" in payload)) {
+      throw new UpstashError(
+        `Error while updating vector with id ${payload.id}.At least one of 'metadata', 'vector', 'sparseVector' or 'data' should be provided.`
+      );
+    }
     if (opts?.namespace) {
       endpoint = `${endpoint}/${opts.namespace}`;
     }
@@ -856,5 +885,8 @@ var Index2 = class _Index extends Index {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  Index
+  FusionAlgorithm,
+  Index,
+  QueryMode,
+  WeightingStrategy
 });

package/dist/cloudflare.mjs

@@ -1,7 +1,10 @@
 import {
+  FusionAlgorithm,
   HttpClient,
-  Index
-} from "./chunk-XN6MKCVR.mjs";
+  Index,
+  QueryMode,
+  WeightingStrategy
+} from "./chunk-6XOYYLIG.mjs";
 
 // src/platforms/cloudflare.ts
 var Index2 = class _Index extends Index {
@@ -77,5 +80,8 @@ var Index2 = class _Index extends Index {
   }
 };
 export {
-  Index2 as Index
+  FusionAlgorithm,
+  Index2 as Index,
+  QueryMode,
+  WeightingStrategy
 };

package/dist/nodejs.d.mts

@@ -1,5 +1,5 @@
-import { R as RequesterConfig, D as Dict, I as Index$1, a as Requester } from './vector-gR6tGrYi.mjs';
-export { F as FetchResult, d as InfoResult, Q as QueryResult, c as RangeResult, U as UpstashRequest, b as UpstashResponse, V as Vector } from './vector-gR6tGrYi.mjs';
+import { R as RequesterConfig, D as Dict, I as Index$1, a as Requester } from './vector-uKwku_iy.mjs';
+export { d as FetchResult, F as FusionAlgorithm, f as InfoResult, Q as QueryMode, e as QueryResult, c as RangeResult, U as UpstashRequest, b as UpstashResponse, V as Vector, W as WeightingStrategy } from './vector-uKwku_iy.mjs';
 
 /**
  * Connection credentials for upstash vector.

package/dist/nodejs.d.ts

@@ -1,5 +1,5 @@
-import { R as RequesterConfig, D as Dict, I as Index$1, a as Requester } from './vector-gR6tGrYi.js';
-export { F as FetchResult, d as InfoResult, Q as QueryResult, c as RangeResult, U as UpstashRequest, b as UpstashResponse, V as Vector } from './vector-gR6tGrYi.js';
+import { R as RequesterConfig, D as Dict, I as Index$1, a as Requester } from './vector-uKwku_iy.js';
+export { d as FetchResult, F as FusionAlgorithm, f as InfoResult, Q as QueryMode, e as QueryResult, c as RangeResult, U as UpstashRequest, b as UpstashResponse, V as Vector, W as WeightingStrategy } from './vector-uKwku_iy.js';
 
 /**
  * Connection credentials for upstash vector.

package/dist/nodejs.js

@@ -20,7 +20,10 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/platforms/nodejs.ts
 var nodejs_exports = {};
 __export(nodejs_exports, {
-  Index: () => Index2
+  FusionAlgorithm: () => FusionAlgorithm,
+  Index: () => Index2,
+  QueryMode: () => QueryMode,
+  WeightingStrategy: () => WeightingStrategy
 });
 module.exports = __toCommonJS(nodejs_exports);
 
@@ -84,7 +87,9 @@ var HttpClient = class {
           break;
         }
         error = error_;
-        await new Promise((r) => setTimeout(r, this.retry.backoff(i)));
+        if (i < this.retry.attempts) {
+          await new Promise((r) => setTimeout(r, this.retry.backoff(i)));
+        }
       }
     }
     if (!res) {
@@ -160,6 +165,8 @@ var QueryCommand = class extends Command {
     let endpoint = "query";
     if ("data" in payload) {
       endpoint = "query-data";
+    } else if (!payload.vector && !payload.sparseVector) {
+      throw new UpstashError("Either data, vector or sparseVector should be provided.");
     }
     if (options?.namespace) {
       endpoint = `${endpoint}/${options.namespace}`;
@@ -168,6 +175,23 @@ var QueryCommand = class extends Command {
   }
 };
 
+// src/commands/client/query/types.ts
+var WeightingStrategy = /* @__PURE__ */ ((WeightingStrategy2) => {
+  WeightingStrategy2["IDF"] = "IDF";
+  return WeightingStrategy2;
+})(WeightingStrategy || {});
+var FusionAlgorithm = /* @__PURE__ */ ((FusionAlgorithm2) => {
+  FusionAlgorithm2["RRF"] = "RRF";
+  FusionAlgorithm2["DBSF"] = "DBSF";
+  return FusionAlgorithm2;
+})(FusionAlgorithm || {});
+var QueryMode = /* @__PURE__ */ ((QueryMode2) => {
+  QueryMode2["HYBRID"] = "HYBRID";
+  QueryMode2["DENSE"] = "DENSE";
+  QueryMode2["SPARSE"] = "SPARSE";
+  return QueryMode2;
+})(QueryMode || {});
+
 // src/commands/client/upsert/index.ts
 var UpsertCommand = class extends Command {
   constructor(payload, opts) {
@@ -185,7 +209,7 @@ var UpsertCommand = class extends Command {
   }
 };
 var isVectorPayload = (payload) => {
-  return "vector" in payload;
+  return "vector" in payload || "sparseVector" in payload;
 };
 
 // src/commands/client/fetch/index.ts
@@ -406,6 +430,11 @@ var Namespace = class {
 var UpdateCommand = class extends Command {
   constructor(payload, opts) {
     let endpoint = "update";
+    if (!("metadata" in payload) && !("vector" in payload) && !("sparseVector" in payload) && !("data" in payload)) {
+      throw new UpstashError(
+        `Error while updating vector with id ${payload.id}.At least one of 'metadata', 'vector', 'sparseVector' or 'data' should be provided.`
+      );
+    }
     if (opts?.namespace) {
       endpoint = `${endpoint}/${opts.namespace}`;
     }
@@ -835,5 +864,8 @@ var Index2 = class _Index extends Index {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  Index
+  FusionAlgorithm,
+  Index,
+  QueryMode,
+  WeightingStrategy
 });

package/dist/nodejs.mjs

@@ -1,7 +1,10 @@
 import {
+  FusionAlgorithm,
   HttpClient,
-  Index
-} from "./chunk-XN6MKCVR.mjs";
+  Index,
+  QueryMode,
+  WeightingStrategy
+} from "./chunk-6XOYYLIG.mjs";
 
 // src/platforms/nodejs.ts
 var Index2 = class _Index extends Index {
@@ -56,5 +59,8 @@ var Index2 = class _Index extends Index {
   }
 };
 export {
-  Index2 as Index
+  FusionAlgorithm,
+  Index2 as Index,
+  QueryMode,
+  WeightingStrategy
 };

package/dist/{vector-gR6tGrYi.d.mts → vector-uKwku_iy.d.mts}

@@ -45,11 +45,13 @@ type RequesterConfig = {
 type Vector<TMetadata = Dict> = {
     id: string;
     vector?: number[];
+    sparseVector?: SparseVector;
     metadata?: TMetadata;
     data?: string;
 };
 type NAMESPACE = string;
 type Dict = Record<string, unknown>;
+type SparseVector = [indices: number[], values: number[]];
 
 declare const _ENDPOINTS: readonly ["upsert", "update", "query", "delete", "fetch", "reset", "range", "info", "resumable-query", "resumable-query-data", "resumable-query-next", "resumable-query-end", "upsert-data", "query-data", "list-namespaces", "delete-namespace"];
 type EndpointVariants = (typeof _ENDPOINTS)[number] | `${(typeof _ENDPOINTS)[number]}/${NAMESPACE}` | `reset?all`;
@@ -80,23 +82,138 @@ type QueryCommandPayload = {
     includeVectors?: boolean;
     includeMetadata?: boolean;
     includeData?: boolean;
+    weightingStrategy?: WeightingStrategy;
+    fusionAlgorithm?: FusionAlgorithm;
+    queryMode?: QueryMode;
 } & ({
-    vector: number[];
+    vector?: number[];
+    sparseVector?: SparseVector;
     data?: never;
 } | {
     data: string;
     vector?: never;
+    sparseVector?: never;
 });
 type QueryResult<TMetadata = Dict> = {
     id: number | string;
     score: number;
     vector?: number[];
+    sparseVector?: SparseVector;
     metadata?: TMetadata;
     data?: string;
 };
 type QueryCommandOptions = {
     namespace?: string;
 };
+/**
+ * For sparse vectors, what kind of weighting strategy
+ * should be used while querying the matching non-zero
+ * dimension values of the query vector with the documents.
+ *
+ * If not provided, no weighting will be used.
+ */
+declare enum WeightingStrategy {
+    /**
+     * Inverse document frequency.
+     *
+     * It is recommended to use this weighting strategy for
+     * BM25 sparse embedding models.
+     *
+     * It is calculated as
+     *
+     * ln(((N - n(q) + 0.5) / (n(q) + 0.5)) + 1) where
+     * N:    Total number of sparse vectors.
+     * n(q): Total number of sparse vectors having non-zero value
+     *       for that particular dimension.
+     * ln:   Natural logarithm
+     *
+     * The values of N and n(q) are maintained by Upstash as the
+     * vectors are indexed.
+     */
+    IDF = "IDF"
+}
+/**
+ * Fusion algorithm to use while fusing scores
+ * from dense and sparse components of a hybrid index.
+ *
+ * If not provided, defaults to `RRF`.
+ */
+declare enum FusionAlgorithm {
+    /**
+     * Reciprocal rank fusion.
+     *
+     * Each sorted score from the dense and sparse indexes are
+     * mapped to 1 / (rank + K), where rank is the order of the
+     * score in the dense or sparse scores and K is a constant
+     * with the value of 60.
+     *
+     * Then, scores from the dense and sparse components are
+     * deduplicated (i.e. if a score for the same vector is present
+     * in both dense and sparse scores, the mapped scores are
+     * added; otherwise individual mapped scores are used)
+     * and the final result is returned as the topK values
+     * of this final list.
+     *
+     * In short, this algorithm just takes the order of the scores
+     * into consideration.
+     */
+    RRF = "RRF",
+    /**
+     * Distribution based score fusion.
+     *
+     * Each sorted score from the dense and sparse indexes are
+     * normalized as
+     * (s - (mean - 3 * stddev)) / ((mean + 3 * stddev) - (mean - 3 * stddev))
+     * where s is the score, (mean - 3 * stddev) is the minimum,
+     * and (mean + 3 * stddev) is the maximum tail ends of the distribution.
+     *
+     * Then, scores from the dense and sparse components are
+     * deduplicated (i.e. if a score for the same vector is present
+     * in both dense and sparse scores, the normalized scores are
+     * added; otherwise individual normalized scores are used)
+     * and the final result is returned as the topK values
+     * of this final list.
+     *
+     * In short, this algorithm takes distribution of the scores
+     * into consideration as well, as opposed to the `RRF`.
+     */
+    DBSF = "DBSF"
+}
+/**
+ * Query mode for hybrid indexes with Upstash-hosted
+ * embedding models.
+ *
+ * Specifies whether to run the query in only the
+ * dense index, only the sparse index, or in both.
+ *
+ * If not provided, defaults to `HYBRID`.
+ */
+declare enum QueryMode {
+    /**
+     * Runs the query in hybrid index mode, after embedding
+     * the raw text data into dense and sparse vectors.
+     *
+     * Query results from the dense and sparse index components
+     * of the hybrid index are fused before returning the result.
+     */
+    HYBRID = "HYBRID",
+    /**
+     * Runs the query in dense index mode, after embedding
+     * the raw text data into a dense vector.
+     *
+     * Only the query results from the dense index component
+     * of the hybrid index is returned.
+     */
+    DENSE = "DENSE",
+    /**
+     * Runs the query in sparse index mode, after embedding
+     * the raw text data into a sparse vector.
+     *
+     * Only the query results from the sparse index component
+     * of the hybrid index is returned.
+     */
+    SPARSE = "SPARSE"
+}
 
 declare class QueryManyCommand<TMetadata> extends Command<QueryResult<TMetadata>[][]> {
     constructor(payload: QueryCommandPayload[], options?: QueryCommandOptions);
@@ -189,7 +306,8 @@ declare class Namespace<TIndexMetadata extends Dict = Dict> {
      */
     upsert: <TMetadata extends Dict = TIndexMetadata>(args: {
         id: string | number;
-        vector: number[];
+        vector?: number[] | undefined;
+        sparseVector?: SparseVector | undefined;
         metadata?: (TMetadata extends infer U ? U : never) | undefined;
     } | {
         id: string | number;
@@ -197,7 +315,8 @@ declare class Namespace<TIndexMetadata extends Dict = Dict> {
         metadata?: (TMetadata extends infer U ? U : never) | undefined;
     } | {
         id: string | number;
-        vector: number[];
+        vector?: number[] | undefined;
+        sparseVector?: SparseVector | undefined;
         metadata?: (TMetadata extends infer U ? U : never) | undefined;
     }[] | {
         id: string | number;
@@ -206,7 +325,8 @@ declare class Namespace<TIndexMetadata extends Dict = Dict> {
     }[]) => Promise<string>;
     update: <TMetadata extends Dict = TIndexMetadata>(args: {
         id: string | number;
-        vector: number[];
+        vector?: number[] | undefined;
+        sparseVector?: SparseVector | undefined;
     } | {
         id: string | number;
         data: string;
@@ -215,7 +335,28 @@ declare class Namespace<TIndexMetadata extends Dict = Dict> {
         metadata: TMetadata extends infer U ? U : never;
         metadataUpdateMode?: "PATCH" | "OVERWRITE" | undefined;
     }) => Promise<{
-        updated: number;
+        updated: number; /**
+         * Upserts (Updates and Inserts) specific items into the index namespace.
+         * It's used for adding new items to the index namespace or updating existing ones.
+         *
+         * @example
+         * ```js
+         * const upsertArgs = {
+         *   id: '123',
+         *   vector: [0.42, 0.87, ...],
+         *   metadata: { property1: 'value1', property2: 'value2' }
+         * };
+         * const upsertResult = await index.namespace("ns").upsert(upsertArgs);
+         * console.log(upsertResult); // Outputs the result of the upsert operation
+         * ```
+         *
+         * @param {CommandArgs<typeof UpsertCommand>} args - The arguments for the upsert command.
+         * @param {number|string} args.id - The unique identifier for the item being upserted.
+         * @param {number[]} args.vector - The feature vector associated with the item.
+         * @param {Dict} [args.metadata] - Optional metadata to be associated with the item.
+         *
+         * @returns {string} A promise that resolves with the result of the upsert operation after the command is executed.
+         */
     }>;
     /**
      * It's used for retrieving specific items from the index namespace, optionally including
@@ -482,7 +623,8 @@ declare class Index<TIndexMetadata extends Dict = Dict> {
      */
     upsert: <TMetadata extends Dict = TIndexMetadata>(args: {
         id: string | number;
-        vector: number[];
+        vector?: number[] | undefined;
+        sparseVector?: SparseVector | undefined;
         metadata?: (TMetadata extends infer U ? U : never) | undefined;
     } | {
         id: string | number;
@@ -490,7 +632,8 @@ declare class Index<TIndexMetadata extends Dict = Dict> {
         metadata?: (TMetadata extends infer U ? U : never) | undefined;
     } | {
         id: string | number;
-        vector: number[];
+        vector?: number[] | undefined;
+        sparseVector?: SparseVector | undefined;
         metadata?: (TMetadata extends infer U ? U : never) | undefined;
     }[] | {
         id: string | number;
@@ -501,7 +644,8 @@ declare class Index<TIndexMetadata extends Dict = Dict> {
     }) => Promise<string>;
     update: <TMetadata extends Dict = TIndexMetadata>(args: {
         id: string | number;
-        vector: number[];
+        vector?: number[] | undefined;
+        sparseVector?: SparseVector | undefined;
     } | {
         id: string | number;
         data: string;
@@ -642,4 +786,4 @@ declare class Index<TIndexMetadata extends Dict = Dict> {
     deleteNamespace: (namespace: string) => Promise<string>;
 }
 
-export { type Dict as D, type FetchResult as F, Index as I, type QueryResult as Q, type RequesterConfig as R, type UpstashRequest as U, type Vector as V, type Requester as a, type UpstashResponse as b, type RangeResult as c, type InfoResult as d };
+export { type Dict as D, FusionAlgorithm as F, Index as I, QueryMode as Q, type RequesterConfig as R, 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/dist/{vector-gR6tGrYi.d.ts → vector-uKwku_iy.d.ts}

@@ -45,11 +45,13 @@ type RequesterConfig = {
 type Vector<TMetadata = Dict> = {
     id: string;
     vector?: number[];
+    sparseVector?: SparseVector;
     metadata?: TMetadata;
     data?: string;
 };
 type NAMESPACE = string;
 type Dict = Record<string, unknown>;
+type SparseVector = [indices: number[], values: number[]];
 
 declare const _ENDPOINTS: readonly ["upsert", "update", "query", "delete", "fetch", "reset", "range", "info", "resumable-query", "resumable-query-data", "resumable-query-next", "resumable-query-end", "upsert-data", "query-data", "list-namespaces", "delete-namespace"];
 type EndpointVariants = (typeof _ENDPOINTS)[number] | `${(typeof _ENDPOINTS)[number]}/${NAMESPACE}` | `reset?all`;
@@ -80,23 +82,138 @@ type QueryCommandPayload = {
     includeVectors?: boolean;
     includeMetadata?: boolean;
     includeData?: boolean;
+    weightingStrategy?: WeightingStrategy;
+    fusionAlgorithm?: FusionAlgorithm;
+    queryMode?: QueryMode;
 } & ({
-    vector: number[];
+    vector?: number[];
+    sparseVector?: SparseVector;
     data?: never;
 } | {
     data: string;
     vector?: never;
+    sparseVector?: never;
 });
 type QueryResult<TMetadata = Dict> = {
     id: number | string;
     score: number;
     vector?: number[];
+    sparseVector?: SparseVector;
     metadata?: TMetadata;
     data?: string;
 };
 type QueryCommandOptions = {
     namespace?: string;
 };
+/**
+ * For sparse vectors, what kind of weighting strategy
+ * should be used while querying the matching non-zero
+ * dimension values of the query vector with the documents.
+ *
+ * If not provided, no weighting will be used.
+ */
+declare enum WeightingStrategy {
+    /**
+     * Inverse document frequency.
+     *
+     * It is recommended to use this weighting strategy for
+     * BM25 sparse embedding models.
+     *
+     * It is calculated as
+     *
+     * ln(((N - n(q) + 0.5) / (n(q) + 0.5)) + 1) where
+     * N:    Total number of sparse vectors.
+     * n(q): Total number of sparse vectors having non-zero value
+     *       for that particular dimension.
+     * ln:   Natural logarithm
+     *
+     * The values of N and n(q) are maintained by Upstash as the
+     * vectors are indexed.
+     */
+    IDF = "IDF"
+}
+/**
+ * Fusion algorithm to use while fusing scores
+ * from dense and sparse components of a hybrid index.
+ *
+ * If not provided, defaults to `RRF`.
+ */
+declare enum FusionAlgorithm {
+    /**
+     * Reciprocal rank fusion.
+     *
+     * Each sorted score from the dense and sparse indexes are
+     * mapped to 1 / (rank + K), where rank is the order of the
+     * score in the dense or sparse scores and K is a constant
+     * with the value of 60.
+     *
+     * Then, scores from the dense and sparse components are
+     * deduplicated (i.e. if a score for the same vector is present
+     * in both dense and sparse scores, the mapped scores are
+     * added; otherwise individual mapped scores are used)
+     * and the final result is returned as the topK values
+     * of this final list.
+     *
+     * In short, this algorithm just takes the order of the scores
+     * into consideration.
+     */
+    RRF = "RRF",
+    /**
+     * Distribution based score fusion.
+     *
+     * Each sorted score from the dense and sparse indexes are
+     * normalized as
+     * (s - (mean - 3 * stddev)) / ((mean + 3 * stddev) - (mean - 3 * stddev))
+     * where s is the score, (mean - 3 * stddev) is the minimum,
+     * and (mean + 3 * stddev) is the maximum tail ends of the distribution.
+     *
+     * Then, scores from the dense and sparse components are
+     * deduplicated (i.e. if a score for the same vector is present
+     * in both dense and sparse scores, the normalized scores are
+     * added; otherwise individual normalized scores are used)
+     * and the final result is returned as the topK values
+     * of this final list.
+     *
+     * In short, this algorithm takes distribution of the scores
+     * into consideration as well, as opposed to the `RRF`.
+     */
+    DBSF = "DBSF"
+}
+/**
+ * Query mode for hybrid indexes with Upstash-hosted
+ * embedding models.
+ *
+ * Specifies whether to run the query in only the
+ * dense index, only the sparse index, or in both.
+ *
+ * If not provided, defaults to `HYBRID`.
+ */
+declare enum QueryMode {
+    /**
+     * Runs the query in hybrid index mode, after embedding
+     * the raw text data into dense and sparse vectors.
+     *
+     * Query results from the dense and sparse index components
+     * of the hybrid index are fused before returning the result.
+     */
+    HYBRID = "HYBRID",
+    /**
+     * Runs the query in dense index mode, after embedding
+     * the raw text data into a dense vector.
+     *
+     * Only the query results from the dense index component
+     * of the hybrid index is returned.
+     */
+    DENSE = "DENSE",
+    /**
+     * Runs the query in sparse index mode, after embedding
+     * the raw text data into a sparse vector.
+     *
+     * Only the query results from the sparse index component
+     * of the hybrid index is returned.
+     */
+    SPARSE = "SPARSE"
+}
 
 declare class QueryManyCommand<TMetadata> extends Command<QueryResult<TMetadata>[][]> {
     constructor(payload: QueryCommandPayload[], options?: QueryCommandOptions);
@@ -189,7 +306,8 @@ declare class Namespace<TIndexMetadata extends Dict = Dict> {
      */
     upsert: <TMetadata extends Dict = TIndexMetadata>(args: {
         id: string | number;
-        vector: number[];
+        vector?: number[] | undefined;
+        sparseVector?: SparseVector | undefined;
         metadata?: (TMetadata extends infer U ? U : never) | undefined;
     } | {
         id: string | number;
@@ -197,7 +315,8 @@ declare class Namespace<TIndexMetadata extends Dict = Dict> {
         metadata?: (TMetadata extends infer U ? U : never) | undefined;
     } | {
         id: string | number;
-        vector: number[];
+        vector?: number[] | undefined;
+        sparseVector?: SparseVector | undefined;
         metadata?: (TMetadata extends infer U ? U : never) | undefined;
     }[] | {
         id: string | number;
@@ -206,7 +325,8 @@ declare class Namespace<TIndexMetadata extends Dict = Dict> {
     }[]) => Promise<string>;
     update: <TMetadata extends Dict = TIndexMetadata>(args: {
         id: string | number;
-        vector: number[];
+        vector?: number[] | undefined;
+        sparseVector?: SparseVector | undefined;
     } | {
         id: string | number;
         data: string;
@@ -215,7 +335,28 @@ declare class Namespace<TIndexMetadata extends Dict = Dict> {
         metadata: TMetadata extends infer U ? U : never;
         metadataUpdateMode?: "PATCH" | "OVERWRITE" | undefined;
     }) => Promise<{
-        updated: number;
+        updated: number; /**
+         * Upserts (Updates and Inserts) specific items into the index namespace.
+         * It's used for adding new items to the index namespace or updating existing ones.
+         *
+         * @example
+         * ```js
+         * const upsertArgs = {
+         *   id: '123',
+         *   vector: [0.42, 0.87, ...],
+         *   metadata: { property1: 'value1', property2: 'value2' }
+         * };
+         * const upsertResult = await index.namespace("ns").upsert(upsertArgs);
+         * console.log(upsertResult); // Outputs the result of the upsert operation
+         * ```
+         *
+         * @param {CommandArgs<typeof UpsertCommand>} args - The arguments for the upsert command.
+         * @param {number|string} args.id - The unique identifier for the item being upserted.
+         * @param {number[]} args.vector - The feature vector associated with the item.
+         * @param {Dict} [args.metadata] - Optional metadata to be associated with the item.
+         *
+         * @returns {string} A promise that resolves with the result of the upsert operation after the command is executed.
+         */
     }>;
     /**
      * It's used for retrieving specific items from the index namespace, optionally including
@@ -482,7 +623,8 @@ declare class Index<TIndexMetadata extends Dict = Dict> {
      */
     upsert: <TMetadata extends Dict = TIndexMetadata>(args: {
         id: string | number;
-        vector: number[];
+        vector?: number[] | undefined;
+        sparseVector?: SparseVector | undefined;
         metadata?: (TMetadata extends infer U ? U : never) | undefined;
     } | {
         id: string | number;
@@ -490,7 +632,8 @@ declare class Index<TIndexMetadata extends Dict = Dict> {
         metadata?: (TMetadata extends infer U ? U : never) | undefined;
     } | {
         id: string | number;
-        vector: number[];
+        vector?: number[] | undefined;
+        sparseVector?: SparseVector | undefined;
         metadata?: (TMetadata extends infer U ? U : never) | undefined;
     }[] | {
         id: string | number;
@@ -501,7 +644,8 @@ declare class Index<TIndexMetadata extends Dict = Dict> {
     }) => Promise<string>;
     update: <TMetadata extends Dict = TIndexMetadata>(args: {
         id: string | number;
-        vector: number[];
+        vector?: number[] | undefined;
+        sparseVector?: SparseVector | undefined;
     } | {
         id: string | number;
         data: string;
@@ -642,4 +786,4 @@ declare class Index<TIndexMetadata extends Dict = Dict> {
     deleteNamespace: (namespace: string) => Promise<string>;
 }
 
-export { type Dict as D, type FetchResult as F, Index as I, type QueryResult as Q, type RequesterConfig as R, type UpstashRequest as U, type Vector as V, type Requester as a, type UpstashResponse as b, type RangeResult as c, type InfoResult as d };
+export { type Dict as D, FusionAlgorithm as F, Index as I, QueryMode as Q, type RequesterConfig as R, 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.1.7", "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 && vitest run --typecheck", "fmt": "prettier --write .", "lint": "tsc && eslint \"src/**/*.{js,ts,tsx}\" --quiet --fix", "build": "tsup", "prepare": "husky install" } }
+{ "name": "@upstash/vector", "version": "v1.2.0-canary-hybrid", "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" } }