LangChain
Use GridGain 8 as a backend for LangChain components, including key-value and byte stores, a document loader, chat message history, LLM caches, and a vector store.
The langchain-gridgain package provides storage adapters that let LangChain components use GridGain as a backend for various data storage needs.
Features
The package implements the following LangChain interfaces:
GridGainStore: A key-value store for string values.
GridGainByteStore: A key-value store for binary values, such as computed embeddings.
GridGainDocumentLoader: A document loader for retrieving documents from GridGain caches.
GridGainChatMessageHistory: A chat message history store.
GridGainCache: An exact-match cache for large language model (LLM) responses.
GridGainSemanticCache: A semantic cache for LLM responses.
GridGainVectorStore: A vector store for storing and querying embeddings.
For LangGraph persistence, see LangGraph Integration.
Prerequisites
The following is required to use the LangChain integration:
Python 3.11 or later.
A running GridGain 8 cluster. The edition you need depends on the components that you use:
GridGainStore,GridGainByteStore,GridGainDocumentLoader,GridGainChatMessageHistory, andGridGainCacheuse only key-value operations and work with any edition.GridGainVectorStoreandGridGainSemanticCacherequire GridGain 8.9.17 or later with a license that provides access to vector search.
To filter vector searches by metadata, GridGain 8.10 or later. See Filtering by Metadata.
Installation
Install the langchain-gridgain package using pip:
Version 3.1.0 depends on langchain-core 1.4.7 or later (below 2.0), the GridGain 8 Python thin client pygridgain 1.7.0 or later (below 2.0), and the Apache Ignite Python thin client pyignite 0.6.1 or later (below 0.7). It does not depend on langchain-community.
GridGainStore, GridGainByteStore, GridGainDocumentLoader, GridGainChatMessageHistory, and GridGainCache accept a pygridgain or a pyignite client. GridGainVectorStore and GridGainSemanticCache require a pygridgain client, because pyignite does not support vector queries.
Connecting to GridGain
Before using any of the GridGain-based components, connect to your GridGain cluster with the Python thin client:
Replace "your_username", "your_password", "gridgain.example.com", and 10800 with your actual GridGain cluster credentials and connection details.
The examples below use the client object returned by this function.
Detailed Component Explanations
1. GridGainStore
GridGainStore is a key-value store that uses GridGain as its backend. It provides a simple way to store and retrieve data using key-value pairs.
Usage example:
2. GridGainByteStore
GridGainByteStore is a key-value store for binary values (BaseStore[str, bytes]). Its main use is caching computed embeddings with LangChain's CacheBackedEmbeddings, so each text is embedded only once.
mget, mset, and mdelete each send one request for the whole batch. mget returns the values in the order of the keys, with None for missing keys.
Usage example:
This example requires the langchain-classic package, which langchain-gridgain does not install. Choose a namespace that identifies the embedding model and its configuration.
3. GridGainDocumentLoader
GridGainDocumentLoader loads documents from GridGain caches. It is useful when you need to retrieve and process large amounts of text stored in GridGain.
Usage example:
4. GridGainChatMessageHistory
GridGainChatMessageHistory stores and retrieves chat message history in GridGain. Use it to keep context in conversational AI applications.
Usage example:
5. GridGainCache
GridGainCache caches LLM responses in GridGain. This improves response times for repeated, identical prompts.
The cache key includes both the prompt and the LLM, so the same prompt sent to different models is cached separately.
Usage example:
To remove all entries from the cache, call llm_cache.clear().
6. GridGainSemanticCache
GridGainSemanticCache caches LLM responses for similar prompts. It finds a cached response by comparing the embedding of a new prompt with the embeddings of earlier prompts, and stores the responses in a GridGainCache.
Usage example:
If a lookup fails, the semantic cache logs the error and treats it as a cache miss. If an update fails, it logs the error and skips the write. clear() raises an exception on failure.
semantic_cache.clear() removes all entries from its own cache and from the whole GridGainCache that it uses.
7. GridGainVectorStore
GridGainVectorStore stores and queries embeddings in GridGain. It implements the standard LangChain VectorStore interface.
Usage example:
Scores are cosine distances: a lower distance means a closer match. Relevance scores, as returned by
similarity_search_with_relevance_scoresand used by thesimilarity_score_thresholdretriever, are calculated as1 - distance. They are not limited to the[0, 1]range: opposite vectors have a relevance below0.The
score_thresholdargument of the search methods is applied on the server, on the similarity scale of the vector engine. If you omit it, no threshold is applied.Deleting a document also removes it from the vector index.
The asynchronous methods run the synchronous ones in a thread pool.
Filtering by Metadata
You can restrict a vector search to documents with given metadata values. GridGain applies the filter on the server before it selects the top k results, so a filtered search returns up to k matching documents.
Declare the metadata keys that you want to filter on in filterable_metadata_fields when you create the store. The store writes each declared key as a separate string field in a full-text index next to the vector index. The full metadata is still stored and returned unchanged.
A field name must start with a letter, contain only letters, digits, and underscores, and be at most 63 characters long. It cannot be a Python keyword, self, or cls. The names id, content, contentVector, metadata, schema, schema_id, type_id, type_name, and version are reserved in any letter case. For any other name, the store raises ValueError.
The filter is passed to similarity search, maximal marginal relevance search, and retrievers. It supports the following forms:
Several keys, combined with AND:
{"tenant": "alice", "category": "laptop"}.Explicit equality:
{"tenant": {"$eq": "alice"}}.Explicit AND:
{"$and": [{"tenant": "alice"}, {"category": "laptop"}]}.
Only None and {} mean no filter. The following filters raise ValueError instead of being ignored:
Other operators, such as ranges,
$or, and$inKeys that are not declared in
filterable_metadata_fieldsA key tested for two different values
Filters that are not dictionaries
Values are compared as text. Strings are compared as is, booleans as "true" or "false", and numbers as their text form. As a result, the integer 1 matches the string "1", but not the float 1.0. Other values, such as None, lists, and dates, are not stored in the filter fields, so they never match, and a filter on them raises ValueError.
If the cluster does not support filtered vector queries, a filtered search raises NotSupportedByClusterError. The filter is never dropped silently.
Entry Expiry (TTL)
GridGainStore, GridGainByteStore, GridGainCache, GridGainSemanticCache, and GridGainVectorStore accept an optional ttl argument that sets a time to live (TTL), as a number of seconds or a datetime.timedelta. Entries that the component writes expire that long after they are created or updated. Reading an entry does not extend its lifetime. A ttl below one millisecond raises ValueError.
The default, None, does not change the expiry policy of the cache.
GridGainChatMessageHistory and GridGainDocumentLoader do not accept ttl.
For the semantic cache, ttl applies to its own entries. Set the same ttl on the GridGainCache that it uses, so that both expire together.
Upgrading to Version 3.1.0
Version 3.1.0 requires Python 3.11 or later and pygridgain 1.7.0 or later (below 2.0). Upgrade Python before you install the new version. A non-empty filter that the vector store cannot apply raises ValueError. Only None and {} mean no filter. The stored data remains compatible with version 3.0.0.
Upgrading to Version 3.0.0
In version 3.0.0, the LangGraph checkpointer and memory store moved from langchain-gridgain to the langgraph-checkpoint-gridgain package. If you use them, install langgraph-checkpoint-gridgain and update the imports as described in LangGraph Integration. If you use only the LangChain components, no changes are required.
Upgrading From Version 1.0.x
Version 2.0.0 changed the following:
Dependencies. The package depends on
langchain-core1.4.7 or later instead of fixed versions oflangchainandlangchain-community, and requirespygridgain1.6.0 or later.Imports. Import the components from
langchain_gridgain, not fromlangchain_community.LLM cache keys.
GridGainCachekeys now include the LLM. Entries written by version 1.0.x cannot be found with the new keys and never expire. After the upgrade, clear each cache once:Embedding cache keys. The
CacheBackedEmbeddingsexample now useskey_encoder="sha256". If you change the key encoder, the embeddings are computed again.GridGainByteStorehas noclear()method. To remove the old entries, callbyte_store.mdelete(list(byte_store.yield_keys())).Vector store.
GridGainVectorStorereturns real cosine distances instead of a constant score of1.0, and supports deleting documents by ID.
LangChain Tutorial
GridGain provides a tutorial with a demonstration project. The project uses langchain-gridgain to build a laptop recommendation system and shows GridGain as a backend for several LangChain components.
The tutorial is available in the How to Build Retrieval-Augmented Generation With GridGain and LangChain page.
This page is: Copyright © 2026 MariaDB. All rights reserved.
Last updated
Was this helpful?

