@upstash/vector 1.2.0-canary → 1.2.0-canary-hybrid-1

package/README.md

@@ -49,11 +49,11 @@ const index = new Index<Metadata>({
   token: "<UPSTASH_VECTOR_REST_TOKEN>",
 });
 
-//Upsert data
+// Upsert to dense index
 await index.upsert([{
   id: 'upstash-rocks',
   vector: [
-    .... // embedding values
+    0.13, 0.87, ... // dense embedding
   ],
   metadata: {
     title: 'Lord of The Rings',
@@ -62,13 +62,44 @@ await index.upsert([{
   }
 }])
 
+// Upsert to sparse index
+await index.upsert([{
+  id: 'upstash-rocks',
+  sparseVector: { // sparse embedding
+    indices: [2, 3],
+    values: [0.13, 0.87],
+  },
+  metadata: {
+    title: 'Lord of The Rings',
+    genre: 'fantasy',
+    category: 'classic'
+  }
+}])
+
+// Upsert to hybrid index
+await index.upsert([{
+  id: 'upstash-rocks',
+  vector: [
+    0.13, 0.87, ... // dense embedding
+  ],
+  sparseVector: {   // sparse embedding
+    indices: [2, 3],
+    values: [0.13, 0.87],
+  },
+  metadata: {
+    title: 'Lord of The Rings',
+    genre: 'fantasy',
+    category: 'classic'
+  }
+}])
+
 // Upsert data as plain text.
 await index.upsert([{
   id: 'tokyo',
   data: "Tokyo is the capital of Japan.",
 }])
 
-//Upsert data alongside with your embedding
+// Upsert data alongside with your embedding
 await index.upsert([{
   id: 'tokyo',
   data: "Tokyo is the capital of Japan.",
@@ -76,7 +107,7 @@ await index.upsert([{
 }])
 
 
-//Query data
+// Query data
 const results = await index.query<Metadata>(
   {
     vector: [
@@ -92,7 +123,7 @@ const results = await index.query<Metadata>(
   }
 )
 
-//Query with your data
+// Query with your data
 const results = await index.query(
   {
     data: "Where is the capital of Japan",
@@ -100,7 +131,7 @@ const results = await index.query(
   },
 )
 
-//Query with your data
+// Query with your data
 const results = await index.query(
   {
     vector: [
@@ -113,7 +144,7 @@ const results = await index.query(
 
 // If you wanna learn more about filtering check: [Metadata Filtering](https://upstash.com/docs/vector/features/filtering)
 
-//Update data
+// Update data
 await index.upsert(
   {
     id: "upstash-rocks",
@@ -128,19 +159,19 @@ await index.upsert(
   }
 );
 
-//Delete record
+// Delete record
 await index.delete("upstash-rocks", {namespace: "example-namespace"});
 
-//Delete many by id
+// Delete many by id
 await index.delete(["id-1", "id-2", "id-3"]);
 
-//Fetch records by their IDs
+// Fetch records by their IDs
 await index.fetch(["id-1", "id-2"], {namespace: "example-namespace"});
 
-//Fetch records by their IDs
+// Fetch records by their IDs
 await index.fetch(["id-1", "id-2"], {namespace: "example-namespace", includeData:true});
 
-//Fetch records with range
+// Fetch records with range
 await index.range(
   {
     cursor: 0,
@@ -152,19 +183,19 @@ await index.range(
   }
 );
 
-//Reset index
+// Reset index
 await index.reset();
 
-//Info about index
+// Info about index
 await index.info();
 
-//Random vector based on stored vectors
+// Random vector based on stored vectors
 await index.random({namespace: "example-namespace"});
 
-//List existing namesapces
+// List existing namesapces
 await index.listNamespaces();
 
-//Delete a namespace
+// Delete a namespace
 await index.deleteNamespace("namespace-to-be-deleted");
 ```
 
@@ -190,7 +221,7 @@ const index = new Index<Metadata>({
 
 const namespace = index.namespace("example-namespace");
 
-//Upsert Data
+// Upsert Data
 await namespace.upsert([{
   id: 'upstash-rocks',
   vector: [
@@ -203,7 +234,7 @@ await namespace.upsert([{
   }
 }])
 
-//Query Vector
+// Query Vector
 const results = await namespace.query<Metadata>(
   {
     vector: [
@@ -216,10 +247,10 @@ const results = await namespace.query<Metadata>(
   },
 )
 
-//Delete Record
+// Delete Record
 await namespace.delete("upstash-rocks");
 
-//Fetch records by their IDs
+// Fetch records by their IDs
 await namespace.fetch(["id-1", "id-2"]);
 ```
 

package/dist/{chunk-XN6MKCVR.mjs → chunk-4AKSNQD7.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
@@ -757,5 +778,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-Cj9w3M1X.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-Cj9w3M1X.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-Cj9w3M1X.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-Cj9w3M1X.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
@@ -800,8 +824,9 @@ var Index2 = class _Index extends Index {
    * ```
    */
   constructor(config) {
-    const token = config?.token ?? process.env.NEXT_PUBLIC_UPSTASH_VECTOR_REST_TOKEN ?? process.env.UPSTASH_VECTOR_REST_TOKEN;
-    const url = config?.url ?? process.env.NEXT_PUBLIC_UPSTASH_VECTOR_REST_URL ?? process.env.UPSTASH_VECTOR_REST_URL;
+    const safeProcess = typeof process === "undefined" ? {} : process;
+    const token = config?.token ?? safeProcess.NEXT_PUBLIC_UPSTASH_VECTOR_REST_TOKEN ?? safeProcess.UPSTASH_VECTOR_REST_TOKEN;
+    const url = config?.url ?? safeProcess.NEXT_PUBLIC_UPSTASH_VECTOR_REST_URL ?? safeProcess.UPSTASH_VECTOR_REST_URL;
     if (!token) {
       throw new Error("UPSTASH_VECTOR_REST_TOKEN is missing!");
     }
@@ -855,5 +880,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-4AKSNQD7.mjs";
 
 // src/platforms/cloudflare.ts
 var Index2 = class _Index extends Index {
@@ -22,8 +25,9 @@ var Index2 = class _Index extends Index {
    * ```
    */
   constructor(config) {
-    const token = config?.token ?? process.env.NEXT_PUBLIC_UPSTASH_VECTOR_REST_TOKEN ?? process.env.UPSTASH_VECTOR_REST_TOKEN;
-    const url = config?.url ?? process.env.NEXT_PUBLIC_UPSTASH_VECTOR_REST_URL ?? process.env.UPSTASH_VECTOR_REST_URL;
+    const safeProcess = typeof process === "undefined" ? {} : process;
+    const token = config?.token ?? safeProcess.NEXT_PUBLIC_UPSTASH_VECTOR_REST_TOKEN ?? safeProcess.UPSTASH_VECTOR_REST_TOKEN;
+    const url = config?.url ?? safeProcess.NEXT_PUBLIC_UPSTASH_VECTOR_REST_URL ?? safeProcess.UPSTASH_VECTOR_REST_URL;
     if (!token) {
       throw new Error("UPSTASH_VECTOR_REST_TOKEN is missing!");
     }
@@ -76,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-Cj9w3M1X.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-Cj9w3M1X.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-Cj9w3M1X.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-Cj9w3M1X.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
@@ -835,5 +859,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-4AKSNQD7.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-Cj9w3M1X.d.mts}

@@ -45,11 +45,16 @@ 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 +85,142 @@ type QueryCommandPayload = {
     includeVectors?: boolean;
     includeMetadata?: boolean;
     includeData?: boolean;
+    weightingStrategy?: WeightingStrategy;
+    fusionAlgorithm?: FusionAlgorithm;
+    queryMode?: QueryMode;
 } & ({
     vector: number[];
+    sparseVector?: SparseVector;
+    data?: never;
+} | {
+    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);
@@ -187,27 +311,51 @@ declare class Namespace<TIndexMetadata extends Dict = Dict> {
      *
      * @returns {string} A promise that resolves with the result of the upsert operation after the command is executed.
      */
-    upsert: <TMetadata extends Dict = TIndexMetadata>(args: {
+    upsert: <TMetadata extends Dict = TIndexMetadata>(args: ({
         id: string | number;
-        vector: number[];
         metadata?: (TMetadata extends infer U ? U : never) | undefined;
+    } & ({
+        vector: number[];
+        sparseVector?: undefined;
+    } | {
+        vector?: undefined;
+        sparseVector: SparseVector;
     } | {
+        vector: number[];
+        sparseVector: SparseVector;
+    })) | {
         id: string | number;
         data: string;
         metadata?: (TMetadata extends infer U ? U : never) | undefined;
-    } | {
+    } | ({
         id: string | number;
-        vector: number[];
         metadata?: (TMetadata extends infer U ? U : never) | undefined;
-    }[] | {
+    } & ({
+        vector: number[];
+        sparseVector?: undefined;
+    } | {
+        vector?: undefined;
+        sparseVector: SparseVector;
+    } | {
+        vector: number[];
+        sparseVector: SparseVector;
+    }))[] | {
         id: string | number;
         data: string;
         metadata?: (TMetadata extends infer U ? U : never) | undefined;
     }[]) => Promise<string>;
-    update: <TMetadata extends Dict = TIndexMetadata>(args: {
+    update: <TMetadata extends Dict = TIndexMetadata>(args: ({
         id: string | number;
+    } & ({
+        vector?: undefined;
+        sparseVector: SparseVector;
+    } | {
         vector: number[];
+        sparseVector?: undefined;
     } | {
+        vector: number[];
+        sparseVector: SparseVector;
+    })) | {
         id: string | number;
         data: string;
     } | {
@@ -480,29 +628,53 @@ declare class Index<TIndexMetadata extends Dict = Dict> {
      *
      * @returns {string} A promise that resolves with the result of the upsert operation after the command is executed.
      */
-    upsert: <TMetadata extends Dict = TIndexMetadata>(args: {
+    upsert: <TMetadata extends Dict = TIndexMetadata>(args: ({
         id: string | number;
-        vector: number[];
         metadata?: (TMetadata extends infer U ? U : never) | undefined;
+    } & ({
+        vector: number[];
+        sparseVector?: undefined;
     } | {
+        vector?: undefined;
+        sparseVector: SparseVector;
+    } | {
+        vector: number[];
+        sparseVector: SparseVector;
+    })) | {
         id: string | number;
         data: string;
         metadata?: (TMetadata extends infer U ? U : never) | undefined;
-    } | {
+    } | ({
         id: string | number;
-        vector: number[];
         metadata?: (TMetadata extends infer U ? U : never) | undefined;
-    }[] | {
+    } & ({
+        vector: number[];
+        sparseVector?: undefined;
+    } | {
+        vector?: undefined;
+        sparseVector: SparseVector;
+    } | {
+        vector: number[];
+        sparseVector: SparseVector;
+    }))[] | {
         id: string | number;
         data: string;
         metadata?: (TMetadata extends infer U ? U : never) | undefined;
     }[], options?: {
         namespace?: string;
     }) => Promise<string>;
-    update: <TMetadata extends Dict = TIndexMetadata>(args: {
+    update: <TMetadata extends Dict = TIndexMetadata>(args: ({
         id: string | number;
+    } & ({
+        vector?: undefined;
+        sparseVector: SparseVector;
+    } | {
         vector: number[];
+        sparseVector?: undefined;
     } | {
+        vector: number[];
+        sparseVector: SparseVector;
+    })) | {
         id: string | number;
         data: string;
     } | {
@@ -642,4 +814,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-Cj9w3M1X.d.ts}

@@ -45,11 +45,16 @@ 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 +85,142 @@ type QueryCommandPayload = {
     includeVectors?: boolean;
     includeMetadata?: boolean;
     includeData?: boolean;
+    weightingStrategy?: WeightingStrategy;
+    fusionAlgorithm?: FusionAlgorithm;
+    queryMode?: QueryMode;
 } & ({
     vector: number[];
+    sparseVector?: SparseVector;
+    data?: never;
+} | {
+    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);
@@ -187,27 +311,51 @@ declare class Namespace<TIndexMetadata extends Dict = Dict> {
      *
      * @returns {string} A promise that resolves with the result of the upsert operation after the command is executed.
      */
-    upsert: <TMetadata extends Dict = TIndexMetadata>(args: {
+    upsert: <TMetadata extends Dict = TIndexMetadata>(args: ({
         id: string | number;
-        vector: number[];
         metadata?: (TMetadata extends infer U ? U : never) | undefined;
+    } & ({
+        vector: number[];
+        sparseVector?: undefined;
+    } | {
+        vector?: undefined;
+        sparseVector: SparseVector;
     } | {
+        vector: number[];
+        sparseVector: SparseVector;
+    })) | {
         id: string | number;
         data: string;
         metadata?: (TMetadata extends infer U ? U : never) | undefined;
-    } | {
+    } | ({
         id: string | number;
-        vector: number[];
         metadata?: (TMetadata extends infer U ? U : never) | undefined;
-    }[] | {
+    } & ({
+        vector: number[];
+        sparseVector?: undefined;
+    } | {
+        vector?: undefined;
+        sparseVector: SparseVector;
+    } | {
+        vector: number[];
+        sparseVector: SparseVector;
+    }))[] | {
         id: string | number;
         data: string;
         metadata?: (TMetadata extends infer U ? U : never) | undefined;
     }[]) => Promise<string>;
-    update: <TMetadata extends Dict = TIndexMetadata>(args: {
+    update: <TMetadata extends Dict = TIndexMetadata>(args: ({
         id: string | number;
+    } & ({
+        vector?: undefined;
+        sparseVector: SparseVector;
+    } | {
         vector: number[];
+        sparseVector?: undefined;
     } | {
+        vector: number[];
+        sparseVector: SparseVector;
+    })) | {
         id: string | number;
         data: string;
     } | {
@@ -480,29 +628,53 @@ declare class Index<TIndexMetadata extends Dict = Dict> {
      *
      * @returns {string} A promise that resolves with the result of the upsert operation after the command is executed.
      */
-    upsert: <TMetadata extends Dict = TIndexMetadata>(args: {
+    upsert: <TMetadata extends Dict = TIndexMetadata>(args: ({
         id: string | number;
-        vector: number[];
         metadata?: (TMetadata extends infer U ? U : never) | undefined;
+    } & ({
+        vector: number[];
+        sparseVector?: undefined;
     } | {
+        vector?: undefined;
+        sparseVector: SparseVector;
+    } | {
+        vector: number[];
+        sparseVector: SparseVector;
+    })) | {
         id: string | number;
         data: string;
         metadata?: (TMetadata extends infer U ? U : never) | undefined;
-    } | {
+    } | ({
         id: string | number;
-        vector: number[];
         metadata?: (TMetadata extends infer U ? U : never) | undefined;
-    }[] | {
+    } & ({
+        vector: number[];
+        sparseVector?: undefined;
+    } | {
+        vector?: undefined;
+        sparseVector: SparseVector;
+    } | {
+        vector: number[];
+        sparseVector: SparseVector;
+    }))[] | {
         id: string | number;
         data: string;
         metadata?: (TMetadata extends infer U ? U : never) | undefined;
     }[], options?: {
         namespace?: string;
     }) => Promise<string>;
-    update: <TMetadata extends Dict = TIndexMetadata>(args: {
+    update: <TMetadata extends Dict = TIndexMetadata>(args: ({
         id: string | number;
+    } & ({
+        vector?: undefined;
+        sparseVector: SparseVector;
+    } | {
         vector: number[];
+        sparseVector?: undefined;
     } | {
+        vector: number[];
+        sparseVector: SparseVector;
+    })) | {
         id: string | number;
         data: string;
     } | {
@@ -642,4 +814,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.2.0-canary", "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-1", "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" } }