@vectorstores/upstash 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) vectorstores contributors 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/dist/index.cjs

@@ -0,0 +1,181 @@
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var core = require('@vectorstores/core');
+var vector = require('@upstash/vector');
+var env = require('@vectorstores/env');
+
+/**
+ * Provides support for writing and querying vector data in Upstash.
+ */ class UpstashVectorStore extends core.BaseVectorStore {
+    /**
+   * @param namespace namespace to use
+   * @param token upstash vector token. if not set, `process.env.UPSTASH_VECTOR_REST_TOKEN` is used.
+   * @param endpoint upstash vector endpoint. If not set, `process.env.UPSTASH_VECTOR_REST_URL` is used.
+   * @param maxBatchSize maximum number of vectors upserted at once. Default is 1000.
+   *
+   * @example
+   * ```ts
+   * const vectorStore = new UpstashVectorStore({ namespace: "my-namespace" })
+   * ```
+   */ constructor(params){
+        super(params), this.storesText = true;
+        this.namespace = params?.namespace ?? "";
+        this.maxBatchSize = params?.maxBatchSize ?? 1000;
+        const token = params?.token ?? env.getEnv("UPSTASH_VECTOR_REST_TOKEN");
+        const endpoint = params?.endpoint ?? env.getEnv("UPSTASH_VECTOR_REST_URL");
+        if (!token) {
+            throw new Error("Must specify UPSTASH_VECTOR_REST_TOKEN via env variable.");
+        }
+        if (!endpoint) {
+            throw new Error("Must specify UPSTASH_VECTOR_REST_URL via env variable.");
+        }
+        this.db = new vector.Index({
+            token,
+            url: endpoint
+        });
+    }
+    async getDb() {
+        if (!this.db) {
+            const { Index } = await import('@upstash/vector');
+            this.db = new Index();
+        }
+        return this.db;
+    }
+    /**
+   * Connects to the database specified in environment vars.
+   * @returns A connection to the database, or the error encountered while connecting/setting up.
+   */ client() {
+        return this.getDb();
+    }
+    /**
+   * Adds vector record(s) to the table.
+   * @param embeddingResults The Nodes to be inserted, optionally including metadata tuples.
+   * @returns ids of the embeddings (infered from the id_ field of embeddingResults objects)
+   */ async add(embeddingResults) {
+        if (embeddingResults.length == 0) {
+            return [];
+        }
+        const nodes = embeddingResults.map(this.nodeToRecord);
+        const result = await this.upsertInBatches(nodes);
+        if (result != "OK") {
+            throw new Error("Failed to save chunk");
+        }
+        return nodes.map((node)=>node.id).filter((id)=>!!id);
+    }
+    /**
+   * Adds plain text record(s) to the table. Upstash take cares of embedding conversion.
+   * @param text The Nodes to be inserted, optionally including metadata tuples.
+   * @returns ids of the embeddings (infered from the id_ field of embeddingResults objects)
+   */ async addPlainText(text) {
+        if (text.length == 0) {
+            return [];
+        }
+        const nodes = text.map(this.textNodeToRecord);
+        const result = await this.upsertInBatches(nodes);
+        if (result != "OK") {
+            throw new Error("Failed to save chunk");
+        }
+        return nodes.map((node)=>node.id).filter((id)=>!!id);
+    }
+    async upsertInBatches(nodes) {
+        const promises = [];
+        for(let i = 0; i < nodes.length; i += this.maxBatchSize){
+            const batch = nodes.slice(i, i + this.maxBatchSize);
+            promises.push(this.db.upsert(batch, {
+                namespace: this.namespace
+            }));
+        }
+        const results = await Promise.all(promises);
+        return results.every((result)=>result === "OK") ? "OK" : "NOT-OK";
+    }
+    /**
+   * Deletes a single record from the database by id.
+   * NOTE: Uses the collection property controlled by setCollection/getCollection.
+   * @param refDocId Unique identifier for the record to delete.
+   * @returns Promise that resolves if the delete query did not throw an error.
+   */ async delete(refDocId) {
+        await this.db.namespace(this.namespace).delete(refDocId);
+    }
+    /**
+   * Deletes a single record from the database by id.
+   * NOTE: Uses the collection property controlled by setCollection/getCollection.
+   * @param refDocId Unique identifier for the record to delete.
+   * @param deleteKwargs Required by VectorStore interface.  Currently ignored.
+   * @returns Promise that resolves if the delete query did not throw an error.
+   */ async deleteMany(refDocId) {
+        await this.db.namespace(this.namespace).delete(refDocId);
+    }
+    /**
+   * Query the vector store for the closest matching data to the query embeddings
+   * @param query The VectorStoreQuery to be used
+   * @param options Required by VectorStore interface.  Currently ignored.
+   * @returns Zero or more Document instances with data from the vector store.
+   */ async query(query, _options) {
+        const filter = this.toUpstashFilter(query.filters);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const defaultOptions = {
+            vector: query.queryEmbedding,
+            topK: query.similarityTopK,
+            includeVectors: true,
+            includeMetadata: true,
+            filter
+        };
+        const db = this.db;
+        const results = await db.query(defaultOptions, {
+            namespace: this.namespace
+        });
+        const nodes = results.map((result)=>{
+            const node = core.metadataDictToNode(result.metadata ?? {}, {
+                fallback: {
+                    id: result.id,
+                    metadata: result.metadata,
+                    embedding: result.vector
+                }
+            });
+            return node;
+        });
+        const ret = {
+            nodes: nodes,
+            similarities: results.map((row)=>row.score || 999),
+            ids: results.map((row)=>String(row.id))
+        };
+        return ret;
+    }
+    toFilterString(filter) {
+        return `${filter.key} ${filter.operator} ${filter.value}`;
+    }
+    toUpstashFilter(stdFilters) {
+        if (!stdFilters?.filters) return;
+        for (const item of stdFilters.filters){
+            if (item.operator === "==") {
+                //@ts-expect-error Upstash equal operator uses only one equal sign, so we have to replace it.
+                item.operator = "=";
+            }
+        }
+        const filterStrings = stdFilters.filters.map(this.toFilterString);
+        if (filterStrings.length === 1) {
+            return filterStrings[0];
+        }
+        return filterStrings.join(` ${stdFilters.condition ?? "and"} `);
+    }
+    nodeToRecord(node) {
+        const id = node.id_.length ? node.id_ : null;
+        return {
+            // fixme: why id is possibly null?
+            id: id,
+            vector: node.getEmbedding(),
+            metadata: core.nodeToMetadata(node)
+        };
+    }
+    textNodeToRecord(node) {
+        const id = node.id_.length ? node.id_ : null;
+        return {
+            // fixme: why id is possibly null?
+            id: id,
+            data: node.text,
+            metadata: core.nodeToMetadata(node)
+        };
+    }
+}
+
+exports.UpstashVectorStore = UpstashVectorStore;

package/dist/index.d.cts

@@ -0,0 +1,85 @@
+import { BaseVectorStore, VectorStoreBaseParams, BaseNode, Metadata, TextNode, VectorStoreQuery, VectorStoreQueryResult, MetadataFilter, MetadataFilters } from '@vectorstores/core';
+import { Index } from '@upstash/vector';
+
+type UpstashParams = {
+    namespace?: string;
+    token?: string;
+    endpoint?: string;
+    maxBatchSize?: number;
+} & VectorStoreBaseParams;
+/**
+ * Provides support for writing and querying vector data in Upstash.
+ */
+declare class UpstashVectorStore extends BaseVectorStore {
+    storesText: boolean;
+    private db;
+    private maxBatchSize;
+    namespace: string;
+    /**
+     * @param namespace namespace to use
+     * @param token upstash vector token. if not set, `process.env.UPSTASH_VECTOR_REST_TOKEN` is used.
+     * @param endpoint upstash vector endpoint. If not set, `process.env.UPSTASH_VECTOR_REST_URL` is used.
+     * @param maxBatchSize maximum number of vectors upserted at once. Default is 1000.
+     *
+     * @example
+     * ```ts
+     * const vectorStore = new UpstashVectorStore({ namespace: "my-namespace" })
+     * ```
+     */
+    constructor(params?: UpstashParams);
+    private getDb;
+    /**
+     * Connects to the database specified in environment vars.
+     * @returns A connection to the database, or the error encountered while connecting/setting up.
+     */
+    client(): Promise<Index>;
+    /**
+     * Adds vector record(s) to the table.
+     * @param embeddingResults The Nodes to be inserted, optionally including metadata tuples.
+     * @returns ids of the embeddings (infered from the id_ field of embeddingResults objects)
+     */
+    add(embeddingResults: BaseNode<Metadata>[]): Promise<string[]>;
+    /**
+     * Adds plain text record(s) to the table. Upstash take cares of embedding conversion.
+     * @param text The Nodes to be inserted, optionally including metadata tuples.
+     * @returns ids of the embeddings (infered from the id_ field of embeddingResults objects)
+     */
+    addPlainText(text: TextNode<Metadata>[]): Promise<string[]>;
+    private upsertInBatches;
+    /**
+     * Deletes a single record from the database by id.
+     * NOTE: Uses the collection property controlled by setCollection/getCollection.
+     * @param refDocId Unique identifier for the record to delete.
+     * @returns Promise that resolves if the delete query did not throw an error.
+     */
+    delete(refDocId: string): Promise<void>;
+    /**
+     * Deletes a single record from the database by id.
+     * NOTE: Uses the collection property controlled by setCollection/getCollection.
+     * @param refDocId Unique identifier for the record to delete.
+     * @param deleteKwargs Required by VectorStore interface.  Currently ignored.
+     * @returns Promise that resolves if the delete query did not throw an error.
+     */
+    deleteMany(refDocId: string[]): Promise<void>;
+    /**
+     * Query the vector store for the closest matching data to the query embeddings
+     * @param query The VectorStoreQuery to be used
+     * @param options Required by VectorStore interface.  Currently ignored.
+     * @returns Zero or more Document instances with data from the vector store.
+     */
+    query(query: VectorStoreQuery, _options?: object): Promise<VectorStoreQueryResult>;
+    toFilterString(filter: MetadataFilter): string;
+    toUpstashFilter(stdFilters?: MetadataFilters): string | undefined;
+    nodeToRecord(node: BaseNode<Metadata>): {
+        id: string;
+        vector: number[];
+        metadata: Metadata;
+    };
+    textNodeToRecord(node: TextNode<Metadata>): {
+        id: string;
+        data: string;
+        metadata: Metadata;
+    };
+}
+
+export { UpstashVectorStore };

package/dist/index.d.ts

@@ -0,0 +1,85 @@
+import { BaseVectorStore, VectorStoreBaseParams, BaseNode, Metadata, TextNode, VectorStoreQuery, VectorStoreQueryResult, MetadataFilter, MetadataFilters } from '@vectorstores/core';
+import { Index } from '@upstash/vector';
+
+type UpstashParams = {
+    namespace?: string;
+    token?: string;
+    endpoint?: string;
+    maxBatchSize?: number;
+} & VectorStoreBaseParams;
+/**
+ * Provides support for writing and querying vector data in Upstash.
+ */
+declare class UpstashVectorStore extends BaseVectorStore {
+    storesText: boolean;
+    private db;
+    private maxBatchSize;
+    namespace: string;
+    /**
+     * @param namespace namespace to use
+     * @param token upstash vector token. if not set, `process.env.UPSTASH_VECTOR_REST_TOKEN` is used.
+     * @param endpoint upstash vector endpoint. If not set, `process.env.UPSTASH_VECTOR_REST_URL` is used.
+     * @param maxBatchSize maximum number of vectors upserted at once. Default is 1000.
+     *
+     * @example
+     * ```ts
+     * const vectorStore = new UpstashVectorStore({ namespace: "my-namespace" })
+     * ```
+     */
+    constructor(params?: UpstashParams);
+    private getDb;
+    /**
+     * Connects to the database specified in environment vars.
+     * @returns A connection to the database, or the error encountered while connecting/setting up.
+     */
+    client(): Promise<Index>;
+    /**
+     * Adds vector record(s) to the table.
+     * @param embeddingResults The Nodes to be inserted, optionally including metadata tuples.
+     * @returns ids of the embeddings (infered from the id_ field of embeddingResults objects)
+     */
+    add(embeddingResults: BaseNode<Metadata>[]): Promise<string[]>;
+    /**
+     * Adds plain text record(s) to the table. Upstash take cares of embedding conversion.
+     * @param text The Nodes to be inserted, optionally including metadata tuples.
+     * @returns ids of the embeddings (infered from the id_ field of embeddingResults objects)
+     */
+    addPlainText(text: TextNode<Metadata>[]): Promise<string[]>;
+    private upsertInBatches;
+    /**
+     * Deletes a single record from the database by id.
+     * NOTE: Uses the collection property controlled by setCollection/getCollection.
+     * @param refDocId Unique identifier for the record to delete.
+     * @returns Promise that resolves if the delete query did not throw an error.
+     */
+    delete(refDocId: string): Promise<void>;
+    /**
+     * Deletes a single record from the database by id.
+     * NOTE: Uses the collection property controlled by setCollection/getCollection.
+     * @param refDocId Unique identifier for the record to delete.
+     * @param deleteKwargs Required by VectorStore interface.  Currently ignored.
+     * @returns Promise that resolves if the delete query did not throw an error.
+     */
+    deleteMany(refDocId: string[]): Promise<void>;
+    /**
+     * Query the vector store for the closest matching data to the query embeddings
+     * @param query The VectorStoreQuery to be used
+     * @param options Required by VectorStore interface.  Currently ignored.
+     * @returns Zero or more Document instances with data from the vector store.
+     */
+    query(query: VectorStoreQuery, _options?: object): Promise<VectorStoreQueryResult>;
+    toFilterString(filter: MetadataFilter): string;
+    toUpstashFilter(stdFilters?: MetadataFilters): string | undefined;
+    nodeToRecord(node: BaseNode<Metadata>): {
+        id: string;
+        vector: number[];
+        metadata: Metadata;
+    };
+    textNodeToRecord(node: TextNode<Metadata>): {
+        id: string;
+        data: string;
+        metadata: Metadata;
+    };
+}
+
+export { UpstashVectorStore };

package/dist/index.edge-light.d.ts

@@ -0,0 +1,85 @@
+import { BaseVectorStore, VectorStoreBaseParams, BaseNode, Metadata, TextNode, VectorStoreQuery, VectorStoreQueryResult, MetadataFilter, MetadataFilters } from '@vectorstores/core';
+import { Index } from '@upstash/vector';
+
+type UpstashParams = {
+    namespace?: string;
+    token?: string;
+    endpoint?: string;
+    maxBatchSize?: number;
+} & VectorStoreBaseParams;
+/**
+ * Provides support for writing and querying vector data in Upstash.
+ */
+declare class UpstashVectorStore extends BaseVectorStore {
+    storesText: boolean;
+    private db;
+    private maxBatchSize;
+    namespace: string;
+    /**
+     * @param namespace namespace to use
+     * @param token upstash vector token. if not set, `process.env.UPSTASH_VECTOR_REST_TOKEN` is used.
+     * @param endpoint upstash vector endpoint. If not set, `process.env.UPSTASH_VECTOR_REST_URL` is used.
+     * @param maxBatchSize maximum number of vectors upserted at once. Default is 1000.
+     *
+     * @example
+     * ```ts
+     * const vectorStore = new UpstashVectorStore({ namespace: "my-namespace" })
+     * ```
+     */
+    constructor(params?: UpstashParams);
+    private getDb;
+    /**
+     * Connects to the database specified in environment vars.
+     * @returns A connection to the database, or the error encountered while connecting/setting up.
+     */
+    client(): Promise<Index>;
+    /**
+     * Adds vector record(s) to the table.
+     * @param embeddingResults The Nodes to be inserted, optionally including metadata tuples.
+     * @returns ids of the embeddings (infered from the id_ field of embeddingResults objects)
+     */
+    add(embeddingResults: BaseNode<Metadata>[]): Promise<string[]>;
+    /**
+     * Adds plain text record(s) to the table. Upstash take cares of embedding conversion.
+     * @param text The Nodes to be inserted, optionally including metadata tuples.
+     * @returns ids of the embeddings (infered from the id_ field of embeddingResults objects)
+     */
+    addPlainText(text: TextNode<Metadata>[]): Promise<string[]>;
+    private upsertInBatches;
+    /**
+     * Deletes a single record from the database by id.
+     * NOTE: Uses the collection property controlled by setCollection/getCollection.
+     * @param refDocId Unique identifier for the record to delete.
+     * @returns Promise that resolves if the delete query did not throw an error.
+     */
+    delete(refDocId: string): Promise<void>;
+    /**
+     * Deletes a single record from the database by id.
+     * NOTE: Uses the collection property controlled by setCollection/getCollection.
+     * @param refDocId Unique identifier for the record to delete.
+     * @param deleteKwargs Required by VectorStore interface.  Currently ignored.
+     * @returns Promise that resolves if the delete query did not throw an error.
+     */
+    deleteMany(refDocId: string[]): Promise<void>;
+    /**
+     * Query the vector store for the closest matching data to the query embeddings
+     * @param query The VectorStoreQuery to be used
+     * @param options Required by VectorStore interface.  Currently ignored.
+     * @returns Zero or more Document instances with data from the vector store.
+     */
+    query(query: VectorStoreQuery, _options?: object): Promise<VectorStoreQueryResult>;
+    toFilterString(filter: MetadataFilter): string;
+    toUpstashFilter(stdFilters?: MetadataFilters): string | undefined;
+    nodeToRecord(node: BaseNode<Metadata>): {
+        id: string;
+        vector: number[];
+        metadata: Metadata;
+    };
+    textNodeToRecord(node: TextNode<Metadata>): {
+        id: string;
+        data: string;
+        metadata: Metadata;
+    };
+}
+
+export { UpstashVectorStore };

package/dist/index.edge-light.js

@@ -0,0 +1,179 @@
+import { BaseVectorStore, metadataDictToNode, nodeToMetadata } from '@vectorstores/core';
+import { Index } from '@upstash/vector';
+import { getEnv } from '@vectorstores/env';
+
+/**
+ * Provides support for writing and querying vector data in Upstash.
+ */ class UpstashVectorStore extends BaseVectorStore {
+    /**
+   * @param namespace namespace to use
+   * @param token upstash vector token. if not set, `process.env.UPSTASH_VECTOR_REST_TOKEN` is used.
+   * @param endpoint upstash vector endpoint. If not set, `process.env.UPSTASH_VECTOR_REST_URL` is used.
+   * @param maxBatchSize maximum number of vectors upserted at once. Default is 1000.
+   *
+   * @example
+   * ```ts
+   * const vectorStore = new UpstashVectorStore({ namespace: "my-namespace" })
+   * ```
+   */ constructor(params){
+        super(params), this.storesText = true;
+        this.namespace = params?.namespace ?? "";
+        this.maxBatchSize = params?.maxBatchSize ?? 1000;
+        const token = params?.token ?? getEnv("UPSTASH_VECTOR_REST_TOKEN");
+        const endpoint = params?.endpoint ?? getEnv("UPSTASH_VECTOR_REST_URL");
+        if (!token) {
+            throw new Error("Must specify UPSTASH_VECTOR_REST_TOKEN via env variable.");
+        }
+        if (!endpoint) {
+            throw new Error("Must specify UPSTASH_VECTOR_REST_URL via env variable.");
+        }
+        this.db = new Index({
+            token,
+            url: endpoint
+        });
+    }
+    async getDb() {
+        if (!this.db) {
+            const { Index } = await import('@upstash/vector');
+            this.db = new Index();
+        }
+        return this.db;
+    }
+    /**
+   * Connects to the database specified in environment vars.
+   * @returns A connection to the database, or the error encountered while connecting/setting up.
+   */ client() {
+        return this.getDb();
+    }
+    /**
+   * Adds vector record(s) to the table.
+   * @param embeddingResults The Nodes to be inserted, optionally including metadata tuples.
+   * @returns ids of the embeddings (infered from the id_ field of embeddingResults objects)
+   */ async add(embeddingResults) {
+        if (embeddingResults.length == 0) {
+            return [];
+        }
+        const nodes = embeddingResults.map(this.nodeToRecord);
+        const result = await this.upsertInBatches(nodes);
+        if (result != "OK") {
+            throw new Error("Failed to save chunk");
+        }
+        return nodes.map((node)=>node.id).filter((id)=>!!id);
+    }
+    /**
+   * Adds plain text record(s) to the table. Upstash take cares of embedding conversion.
+   * @param text The Nodes to be inserted, optionally including metadata tuples.
+   * @returns ids of the embeddings (infered from the id_ field of embeddingResults objects)
+   */ async addPlainText(text) {
+        if (text.length == 0) {
+            return [];
+        }
+        const nodes = text.map(this.textNodeToRecord);
+        const result = await this.upsertInBatches(nodes);
+        if (result != "OK") {
+            throw new Error("Failed to save chunk");
+        }
+        return nodes.map((node)=>node.id).filter((id)=>!!id);
+    }
+    async upsertInBatches(nodes) {
+        const promises = [];
+        for(let i = 0; i < nodes.length; i += this.maxBatchSize){
+            const batch = nodes.slice(i, i + this.maxBatchSize);
+            promises.push(this.db.upsert(batch, {
+                namespace: this.namespace
+            }));
+        }
+        const results = await Promise.all(promises);
+        return results.every((result)=>result === "OK") ? "OK" : "NOT-OK";
+    }
+    /**
+   * Deletes a single record from the database by id.
+   * NOTE: Uses the collection property controlled by setCollection/getCollection.
+   * @param refDocId Unique identifier for the record to delete.
+   * @returns Promise that resolves if the delete query did not throw an error.
+   */ async delete(refDocId) {
+        await this.db.namespace(this.namespace).delete(refDocId);
+    }
+    /**
+   * Deletes a single record from the database by id.
+   * NOTE: Uses the collection property controlled by setCollection/getCollection.
+   * @param refDocId Unique identifier for the record to delete.
+   * @param deleteKwargs Required by VectorStore interface.  Currently ignored.
+   * @returns Promise that resolves if the delete query did not throw an error.
+   */ async deleteMany(refDocId) {
+        await this.db.namespace(this.namespace).delete(refDocId);
+    }
+    /**
+   * Query the vector store for the closest matching data to the query embeddings
+   * @param query The VectorStoreQuery to be used
+   * @param options Required by VectorStore interface.  Currently ignored.
+   * @returns Zero or more Document instances with data from the vector store.
+   */ async query(query, _options) {
+        const filter = this.toUpstashFilter(query.filters);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const defaultOptions = {
+            vector: query.queryEmbedding,
+            topK: query.similarityTopK,
+            includeVectors: true,
+            includeMetadata: true,
+            filter
+        };
+        const db = this.db;
+        const results = await db.query(defaultOptions, {
+            namespace: this.namespace
+        });
+        const nodes = results.map((result)=>{
+            const node = metadataDictToNode(result.metadata ?? {}, {
+                fallback: {
+                    id: result.id,
+                    metadata: result.metadata,
+                    embedding: result.vector
+                }
+            });
+            return node;
+        });
+        const ret = {
+            nodes: nodes,
+            similarities: results.map((row)=>row.score || 999),
+            ids: results.map((row)=>String(row.id))
+        };
+        return ret;
+    }
+    toFilterString(filter) {
+        return `${filter.key} ${filter.operator} ${filter.value}`;
+    }
+    toUpstashFilter(stdFilters) {
+        if (!stdFilters?.filters) return;
+        for (const item of stdFilters.filters){
+            if (item.operator === "==") {
+                //@ts-expect-error Upstash equal operator uses only one equal sign, so we have to replace it.
+                item.operator = "=";
+            }
+        }
+        const filterStrings = stdFilters.filters.map(this.toFilterString);
+        if (filterStrings.length === 1) {
+            return filterStrings[0];
+        }
+        return filterStrings.join(` ${stdFilters.condition ?? "and"} `);
+    }
+    nodeToRecord(node) {
+        const id = node.id_.length ? node.id_ : null;
+        return {
+            // fixme: why id is possibly null?
+            id: id,
+            vector: node.getEmbedding(),
+            metadata: nodeToMetadata(node)
+        };
+    }
+    textNodeToRecord(node) {
+        const id = node.id_.length ? node.id_ : null;
+        return {
+            // fixme: why id is possibly null?
+            id: id,
+            data: node.text,
+            metadata: nodeToMetadata(node)
+        };
+    }
+}
+
+export { UpstashVectorStore };

package/dist/index.js

@@ -0,0 +1,179 @@
+import { BaseVectorStore, metadataDictToNode, nodeToMetadata } from '@vectorstores/core';
+import { Index } from '@upstash/vector';
+import { getEnv } from '@vectorstores/env';
+
+/**
+ * Provides support for writing and querying vector data in Upstash.
+ */ class UpstashVectorStore extends BaseVectorStore {
+    /**
+   * @param namespace namespace to use
+   * @param token upstash vector token. if not set, `process.env.UPSTASH_VECTOR_REST_TOKEN` is used.
+   * @param endpoint upstash vector endpoint. If not set, `process.env.UPSTASH_VECTOR_REST_URL` is used.
+   * @param maxBatchSize maximum number of vectors upserted at once. Default is 1000.
+   *
+   * @example
+   * ```ts
+   * const vectorStore = new UpstashVectorStore({ namespace: "my-namespace" })
+   * ```
+   */ constructor(params){
+        super(params), this.storesText = true;
+        this.namespace = params?.namespace ?? "";
+        this.maxBatchSize = params?.maxBatchSize ?? 1000;
+        const token = params?.token ?? getEnv("UPSTASH_VECTOR_REST_TOKEN");
+        const endpoint = params?.endpoint ?? getEnv("UPSTASH_VECTOR_REST_URL");
+        if (!token) {
+            throw new Error("Must specify UPSTASH_VECTOR_REST_TOKEN via env variable.");
+        }
+        if (!endpoint) {
+            throw new Error("Must specify UPSTASH_VECTOR_REST_URL via env variable.");
+        }
+        this.db = new Index({
+            token,
+            url: endpoint
+        });
+    }
+    async getDb() {
+        if (!this.db) {
+            const { Index } = await import('@upstash/vector');
+            this.db = new Index();
+        }
+        return this.db;
+    }
+    /**
+   * Connects to the database specified in environment vars.
+   * @returns A connection to the database, or the error encountered while connecting/setting up.
+   */ client() {
+        return this.getDb();
+    }
+    /**
+   * Adds vector record(s) to the table.
+   * @param embeddingResults The Nodes to be inserted, optionally including metadata tuples.
+   * @returns ids of the embeddings (infered from the id_ field of embeddingResults objects)
+   */ async add(embeddingResults) {
+        if (embeddingResults.length == 0) {
+            return [];
+        }
+        const nodes = embeddingResults.map(this.nodeToRecord);
+        const result = await this.upsertInBatches(nodes);
+        if (result != "OK") {
+            throw new Error("Failed to save chunk");
+        }
+        return nodes.map((node)=>node.id).filter((id)=>!!id);
+    }
+    /**
+   * Adds plain text record(s) to the table. Upstash take cares of embedding conversion.
+   * @param text The Nodes to be inserted, optionally including metadata tuples.
+   * @returns ids of the embeddings (infered from the id_ field of embeddingResults objects)
+   */ async addPlainText(text) {
+        if (text.length == 0) {
+            return [];
+        }
+        const nodes = text.map(this.textNodeToRecord);
+        const result = await this.upsertInBatches(nodes);
+        if (result != "OK") {
+            throw new Error("Failed to save chunk");
+        }
+        return nodes.map((node)=>node.id).filter((id)=>!!id);
+    }
+    async upsertInBatches(nodes) {
+        const promises = [];
+        for(let i = 0; i < nodes.length; i += this.maxBatchSize){
+            const batch = nodes.slice(i, i + this.maxBatchSize);
+            promises.push(this.db.upsert(batch, {
+                namespace: this.namespace
+            }));
+        }
+        const results = await Promise.all(promises);
+        return results.every((result)=>result === "OK") ? "OK" : "NOT-OK";
+    }
+    /**
+   * Deletes a single record from the database by id.
+   * NOTE: Uses the collection property controlled by setCollection/getCollection.
+   * @param refDocId Unique identifier for the record to delete.
+   * @returns Promise that resolves if the delete query did not throw an error.
+   */ async delete(refDocId) {
+        await this.db.namespace(this.namespace).delete(refDocId);
+    }
+    /**
+   * Deletes a single record from the database by id.
+   * NOTE: Uses the collection property controlled by setCollection/getCollection.
+   * @param refDocId Unique identifier for the record to delete.
+   * @param deleteKwargs Required by VectorStore interface.  Currently ignored.
+   * @returns Promise that resolves if the delete query did not throw an error.
+   */ async deleteMany(refDocId) {
+        await this.db.namespace(this.namespace).delete(refDocId);
+    }
+    /**
+   * Query the vector store for the closest matching data to the query embeddings
+   * @param query The VectorStoreQuery to be used
+   * @param options Required by VectorStore interface.  Currently ignored.
+   * @returns Zero or more Document instances with data from the vector store.
+   */ async query(query, _options) {
+        const filter = this.toUpstashFilter(query.filters);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const defaultOptions = {
+            vector: query.queryEmbedding,
+            topK: query.similarityTopK,
+            includeVectors: true,
+            includeMetadata: true,
+            filter
+        };
+        const db = this.db;
+        const results = await db.query(defaultOptions, {
+            namespace: this.namespace
+        });
+        const nodes = results.map((result)=>{
+            const node = metadataDictToNode(result.metadata ?? {}, {
+                fallback: {
+                    id: result.id,
+                    metadata: result.metadata,
+                    embedding: result.vector
+                }
+            });
+            return node;
+        });
+        const ret = {
+            nodes: nodes,
+            similarities: results.map((row)=>row.score || 999),
+            ids: results.map((row)=>String(row.id))
+        };
+        return ret;
+    }
+    toFilterString(filter) {
+        return `${filter.key} ${filter.operator} ${filter.value}`;
+    }
+    toUpstashFilter(stdFilters) {
+        if (!stdFilters?.filters) return;
+        for (const item of stdFilters.filters){
+            if (item.operator === "==") {
+                //@ts-expect-error Upstash equal operator uses only one equal sign, so we have to replace it.
+                item.operator = "=";
+            }
+        }
+        const filterStrings = stdFilters.filters.map(this.toFilterString);
+        if (filterStrings.length === 1) {
+            return filterStrings[0];
+        }
+        return filterStrings.join(` ${stdFilters.condition ?? "and"} `);
+    }
+    nodeToRecord(node) {
+        const id = node.id_.length ? node.id_ : null;
+        return {
+            // fixme: why id is possibly null?
+            id: id,
+            vector: node.getEmbedding(),
+            metadata: nodeToMetadata(node)
+        };
+    }
+    textNodeToRecord(node) {
+        const id = node.id_.length ? node.id_ : null;
+        return {
+            // fixme: why id is possibly null?
+            id: id,
+            data: node.text,
+            metadata: nodeToMetadata(node)
+        };
+    }
+}
+
+export { UpstashVectorStore };

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@vectorstores/upstash",
+  "description": "Upstash Storage for vectorstores",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "exports": {
+    ".": {
+      "edge-light": {
+        "types": "./dist/index.edge-light.d.ts",
+        "default": "./dist/index.edge-light.js"
+      },
+      "workerd": {
+        "types": "./dist/index.edge-light.d.ts",
+        "default": "./dist/index.edge-light.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      },
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/schiesser/vectorstores.git",
+    "directory": "packages/providers/storage/upstash"
+  },
+  "devDependencies": {
+    "@vectorstores/core": "0.1.0",
+    "@vectorstores/env": "0.1.0"
+  },
+  "peerDependencies": {
+    "@vectorstores/core": "0.1.0",
+    "@vectorstores/env": "0.1.0"
+  },
+  "dependencies": {
+    "@upstash/vector": "^1.1.5"
+  },
+  "scripts": {
+    "build": "bunchee",
+    "dev": "bunchee --watch"
+  }
+}