For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to page URLs.
Skip to content

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:

  1. GridGainStore: A key-value store for string values.

  2. GridGainByteStore: A key-value store for binary values, such as computed embeddings.

  3. GridGainDocumentLoader: A document loader for retrieving documents from GridGain caches.

  4. GridGainChatMessageHistory: A chat message history store.

  5. GridGainCache: An exact-match cache for large language model (LLM) responses.

  6. GridGainSemanticCache: A semantic cache for LLM responses.

  7. 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, and GridGainCache use only key-value operations and work with any edition.

    • GridGainVectorStore and GridGainSemanticCache require 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.

All components that use the same client share one lock, so you can use one client from several components and threads. Operations on one client run one at a time. If you need client-side parallelism, use several clients.

The lock protects each client operation, not a sequence of operations. For example, GridGainChatMessageHistory.add_messages() reads the session history and then writes it back. If several threads or processes add messages to the same session at the same time, they can overwrite each other's messages. Serialize updates to one session in your application.

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_scores and used by the similarity_score_threshold retriever, are calculated as 1 - distance. They are not limited to the [0, 1] range: opposite vectors have a relevance below 0.

  • The score_threshold argument 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 $in

  • Keys that are not declared in filterable_metadata_fields

  • A 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-core 1.4.7 or later instead of fixed versions of langchain and langchain-community, and requires pygridgain 1.6.0 or later.

  • Imports. Import the components from langchain_gridgain, not from langchain_community.

  • LLM cache keys. GridGainCache keys 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 CacheBackedEmbeddings example now uses key_encoder="sha256". If you change the key encoder, the embeddings are computed again. GridGainByteStore has no clear() method. To remove the old entries, call byte_store.mdelete(list(byte_store.yield_keys())).

  • Vector store. GridGainVectorStore returns real cosine distances instead of a constant score of 1.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?