Overview

1. Overview

LangChain Infinispan provides LangChain integration with Infinispan, offering a vector store for similarity search in AI applications.

1.1. What is LangChain Infinispan?

LangChain Infinispan is a community integration that connects LangChain with Infinispan.

It provides an InfinispanVectorStore that implements the LangChain VectorStore interface, enabling:

Store and search document embeddings using Infinispan vector search capabilities with Ickle query language.
Metadata filtering with support for typed fields (strings, integers, floats).
Multiple distance strategies: Cosine, L2, Inner Product, and Max Inner Product.
Automatic Protobuf schema registration and indexed cache creation.
Three authentication methods: username/password, bearer token, or pre-built client.

The integration uses the Infinispan REST API for all operations.

2. Getting started

Install LangChain Infinispan and connect to an Infinispan Server instance.

2.1. Installing LangChain Infinispan

Install the LangChain Infinispan package from PyPI.

Prerequisites

Python 3.10 or later
Infinispan 15 or later with vector search support

Procedure

Install the package:
```
pip install langchain-infinispan
```

Verify the installation:

from langchain_infinispan import InfinispanVectorStore
print("langchain-infinispan installed successfully")

2.2. Starting Infinispan Server

Start an Infinispan Server instance for your LangChain application to connect to.

Procedure

Run Infinispan Server with Docker:

docker run -p 11222:11222 -e USER="admin" -e PASS="password" quay.io/infinispan/server:latest

The server starts with default settings and creates an admin user. The REST API is available at http://localhost:11222.

3. Vector store

Use Infinispan as a vector store in your LangChain applications for storing embeddings and performing similarity search.

3.1. How the vector store works

The Infinispan vector store uses Protobuf schemas to define the structure of stored embeddings. When the vector store is first used, it:

Builds a Protobuf schema with dimension-specific message names (for example, LangChainItem1536 for 1536-dimensional embeddings).
Registers the schema with Infinispan Server.
Creates an indexed distributed cache configured for vector search.

Similarity search uses the Infinispan Ickle query language with the <→ vector distance operator. The store supports metadata filtering through Ickle query joins on embedded metadata fields.

Each document is stored as a Protobuf message containing:

id - unique identifier
text - the document text
embedding - the vector representation
metadata - repeated embedded messages with typed fields for strings, integers, and floats

3.2. Creating the vector store

Create an InfinispanVectorStore instance to connect to Infinispan Server. Three authentication methods are available.

Username and password authentication

from langchain_infinispan import InfinispanVectorStore
from langchain_openai import OpenAIEmbeddings

vector_store = InfinispanVectorStore(
    embedding=OpenAIEmbeddings(),
    cache_name="my_vectors",
    ispn_url="http://localhost:11222",
    ispn_user="admin",
    ispn_password="password",
)

Bearer token authentication

vector_store = InfinispanVectorStore(
    embedding=OpenAIEmbeddings(),
    cache_name="my_vectors",
    ispn_url="http://localhost:11222",
    ispn_bearer_token="my-token",
)

Pre-built client

from langchain_infinispan import InfinispanVectorStore, InfinispanClient

client = InfinispanClient(
    url="http://localhost:11222",
    username="admin",
    password="password",
)

vector_store = InfinispanVectorStore(
    embedding=OpenAIEmbeddings(),
    cache_name="my_vectors",
    client=client,
)

Using a pre-built client allows you to share a single HTTP session across multiple vector store instances.

3.3. Vector store parameters

The following table describes the parameters for InfinispanVectorStore.

Parameter Type Default Description

Parameter	Type	Default	Description
`embedding`	`Embeddings`	(required)	The embedding model to use for vectorizing text.
`cache_name`	`str`	`langchain_vectors`	Name of the Infinispan cache to store vectors.
`client`	`InfinispanClient`	`None`	Pre-built client instance. If provided, connection parameters are ignored.
`ispn_url`	`str`	`http://localhost:11222`	Infinispan Server URL.
`ispn_user`	`str`	`None`	Username for HTTP Digest authentication.
`ispn_password`	`str`	`None`	Password for HTTP Digest authentication.
`ispn_bearer_token`	`str`	`None`	Bearer token for authentication.
`verify`	`bool`	`True`	Whether to verify TLS certificates.
`dimension`	`int`	`None`	Embedding dimension. Auto-detected from the embedding model if not set.
`similarity`	`DistanceStrategy`	`COSINE`	Distance strategy for similarity search.
`cache_config`	`str`	`None`	Custom cache configuration XML. Uses a default indexed distributed cache if not set.
`create_cache`	`bool`	`True`	Whether to auto-create the cache if it does not exist.
`register_schema`	`bool`	`True`	Whether to auto-register the Protobuf schema.

embedding

Embeddings

(required)

The embedding model to use for vectorizing text.

cache_name

str

langchain_vectors

Name of the Infinispan cache to store vectors.

client

InfinispanClient

None

Pre-built client instance. If provided, connection parameters are ignored.

ispn_url

str

http://localhost:11222

Infinispan Server URL.

ispn_user

str

None

Username for HTTP Digest authentication.

ispn_password

str

None

Password for HTTP Digest authentication.

ispn_bearer_token

str

None

Bearer token for authentication.

verify

bool

True

Whether to verify TLS certificates.

dimension

int

None

Embedding dimension. Auto-detected from the embedding model if not set.

similarity

DistanceStrategy

COSINE

Distance strategy for similarity search.

cache_config

str

None

Custom cache configuration XML. Uses a default indexed distributed cache if not set.

create_cache

bool

True

Whether to auto-create the cache if it does not exist.

register_schema

bool

True

Whether to auto-register the Protobuf schema.

3.4. Distance strategies

The following distance strategies are available for similarity search.

Strategy Description

Strategy	Description
`COSINE`	Cosine similarity. Default strategy. Works with any vectors.
`L2`	Euclidean (squared L2) distance.
`INNER_PRODUCT`	Dot product similarity. Requires unit-length (normalized) vectors. On Infinispan 15.1+, the server rejects non-normalized vectors.
`MAX_INNER_PRODUCT`	Dot product similarity that allows non-normalized vectors. Relevance scores are normalized using `s / (1 + s)`.

COSINE

Cosine similarity. Default strategy. Works with any vectors.

L2

Euclidean (squared L2) distance.

INNER_PRODUCT

Dot product similarity. Requires unit-length (normalized) vectors. On Infinispan 15.1+, the server rejects non-normalized vectors.

MAX_INNER_PRODUCT

Dot product similarity that allows non-normalized vectors. Relevance scores are normalized using s / (1 + s).

Setting a distance strategy

from langchain_infinispan import InfinispanVectorStore, DistanceStrategy

vector_store = InfinispanVectorStore(
    embedding=my_embeddings,
    similarity=DistanceStrategy.L2,
    ispn_url="http://localhost:11222",
    ispn_user="admin",
    ispn_password="password",
)

3.5. Adding documents

Add documents to the Infinispan vector store. Documents are automatically embedded and stored with their metadata.

Adding texts

ids = vector_store.add_texts(
    texts=["Hello world", "Infinispan is fast"],
    metadatas=[{"source": "greeting"}, {"source": "fact"}],
)

Adding LangChain Documents

from langchain_core.documents import Document

docs = [
    Document(page_content="Hello world", metadata={"source": "greeting"}),
    Document(page_content="Infinispan is fast", metadata={"source": "fact"}),
]
ids = vector_store.add_documents(docs)

Creating from texts

vector_store = InfinispanVectorStore.from_texts(
    texts=["Hello world", "Infinispan is fast"],
    embedding=my_embeddings,
    metadatas=[{"source": "greeting"}, {"source": "fact"}],
    ispn_url="http://localhost:11222",
    ispn_user="admin",
    ispn_password="password",
)

Unique IDs are auto-generated for each document. You can also provide custom IDs with the ids parameter.

3.6. Performing similarity search

Search for documents similar to a query using the Infinispan vector store.

Basic similarity search

results = vector_store.similarity_search("hello", k=5)
for doc in results:
    print(doc.page_content, doc.metadata)

Search with scores

results = vector_store.similarity_search_with_score("hello", k=5)
for doc, score in results:
    print(f"{doc.page_content} (score: {score})")

Search with relevance scores

Relevance scores are normalized to [0, 1] for all distance strategies.

results = vector_store.similarity_search_with_relevance_scores("hello", k=5)
for doc, score in results:
    print(f"{doc.page_content} (relevance: {score})")

Search by embedding vector

embedding = my_embeddings.embed_query("hello")
results = vector_store.similarity_search_by_vector(embedding, k=5)

Search with metadata filter

results = vector_store.similarity_search(
    "hello",
    k=5,
    filter={"source": "greeting"},
)

3.7. Managing documents

Delete, retrieve, and clear documents in the Infinispan vector store.

Deleting documents by ID

vector_store.delete(ids=["id1", "id2"])

Retrieving documents by ID

docs = vector_store.get_by_ids(["id1", "id2"])

Clearing all documents

vector_store.clear()

Closing the connection

Close the HTTP session when you are done with the vector store.

vector_store.close()

4. Metadata filtering

Filter similarity search results based on document metadata using Infinispan Ickle queries.

4.1. How metadata filtering works

The Infinispan vector store supports filtering similarity search results based on document metadata.

Metadata values are stored with type-aware fields in the Protobuf schema:

String values are stored in the value field.
Integer values are stored in both value and value_int fields.
Float values are stored in both value and value_float fields.

Two filter formats are supported:

Dictionary filters

Simple key-value equality matching. List values are translated to IN clauses.

results = vector_store.similarity_search(
    "hello",
    filter={"source": "greeting"},
)

results = vector_store.similarity_search(
    "hello",
    filter={"category": ["news", "tech"]},
)

LangChain structured filters

Use Comparison and Operation objects from langchain_core.structured_query for complex filter expressions.

from langchain_core.structured_query import Comparison, Comparator

results = vector_store.similarity_search(
    "hello",
    filter=Comparison(
        comparator=Comparator.GT,
        attribute="year",
        value=2020,
    ),
)

Filter expressions are translated to Infinispan Ickle queries with metadata joins for each filtered field.

4.2. Supported filter operations

The Infinispan vector store supports the following filter operations.

Table 1. Comparators
Comparator	Description	Example
`EQ`	Equals	`Comparison(comparator=Comparator.EQ, attribute="country", value="BG")`
`NE`	Not equals	`Comparison(comparator=Comparator.NE, attribute="status", value="active")`
`GT`	Greater than	`Comparison(comparator=Comparator.GT, attribute="year", value=2020)`
`GTE`	Greater than or equal	`Comparison(comparator=Comparator.GTE, attribute="score", value=4.5)`
`LT`	Less than	`Comparison(comparator=Comparator.LT, attribute="price", value=100)`
`LTE`	Less than or equal	`Comparison(comparator=Comparator.LTE, attribute="rating", value=3)`
`IN`	In list	`Comparison(comparator=Comparator.IN, attribute="country", value=["BG", "NL"])`
`NIN`	Not in list	`Comparison(comparator=Comparator.NIN, attribute="status", value=["deleted"])`
`CONTAIN`	Contains substring	`Comparison(comparator=Comparator.CONTAIN, attribute="name", value="test")`
`LIKE`	Pattern match	`Comparison(comparator=Comparator.LIKE, attribute="name", value="test%")`

Table 2. Logical operators
Operator	Description
`AND`	All conditions must match.
`OR`	At least one condition must match.
`NOT`	Negates the condition.

Combined filter example

from langchain_core.structured_query import (
    Comparator, Comparison, Operation, Operator,
)

filter_expr = Operation(
    operator=Operator.AND,
    arguments=[
        Comparison(comparator=Comparator.EQ, attribute="country", value="BG"),
        Comparison(comparator=Comparator.GT, attribute="year", value=2020),
    ],
)

results = vector_store.similarity_search("hello", filter=filter_expr)