@vectorstores/elastic-search 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,266 @@
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var core = require('@vectorstores/core');
+var elasticsearch = require('@elastic/elasticsearch');
+
+function getElasticSearchClient({ esUrl, esCloudId, esApiKey, esUsername, esPassword }) {
+    const clientOptions = {};
+    if (esUrl && esCloudId) {
+        throw new Error("Both esUrl and esCloudId cannot be provided");
+    }
+    if (esUrl) {
+        clientOptions.node = esUrl;
+    } else if (esCloudId) {
+        clientOptions.cloud = {
+            id: esCloudId
+        };
+    } else {
+        throw new Error("Either elasticsearch url or cloud id must be provided");
+    }
+    if (esApiKey) {
+        clientOptions.auth = {
+            apiKey: esApiKey
+        };
+    } else if (esUsername && esPassword) {
+        clientOptions.auth = {
+            username: esUsername,
+            password: esPassword
+        };
+    }
+    return new elasticsearch.Client(clientOptions);
+}
+
+/**
+ * ElasticSearchVectorStore provides vector storage and similarity search capabilities using Elasticsearch.
+ * It extends BaseVectorStore to implement vector storage operations with Elasticsearch as the backend.
+ */ class ElasticSearchVectorStore extends core.BaseVectorStore {
+    /**
+   * Creates a new instance of ElasticSearchVectorStore
+   * @param init - Configuration parameters for Elasticsearch connection and indexing
+   */ constructor(init){
+        super(), this.storesText = true;
+        this.indexName = init.indexName;
+        this.esUrl = init.esUrl ?? undefined;
+        this.esCloudId = init.esCloudId ?? undefined;
+        this.esApiKey = init.esApiKey ?? undefined;
+        this.esUsername = init.esUsername ?? undefined;
+        this.esPassword = init.esPassword ?? undefined;
+        this.textField = init.textField ?? "content";
+        this.vectorField = init.vectorField ?? "embedding";
+        this.distanceStrategy = init.distanceStrategy ?? "cosine";
+        if (!init.esClient) {
+            this.elasticSearchClient = getElasticSearchClient({
+                esUrl: this.esUrl,
+                esCloudId: this.esCloudId,
+                esApiKey: this.esApiKey,
+                esUsername: this.esUsername,
+                esPassword: this.esPassword
+            });
+        } else {
+            this.elasticSearchClient = init.esClient;
+        }
+    }
+    /**
+   * Returns the Elasticsearch client instance
+   * @returns The configured Elasticsearch client
+   */ client() {
+        return this.elasticSearchClient;
+    }
+    /**
+   * Creates an Elasticsearch index if it doesn't exist
+   * @param dimensions - Number of dimensions in the vector embedding
+   * @private
+   */ async createIndexIfNotExists(dimensions) {
+        const indexExists = await this.elasticSearchClient.indices.exists({
+            index: this.indexName
+        });
+        if (!indexExists) {
+            await this.elasticSearchClient.indices.create({
+                index: this.indexName,
+                body: {
+                    mappings: {
+                        properties: {
+                            [this.textField]: {
+                                type: "text"
+                            },
+                            [this.vectorField]: {
+                                type: "dense_vector",
+                                dims: dimensions,
+                                index: true,
+                                similarity: this.distanceStrategy
+                            },
+                            metadata: {
+                                properties: {
+                                    document_id: {
+                                        type: "keyword"
+                                    },
+                                    doc_id: {
+                                        type: "keyword"
+                                    },
+                                    ref_doc_id: {
+                                        type: "keyword"
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            });
+        }
+    }
+    /**
+   * Adds nodes to the vector store
+   * @param nodes - Array of BaseNode objects to store
+   * @returns Array of node IDs that were successfully stored
+   * @throws Error if nodes don't have embeddings
+   */ async add(nodes) {
+        if (!nodes.length) {
+            return [];
+        }
+        const dimensions = nodes[0]?.getEmbedding()?.length;
+        if (!dimensions) {
+            throw new Error("Embedding is required");
+        }
+        await this.createIndexIfNotExists(dimensions);
+        const operations = nodes.flatMap((node)=>[
+                {
+                    index: {
+                        _index: this.indexName,
+                        _id: node.id_
+                    }
+                },
+                {
+                    [this.vectorField]: node.getEmbedding(),
+                    [this.textField]: node.getContent(core.MetadataMode.NONE),
+                    metadata: core.nodeToMetadata(node, true)
+                }
+            ]);
+        const results = await this.elasticSearchClient.bulk({
+            operations,
+            refresh: true
+        });
+        if (results.errors) {
+            const reasons = results.items.map((result)=>result.index?.error?.reason);
+            throw new Error(`Failed to insert documents:\n${reasons.join("\n")}`);
+        }
+        return nodes.map((node)=>node.id_);
+    }
+    /**
+   * Deletes nodes from the vector store by reference document ID
+   * @param refDocId - Reference document ID to delete
+   * @param deleteOptions - Optional deletion parameters
+   */ async delete(refDocId, deleteOptions) {
+        await this.elasticSearchClient.deleteByQuery({
+            index: this.indexName,
+            query: {
+                term: {
+                    "metadata.ref_doc_id": refDocId
+                }
+            },
+            refresh: true
+        });
+    }
+    /**
+   * Converts metadata filters to Elasticsearch query format
+   * @param queryFilters - Metadata filters to convert
+   * @returns Elasticsearch compatible filter object
+   * @private
+   */ toElasticSearchFilter(queryFilters) {
+        if (queryFilters.filters.length === 1) {
+            const filter = queryFilters.filters[0];
+            if (filter) {
+                return {
+                    term: {
+                        [`metadata.${filter.key}`]: filter.value
+                    }
+                };
+            }
+        }
+        return {
+            bool: {
+                must: queryFilters.filters.map((filter)=>({
+                        term: {
+                            [`metadata.${filter.key}`]: filter.value
+                        }
+                    }))
+            }
+        };
+    }
+    /**
+   * Normalizes similarity scores to range [0,1]
+   * @param scores - Array of raw similarity scores
+   * @returns Array of normalized similarity scores
+   * @private
+   */ toLlamaSimilarity(scores) {
+        if (!scores.length) {
+            return [];
+        }
+        const maxScore = Math.max(...scores);
+        const minScore = Math.min(...scores);
+        if (maxScore === minScore) {
+            return scores.map(()=>maxScore > 0 ? 1 : 0);
+        }
+        return scores.map((score)=>(score - minScore) / (maxScore - minScore));
+    }
+    /**
+   * Performs a vector similarity search query
+   * @param query - Vector store query parameters
+   * @param options - Optional query parameters
+   * @returns Query results containing matching nodes, similarities, and IDs
+   * @throws Error if query embedding is not provided
+   */ async query(query, options) {
+        if (!query.queryEmbedding) {
+            throw new Error("query embedding is not provided");
+        }
+        let elasticSearchFilter = [];
+        if (query.filters) {
+            elasticSearchFilter = [
+                this.toElasticSearchFilter(query.filters)
+            ];
+        }
+        const searchResponse = await this.elasticSearchClient.search({
+            index: this.indexName,
+            size: query.similarityTopK,
+            knn: {
+                field: this.vectorField,
+                query_vector: query.queryEmbedding,
+                k: query.similarityTopK,
+                num_candidates: query.similarityTopK * 10,
+                filter: elasticSearchFilter
+            }
+        });
+        return this.getVectorSearchQueryResultFromResponse(searchResponse);
+    }
+    /**
+   * Processes Elasticsearch response into VectorStoreQueryResult format
+   * @param res - Elasticsearch search response
+   * @returns Formatted query results
+   * @private
+   */ getVectorSearchQueryResultFromResponse(res) {
+        const hits = res.hits.hits;
+        const topKNodes = [];
+        const topKIDs = [];
+        const topKScores = [];
+        for (const hit of hits){
+            const source = hit._source;
+            const metadata = source?.metadata ?? {};
+            const text = source?.[this.textField] ?? "";
+            const embedding = source?.[this.vectorField] ?? [];
+            const nodeId = hit._id ?? "";
+            const score = hit._score ?? 0;
+            const node = core.metadataDictToNode(metadata);
+            node.setContent(text);
+            node.embedding = embedding;
+            topKNodes.push(node);
+            topKIDs.push(nodeId);
+            topKScores.push(score);
+        }
+        return {
+            nodes: topKNodes,
+            similarities: this.toLlamaSimilarity(topKScores),
+            ids: topKIDs
+        };
+    }
+}
+
+exports.ElasticSearchVectorStore = ElasticSearchVectorStore;

package/dist/index.d.cts

@@ -0,0 +1,97 @@
+import { Client } from '@elastic/elasticsearch';
+import { BaseVectorStore, BaseNode, VectorStoreQuery, VectorStoreQueryResult } from '@vectorstores/core';
+
+type ElasticSearchParams = {
+    indexName: string;
+    esClient?: Client;
+    esUrl?: string;
+    esCloudId?: string;
+    esApiKey?: string;
+    esUsername?: string;
+    esPassword?: string;
+    textField?: string;
+    vectorField?: string;
+    distanceStrategy?: DISTANCE_STARTEGIES;
+};
+declare enum DISTANCE_STARTEGIES {
+    COSINE = "cosine",
+    EUCLIDEAN = "euclidean",
+    MANHATTAN = "manhattan"
+}
+/**
+ * ElasticSearchVectorStore provides vector storage and similarity search capabilities using Elasticsearch.
+ * It extends BaseVectorStore to implement vector storage operations with Elasticsearch as the backend.
+ */
+declare class ElasticSearchVectorStore extends BaseVectorStore {
+    storesText: boolean;
+    private elasticSearchClient;
+    private indexName;
+    private esUrl?;
+    private esCloudId?;
+    private esApiKey?;
+    private esUsername?;
+    private esPassword?;
+    private textField;
+    private vectorField;
+    private distanceStrategy;
+    /**
+     * Creates a new instance of ElasticSearchVectorStore
+     * @param init - Configuration parameters for Elasticsearch connection and indexing
+     */
+    constructor(init: ElasticSearchParams);
+    /**
+     * Returns the Elasticsearch client instance
+     * @returns The configured Elasticsearch client
+     */
+    client(): Client;
+    /**
+     * Creates an Elasticsearch index if it doesn't exist
+     * @param dimensions - Number of dimensions in the vector embedding
+     * @private
+     */
+    private createIndexIfNotExists;
+    /**
+     * Adds nodes to the vector store
+     * @param nodes - Array of BaseNode objects to store
+     * @returns Array of node IDs that were successfully stored
+     * @throws Error if nodes don't have embeddings
+     */
+    add(nodes: BaseNode[]): Promise<string[]>;
+    /**
+     * Deletes nodes from the vector store by reference document ID
+     * @param refDocId - Reference document ID to delete
+     * @param deleteOptions - Optional deletion parameters
+     */
+    delete(refDocId: string, deleteOptions?: object): Promise<void>;
+    /**
+     * Converts metadata filters to Elasticsearch query format
+     * @param queryFilters - Metadata filters to convert
+     * @returns Elasticsearch compatible filter object
+     * @private
+     */
+    private toElasticSearchFilter;
+    /**
+     * Normalizes similarity scores to range [0,1]
+     * @param scores - Array of raw similarity scores
+     * @returns Array of normalized similarity scores
+     * @private
+     */
+    private toLlamaSimilarity;
+    /**
+     * Performs a vector similarity search query
+     * @param query - Vector store query parameters
+     * @param options - Optional query parameters
+     * @returns Query results containing matching nodes, similarities, and IDs
+     * @throws Error if query embedding is not provided
+     */
+    query(query: VectorStoreQuery, options?: object): Promise<VectorStoreQueryResult>;
+    /**
+     * Processes Elasticsearch response into VectorStoreQueryResult format
+     * @param res - Elasticsearch search response
+     * @returns Formatted query results
+     * @private
+     */
+    private getVectorSearchQueryResultFromResponse;
+}
+
+export { ElasticSearchVectorStore };

package/dist/index.d.ts

@@ -0,0 +1,97 @@
+import { Client } from '@elastic/elasticsearch';
+import { BaseVectorStore, BaseNode, VectorStoreQuery, VectorStoreQueryResult } from '@vectorstores/core';
+
+type ElasticSearchParams = {
+    indexName: string;
+    esClient?: Client;
+    esUrl?: string;
+    esCloudId?: string;
+    esApiKey?: string;
+    esUsername?: string;
+    esPassword?: string;
+    textField?: string;
+    vectorField?: string;
+    distanceStrategy?: DISTANCE_STARTEGIES;
+};
+declare enum DISTANCE_STARTEGIES {
+    COSINE = "cosine",
+    EUCLIDEAN = "euclidean",
+    MANHATTAN = "manhattan"
+}
+/**
+ * ElasticSearchVectorStore provides vector storage and similarity search capabilities using Elasticsearch.
+ * It extends BaseVectorStore to implement vector storage operations with Elasticsearch as the backend.
+ */
+declare class ElasticSearchVectorStore extends BaseVectorStore {
+    storesText: boolean;
+    private elasticSearchClient;
+    private indexName;
+    private esUrl?;
+    private esCloudId?;
+    private esApiKey?;
+    private esUsername?;
+    private esPassword?;
+    private textField;
+    private vectorField;
+    private distanceStrategy;
+    /**
+     * Creates a new instance of ElasticSearchVectorStore
+     * @param init - Configuration parameters for Elasticsearch connection and indexing
+     */
+    constructor(init: ElasticSearchParams);
+    /**
+     * Returns the Elasticsearch client instance
+     * @returns The configured Elasticsearch client
+     */
+    client(): Client;
+    /**
+     * Creates an Elasticsearch index if it doesn't exist
+     * @param dimensions - Number of dimensions in the vector embedding
+     * @private
+     */
+    private createIndexIfNotExists;
+    /**
+     * Adds nodes to the vector store
+     * @param nodes - Array of BaseNode objects to store
+     * @returns Array of node IDs that were successfully stored
+     * @throws Error if nodes don't have embeddings
+     */
+    add(nodes: BaseNode[]): Promise<string[]>;
+    /**
+     * Deletes nodes from the vector store by reference document ID
+     * @param refDocId - Reference document ID to delete
+     * @param deleteOptions - Optional deletion parameters
+     */
+    delete(refDocId: string, deleteOptions?: object): Promise<void>;
+    /**
+     * Converts metadata filters to Elasticsearch query format
+     * @param queryFilters - Metadata filters to convert
+     * @returns Elasticsearch compatible filter object
+     * @private
+     */
+    private toElasticSearchFilter;
+    /**
+     * Normalizes similarity scores to range [0,1]
+     * @param scores - Array of raw similarity scores
+     * @returns Array of normalized similarity scores
+     * @private
+     */
+    private toLlamaSimilarity;
+    /**
+     * Performs a vector similarity search query
+     * @param query - Vector store query parameters
+     * @param options - Optional query parameters
+     * @returns Query results containing matching nodes, similarities, and IDs
+     * @throws Error if query embedding is not provided
+     */
+    query(query: VectorStoreQuery, options?: object): Promise<VectorStoreQueryResult>;
+    /**
+     * Processes Elasticsearch response into VectorStoreQueryResult format
+     * @param res - Elasticsearch search response
+     * @returns Formatted query results
+     * @private
+     */
+    private getVectorSearchQueryResultFromResponse;
+}
+
+export { ElasticSearchVectorStore };

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

@@ -0,0 +1,97 @@
+import { Client } from '@elastic/elasticsearch';
+import { BaseVectorStore, BaseNode, VectorStoreQuery, VectorStoreQueryResult } from '@vectorstores/core';
+
+type ElasticSearchParams = {
+    indexName: string;
+    esClient?: Client;
+    esUrl?: string;
+    esCloudId?: string;
+    esApiKey?: string;
+    esUsername?: string;
+    esPassword?: string;
+    textField?: string;
+    vectorField?: string;
+    distanceStrategy?: DISTANCE_STARTEGIES;
+};
+declare enum DISTANCE_STARTEGIES {
+    COSINE = "cosine",
+    EUCLIDEAN = "euclidean",
+    MANHATTAN = "manhattan"
+}
+/**
+ * ElasticSearchVectorStore provides vector storage and similarity search capabilities using Elasticsearch.
+ * It extends BaseVectorStore to implement vector storage operations with Elasticsearch as the backend.
+ */
+declare class ElasticSearchVectorStore extends BaseVectorStore {
+    storesText: boolean;
+    private elasticSearchClient;
+    private indexName;
+    private esUrl?;
+    private esCloudId?;
+    private esApiKey?;
+    private esUsername?;
+    private esPassword?;
+    private textField;
+    private vectorField;
+    private distanceStrategy;
+    /**
+     * Creates a new instance of ElasticSearchVectorStore
+     * @param init - Configuration parameters for Elasticsearch connection and indexing
+     */
+    constructor(init: ElasticSearchParams);
+    /**
+     * Returns the Elasticsearch client instance
+     * @returns The configured Elasticsearch client
+     */
+    client(): Client;
+    /**
+     * Creates an Elasticsearch index if it doesn't exist
+     * @param dimensions - Number of dimensions in the vector embedding
+     * @private
+     */
+    private createIndexIfNotExists;
+    /**
+     * Adds nodes to the vector store
+     * @param nodes - Array of BaseNode objects to store
+     * @returns Array of node IDs that were successfully stored
+     * @throws Error if nodes don't have embeddings
+     */
+    add(nodes: BaseNode[]): Promise<string[]>;
+    /**
+     * Deletes nodes from the vector store by reference document ID
+     * @param refDocId - Reference document ID to delete
+     * @param deleteOptions - Optional deletion parameters
+     */
+    delete(refDocId: string, deleteOptions?: object): Promise<void>;
+    /**
+     * Converts metadata filters to Elasticsearch query format
+     * @param queryFilters - Metadata filters to convert
+     * @returns Elasticsearch compatible filter object
+     * @private
+     */
+    private toElasticSearchFilter;
+    /**
+     * Normalizes similarity scores to range [0,1]
+     * @param scores - Array of raw similarity scores
+     * @returns Array of normalized similarity scores
+     * @private
+     */
+    private toLlamaSimilarity;
+    /**
+     * Performs a vector similarity search query
+     * @param query - Vector store query parameters
+     * @param options - Optional query parameters
+     * @returns Query results containing matching nodes, similarities, and IDs
+     * @throws Error if query embedding is not provided
+     */
+    query(query: VectorStoreQuery, options?: object): Promise<VectorStoreQueryResult>;
+    /**
+     * Processes Elasticsearch response into VectorStoreQueryResult format
+     * @param res - Elasticsearch search response
+     * @returns Formatted query results
+     * @private
+     */
+    private getVectorSearchQueryResultFromResponse;
+}
+
+export { ElasticSearchVectorStore };

package/dist/index.edge-light.js

@@ -0,0 +1,264 @@
+import { BaseVectorStore, nodeToMetadata, MetadataMode, metadataDictToNode } from '@vectorstores/core';
+import { Client } from '@elastic/elasticsearch';
+
+function getElasticSearchClient({ esUrl, esCloudId, esApiKey, esUsername, esPassword }) {
+    const clientOptions = {};
+    if (esUrl && esCloudId) {
+        throw new Error("Both esUrl and esCloudId cannot be provided");
+    }
+    if (esUrl) {
+        clientOptions.node = esUrl;
+    } else if (esCloudId) {
+        clientOptions.cloud = {
+            id: esCloudId
+        };
+    } else {
+        throw new Error("Either elasticsearch url or cloud id must be provided");
+    }
+    if (esApiKey) {
+        clientOptions.auth = {
+            apiKey: esApiKey
+        };
+    } else if (esUsername && esPassword) {
+        clientOptions.auth = {
+            username: esUsername,
+            password: esPassword
+        };
+    }
+    return new Client(clientOptions);
+}
+
+/**
+ * ElasticSearchVectorStore provides vector storage and similarity search capabilities using Elasticsearch.
+ * It extends BaseVectorStore to implement vector storage operations with Elasticsearch as the backend.
+ */ class ElasticSearchVectorStore extends BaseVectorStore {
+    /**
+   * Creates a new instance of ElasticSearchVectorStore
+   * @param init - Configuration parameters for Elasticsearch connection and indexing
+   */ constructor(init){
+        super(), this.storesText = true;
+        this.indexName = init.indexName;
+        this.esUrl = init.esUrl ?? undefined;
+        this.esCloudId = init.esCloudId ?? undefined;
+        this.esApiKey = init.esApiKey ?? undefined;
+        this.esUsername = init.esUsername ?? undefined;
+        this.esPassword = init.esPassword ?? undefined;
+        this.textField = init.textField ?? "content";
+        this.vectorField = init.vectorField ?? "embedding";
+        this.distanceStrategy = init.distanceStrategy ?? "cosine";
+        if (!init.esClient) {
+            this.elasticSearchClient = getElasticSearchClient({
+                esUrl: this.esUrl,
+                esCloudId: this.esCloudId,
+                esApiKey: this.esApiKey,
+                esUsername: this.esUsername,
+                esPassword: this.esPassword
+            });
+        } else {
+            this.elasticSearchClient = init.esClient;
+        }
+    }
+    /**
+   * Returns the Elasticsearch client instance
+   * @returns The configured Elasticsearch client
+   */ client() {
+        return this.elasticSearchClient;
+    }
+    /**
+   * Creates an Elasticsearch index if it doesn't exist
+   * @param dimensions - Number of dimensions in the vector embedding
+   * @private
+   */ async createIndexIfNotExists(dimensions) {
+        const indexExists = await this.elasticSearchClient.indices.exists({
+            index: this.indexName
+        });
+        if (!indexExists) {
+            await this.elasticSearchClient.indices.create({
+                index: this.indexName,
+                body: {
+                    mappings: {
+                        properties: {
+                            [this.textField]: {
+                                type: "text"
+                            },
+                            [this.vectorField]: {
+                                type: "dense_vector",
+                                dims: dimensions,
+                                index: true,
+                                similarity: this.distanceStrategy
+                            },
+                            metadata: {
+                                properties: {
+                                    document_id: {
+                                        type: "keyword"
+                                    },
+                                    doc_id: {
+                                        type: "keyword"
+                                    },
+                                    ref_doc_id: {
+                                        type: "keyword"
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            });
+        }
+    }
+    /**
+   * Adds nodes to the vector store
+   * @param nodes - Array of BaseNode objects to store
+   * @returns Array of node IDs that were successfully stored
+   * @throws Error if nodes don't have embeddings
+   */ async add(nodes) {
+        if (!nodes.length) {
+            return [];
+        }
+        const dimensions = nodes[0]?.getEmbedding()?.length;
+        if (!dimensions) {
+            throw new Error("Embedding is required");
+        }
+        await this.createIndexIfNotExists(dimensions);
+        const operations = nodes.flatMap((node)=>[
+                {
+                    index: {
+                        _index: this.indexName,
+                        _id: node.id_
+                    }
+                },
+                {
+                    [this.vectorField]: node.getEmbedding(),
+                    [this.textField]: node.getContent(MetadataMode.NONE),
+                    metadata: nodeToMetadata(node, true)
+                }
+            ]);
+        const results = await this.elasticSearchClient.bulk({
+            operations,
+            refresh: true
+        });
+        if (results.errors) {
+            const reasons = results.items.map((result)=>result.index?.error?.reason);
+            throw new Error(`Failed to insert documents:\n${reasons.join("\n")}`);
+        }
+        return nodes.map((node)=>node.id_);
+    }
+    /**
+   * Deletes nodes from the vector store by reference document ID
+   * @param refDocId - Reference document ID to delete
+   * @param deleteOptions - Optional deletion parameters
+   */ async delete(refDocId, deleteOptions) {
+        await this.elasticSearchClient.deleteByQuery({
+            index: this.indexName,
+            query: {
+                term: {
+                    "metadata.ref_doc_id": refDocId
+                }
+            },
+            refresh: true
+        });
+    }
+    /**
+   * Converts metadata filters to Elasticsearch query format
+   * @param queryFilters - Metadata filters to convert
+   * @returns Elasticsearch compatible filter object
+   * @private
+   */ toElasticSearchFilter(queryFilters) {
+        if (queryFilters.filters.length === 1) {
+            const filter = queryFilters.filters[0];
+            if (filter) {
+                return {
+                    term: {
+                        [`metadata.${filter.key}`]: filter.value
+                    }
+                };
+            }
+        }
+        return {
+            bool: {
+                must: queryFilters.filters.map((filter)=>({
+                        term: {
+                            [`metadata.${filter.key}`]: filter.value
+                        }
+                    }))
+            }
+        };
+    }
+    /**
+   * Normalizes similarity scores to range [0,1]
+   * @param scores - Array of raw similarity scores
+   * @returns Array of normalized similarity scores
+   * @private
+   */ toLlamaSimilarity(scores) {
+        if (!scores.length) {
+            return [];
+        }
+        const maxScore = Math.max(...scores);
+        const minScore = Math.min(...scores);
+        if (maxScore === minScore) {
+            return scores.map(()=>maxScore > 0 ? 1 : 0);
+        }
+        return scores.map((score)=>(score - minScore) / (maxScore - minScore));
+    }
+    /**
+   * Performs a vector similarity search query
+   * @param query - Vector store query parameters
+   * @param options - Optional query parameters
+   * @returns Query results containing matching nodes, similarities, and IDs
+   * @throws Error if query embedding is not provided
+   */ async query(query, options) {
+        if (!query.queryEmbedding) {
+            throw new Error("query embedding is not provided");
+        }
+        let elasticSearchFilter = [];
+        if (query.filters) {
+            elasticSearchFilter = [
+                this.toElasticSearchFilter(query.filters)
+            ];
+        }
+        const searchResponse = await this.elasticSearchClient.search({
+            index: this.indexName,
+            size: query.similarityTopK,
+            knn: {
+                field: this.vectorField,
+                query_vector: query.queryEmbedding,
+                k: query.similarityTopK,
+                num_candidates: query.similarityTopK * 10,
+                filter: elasticSearchFilter
+            }
+        });
+        return this.getVectorSearchQueryResultFromResponse(searchResponse);
+    }
+    /**
+   * Processes Elasticsearch response into VectorStoreQueryResult format
+   * @param res - Elasticsearch search response
+   * @returns Formatted query results
+   * @private
+   */ getVectorSearchQueryResultFromResponse(res) {
+        const hits = res.hits.hits;
+        const topKNodes = [];
+        const topKIDs = [];
+        const topKScores = [];
+        for (const hit of hits){
+            const source = hit._source;
+            const metadata = source?.metadata ?? {};
+            const text = source?.[this.textField] ?? "";
+            const embedding = source?.[this.vectorField] ?? [];
+            const nodeId = hit._id ?? "";
+            const score = hit._score ?? 0;
+            const node = metadataDictToNode(metadata);
+            node.setContent(text);
+            node.embedding = embedding;
+            topKNodes.push(node);
+            topKIDs.push(nodeId);
+            topKScores.push(score);
+        }
+        return {
+            nodes: topKNodes,
+            similarities: this.toLlamaSimilarity(topKScores),
+            ids: topKIDs
+        };
+    }
+}
+
+export { ElasticSearchVectorStore };

package/dist/index.js

@@ -0,0 +1,264 @@
+import { BaseVectorStore, nodeToMetadata, MetadataMode, metadataDictToNode } from '@vectorstores/core';
+import { Client } from '@elastic/elasticsearch';
+
+function getElasticSearchClient({ esUrl, esCloudId, esApiKey, esUsername, esPassword }) {
+    const clientOptions = {};
+    if (esUrl && esCloudId) {
+        throw new Error("Both esUrl and esCloudId cannot be provided");
+    }
+    if (esUrl) {
+        clientOptions.node = esUrl;
+    } else if (esCloudId) {
+        clientOptions.cloud = {
+            id: esCloudId
+        };
+    } else {
+        throw new Error("Either elasticsearch url or cloud id must be provided");
+    }
+    if (esApiKey) {
+        clientOptions.auth = {
+            apiKey: esApiKey
+        };
+    } else if (esUsername && esPassword) {
+        clientOptions.auth = {
+            username: esUsername,
+            password: esPassword
+        };
+    }
+    return new Client(clientOptions);
+}
+
+/**
+ * ElasticSearchVectorStore provides vector storage and similarity search capabilities using Elasticsearch.
+ * It extends BaseVectorStore to implement vector storage operations with Elasticsearch as the backend.
+ */ class ElasticSearchVectorStore extends BaseVectorStore {
+    /**
+   * Creates a new instance of ElasticSearchVectorStore
+   * @param init - Configuration parameters for Elasticsearch connection and indexing
+   */ constructor(init){
+        super(), this.storesText = true;
+        this.indexName = init.indexName;
+        this.esUrl = init.esUrl ?? undefined;
+        this.esCloudId = init.esCloudId ?? undefined;
+        this.esApiKey = init.esApiKey ?? undefined;
+        this.esUsername = init.esUsername ?? undefined;
+        this.esPassword = init.esPassword ?? undefined;
+        this.textField = init.textField ?? "content";
+        this.vectorField = init.vectorField ?? "embedding";
+        this.distanceStrategy = init.distanceStrategy ?? "cosine";
+        if (!init.esClient) {
+            this.elasticSearchClient = getElasticSearchClient({
+                esUrl: this.esUrl,
+                esCloudId: this.esCloudId,
+                esApiKey: this.esApiKey,
+                esUsername: this.esUsername,
+                esPassword: this.esPassword
+            });
+        } else {
+            this.elasticSearchClient = init.esClient;
+        }
+    }
+    /**
+   * Returns the Elasticsearch client instance
+   * @returns The configured Elasticsearch client
+   */ client() {
+        return this.elasticSearchClient;
+    }
+    /**
+   * Creates an Elasticsearch index if it doesn't exist
+   * @param dimensions - Number of dimensions in the vector embedding
+   * @private
+   */ async createIndexIfNotExists(dimensions) {
+        const indexExists = await this.elasticSearchClient.indices.exists({
+            index: this.indexName
+        });
+        if (!indexExists) {
+            await this.elasticSearchClient.indices.create({
+                index: this.indexName,
+                body: {
+                    mappings: {
+                        properties: {
+                            [this.textField]: {
+                                type: "text"
+                            },
+                            [this.vectorField]: {
+                                type: "dense_vector",
+                                dims: dimensions,
+                                index: true,
+                                similarity: this.distanceStrategy
+                            },
+                            metadata: {
+                                properties: {
+                                    document_id: {
+                                        type: "keyword"
+                                    },
+                                    doc_id: {
+                                        type: "keyword"
+                                    },
+                                    ref_doc_id: {
+                                        type: "keyword"
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            });
+        }
+    }
+    /**
+   * Adds nodes to the vector store
+   * @param nodes - Array of BaseNode objects to store
+   * @returns Array of node IDs that were successfully stored
+   * @throws Error if nodes don't have embeddings
+   */ async add(nodes) {
+        if (!nodes.length) {
+            return [];
+        }
+        const dimensions = nodes[0]?.getEmbedding()?.length;
+        if (!dimensions) {
+            throw new Error("Embedding is required");
+        }
+        await this.createIndexIfNotExists(dimensions);
+        const operations = nodes.flatMap((node)=>[
+                {
+                    index: {
+                        _index: this.indexName,
+                        _id: node.id_
+                    }
+                },
+                {
+                    [this.vectorField]: node.getEmbedding(),
+                    [this.textField]: node.getContent(MetadataMode.NONE),
+                    metadata: nodeToMetadata(node, true)
+                }
+            ]);
+        const results = await this.elasticSearchClient.bulk({
+            operations,
+            refresh: true
+        });
+        if (results.errors) {
+            const reasons = results.items.map((result)=>result.index?.error?.reason);
+            throw new Error(`Failed to insert documents:\n${reasons.join("\n")}`);
+        }
+        return nodes.map((node)=>node.id_);
+    }
+    /**
+   * Deletes nodes from the vector store by reference document ID
+   * @param refDocId - Reference document ID to delete
+   * @param deleteOptions - Optional deletion parameters
+   */ async delete(refDocId, deleteOptions) {
+        await this.elasticSearchClient.deleteByQuery({
+            index: this.indexName,
+            query: {
+                term: {
+                    "metadata.ref_doc_id": refDocId
+                }
+            },
+            refresh: true
+        });
+    }
+    /**
+   * Converts metadata filters to Elasticsearch query format
+   * @param queryFilters - Metadata filters to convert
+   * @returns Elasticsearch compatible filter object
+   * @private
+   */ toElasticSearchFilter(queryFilters) {
+        if (queryFilters.filters.length === 1) {
+            const filter = queryFilters.filters[0];
+            if (filter) {
+                return {
+                    term: {
+                        [`metadata.${filter.key}`]: filter.value
+                    }
+                };
+            }
+        }
+        return {
+            bool: {
+                must: queryFilters.filters.map((filter)=>({
+                        term: {
+                            [`metadata.${filter.key}`]: filter.value
+                        }
+                    }))
+            }
+        };
+    }
+    /**
+   * Normalizes similarity scores to range [0,1]
+   * @param scores - Array of raw similarity scores
+   * @returns Array of normalized similarity scores
+   * @private
+   */ toLlamaSimilarity(scores) {
+        if (!scores.length) {
+            return [];
+        }
+        const maxScore = Math.max(...scores);
+        const minScore = Math.min(...scores);
+        if (maxScore === minScore) {
+            return scores.map(()=>maxScore > 0 ? 1 : 0);
+        }
+        return scores.map((score)=>(score - minScore) / (maxScore - minScore));
+    }
+    /**
+   * Performs a vector similarity search query
+   * @param query - Vector store query parameters
+   * @param options - Optional query parameters
+   * @returns Query results containing matching nodes, similarities, and IDs
+   * @throws Error if query embedding is not provided
+   */ async query(query, options) {
+        if (!query.queryEmbedding) {
+            throw new Error("query embedding is not provided");
+        }
+        let elasticSearchFilter = [];
+        if (query.filters) {
+            elasticSearchFilter = [
+                this.toElasticSearchFilter(query.filters)
+            ];
+        }
+        const searchResponse = await this.elasticSearchClient.search({
+            index: this.indexName,
+            size: query.similarityTopK,
+            knn: {
+                field: this.vectorField,
+                query_vector: query.queryEmbedding,
+                k: query.similarityTopK,
+                num_candidates: query.similarityTopK * 10,
+                filter: elasticSearchFilter
+            }
+        });
+        return this.getVectorSearchQueryResultFromResponse(searchResponse);
+    }
+    /**
+   * Processes Elasticsearch response into VectorStoreQueryResult format
+   * @param res - Elasticsearch search response
+   * @returns Formatted query results
+   * @private
+   */ getVectorSearchQueryResultFromResponse(res) {
+        const hits = res.hits.hits;
+        const topKNodes = [];
+        const topKIDs = [];
+        const topKScores = [];
+        for (const hit of hits){
+            const source = hit._source;
+            const metadata = source?.metadata ?? {};
+            const text = source?.[this.textField] ?? "";
+            const embedding = source?.[this.vectorField] ?? [];
+            const nodeId = hit._id ?? "";
+            const score = hit._score ?? 0;
+            const node = metadataDictToNode(metadata);
+            node.setContent(text);
+            node.embedding = embedding;
+            topKNodes.push(node);
+            topKIDs.push(nodeId);
+            topKScores.push(score);
+        }
+        return {
+            nodes: topKNodes,
+            similarities: this.toLlamaSimilarity(topKScores),
+            ids: topKIDs
+        };
+    }
+}
+
+export { ElasticSearchVectorStore };

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@vectorstores/elastic-search",
+  "description": "Elastic Search 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/elastic-search"
+  },
+  "devDependencies": {
+    "vitest": "^3.0.9",
+    "@vectorstores/core": "0.1.0",
+    "@vectorstores/env": "0.1.0"
+  },
+  "peerDependencies": {
+    "@vectorstores/core": "0.1.0",
+    "@vectorstores/env": "0.1.0"
+  },
+  "dependencies": {
+    "@elastic/elasticsearch": "^8.17.1"
+  },
+  "scripts": {
+    "build": "bunchee",
+    "dev": "bunchee --watch",
+    "test": "vitest run"
+  }
+}