Feature/valkey vector store by daric93 · Pull Request #20889 · run-llama/llama_index

daric93 · 2026-03-05T17:43:05Z

Description

Adds a new vector store integration for Valkey, an open-source key-value datastore that supports high-performance vector similarity search through the valkey-search module.

Uses valkey-glide (async) and valkey-glide-sync (sync) official clients
Mirrors Redis vector store API for seamless migration
Three initialization patterns: URL only, sync client only, async client only
Lazy async client creation for optimal resource usage

Fixes #20785

Dependencies

Required

valkey-glide>=2.2.7 - Official async Valkey client
valkey-glide-sync>=2.1.0 - Official sync Valkey client
llama-index-core>=0.13.0,<0.15 - LlamaIndex core functionality

Development

Standard LlamaIndex dev dependencies (pytest, mypy, ruff, etc.)

Motivation and Context

Valkey is gaining significant traction as an open-source alternative to Redis. Several factors make this integration timely and valuable:

Open Source Governance: As a Linux Foundation project, Valkey offers transparent governance and community-driven development
Redis Compatibility: Valkey maintains protocol compatibility for core features with Redis while adding new features, making migration straightforward
Performance: The valkey-search module delivers single-digit millisecond latency with 99%+ recall for vector search operations
Growing Adoption: Major cloud providers are offering managed Valkey services with vector search capabilities

New Package?

Did I fill in the tool.llamahub section in the pyproject.toml and provide a detailed README.md for my new integration or package?

Yes
No

Version Bump?

It is a new integration.

Type of Change

New feature (non-breaking change which adds functionality)

How Has This Been Tested?

I added new unit and integration tests to cover this change. Manual testing.

Suggested Checklist:

I have performed a self-review of my own code
I have commented my code, particularly in hard-to-understand areas
I have made corresponding changes to the documentation
I have added Google Colab support for the newly added notebooks.
I have added tests that prove my fix is effective or that my feature works
New and existing unit tests pass locally with my changes
I ran uv run make format; uv run make lint to appease the lint gods

review-notebook-app · 2026-03-05T17:43:12Z

Check out this pull request on

See visual diffs & provide feedback on Jupyter Notebooks.

Powered by ReviewNB

daric93 · 2026-03-05T17:52:56Z

As discussed in #20785 , this PR uses TEXT field support which is currently in RC (Release Candidate) in Valkey-Search, not yet GA.

The implementation is complete and ready for review, but I'm keeping this as a draft until TEXT support reaches GA (estimated March 2026). I'll mark it ready for merge once the official release is available.

In the meantime, feel free to review the implementation and provide any feedback. Happy to address comments while we wait for the GA release.

AstraBert

This looks great, thanks for doing this! I added some comments related to questions/things I would like to change :)

AstraBert · 2026-03-11T10:47:39Z

This is auto-generated from our docs build, no need to modify it

AstraBert · 2026-03-11T10:49:03Z

+class TokenEscaper:
+    """
+    Escape punctuation within an input string. Taken from RedisOM Python.
+    """
+
+    # Keep for compatibility. Characters that RediSearch requires us to escape during queries.
+    # Source: https://redis.io/docs/stack/search/reference/escaping/#the-rules-of-text-field-tokenization
+    DEFAULT_ESCAPED_CHARS = r"[,.<>{}\[\]\\\"\':;!@#$%^&*()\-+=~\/ ]"
+
+    def __init__(self, escape_chars_re: Optional[Pattern] = None):
+        if escape_chars_re:
+            self.escaped_chars_re = escape_chars_re
+        else:
+            self.escaped_chars_re = re.compile(self.DEFAULT_ESCAPED_CHARS)
+
+    def escape(self, value: str) -> str:
+        def escape_symbol(match: re.Match) -> str:
+            value = match.group(0)
+            return f"\\{value}"
+
+        return self.escaped_chars_re.sub(escape_symbol, value)


I would probably implement this as a function rather than a class

removed completely. Valkey's filter implementation handles special characters. Added tests to verify.

AstraBert · 2026-03-11T10:51:31Z

+            url_parts = valkey_url.replace("valkey://", "").split(":")
+            host = url_parts[0] if len(url_parts) > 0 else "localhost"
+            port = int(url_parts[1]) if len(url_parts) > 1 else 6379


I feel like using something like urllib would make the logic easier for parsing the URL here

changed to use urllib

AstraBert · 2026-03-11T10:51:57Z

+
+            # Create sync client immediately (synchronous operation)
+            if not valkey_client:
+                from glide_sync import (


Imports should be placed at the top

AstraBert · 2026-03-11T10:53:11Z

+    @property
+    def client(
+        self,
+    ) -> SyncGlideClient | SyncGlideClusterClient | GlideClient | GlideClusterClient:
+        """Return the valkey client instance."""
+        return self._valkey_client or self._valkey_client_async


We generally use two different properties, one for the sync client (client) and one for the asynchronous one (aclient)

created separate properties

AstraBert · 2026-03-11T11:00:18Z

+    def _ensure_sync_client(self) -> None:
+        """
+        Ensure sync client is available.
+
+        Raises:
+            Exception: If sync client is not available.
+
+        """
+        if not self._valkey_client:
+            raise ValkeyVectorStoreError("No sync client available")


In the spirit of the lazily initialization comment above, I would initialize the sync client here once (pretty much as you do for the async client)

AstraBert · 2026-03-11T11:03:03Z

+VECTOR_FIELD_NAME: str = "vector"
+
+
+class ValkeyIndexInfo:


This should probably be a dataclass

changed. to dataclass

AstraBert · 2026-03-11T11:05:22Z

+
+    GLIDE_AVAILABLE = True
+except ImportError:
+    GLIDE_AVAILABLE = False


This should always be available as I am guessing is part of the valkey-glide and valkey-glide-sync required dependencies in the pyproject.toml(?)
If it is not available, I would consider adding it as a required dependency, or, if you do not want overhead for the package, you could just add it as a dev dependency to be bundled only with tests

AstraBert · 2026-03-11T11:10:34Z

+[tool.uv.sources]
+llama-index-core = {path = "../../../llama-index-core", editable = true}


I feel like this might mess up some things when someone tries to install the package, I would remove it

AstraBert · 2026-03-11T11:12:59Z

+        pass
+
+
+@pytest.mark.integration


I don't see any configuration related to the integration marker here for pytest, and I am not sure our CI would automatically skip them, so I think you might need to add it in the pytest.ini config in the pyproject file

daric93 · 2026-03-13T18:58:29Z

@AstraBert Thanks for the review! All comments have been addressed — ready for a second look when you get a chance.

Signed-off-by: Daria Korenieva <daric2612@gmail.com>

daric93 · 2026-03-19T00:15:12Z

The valkey-search module with text search support is now GA (v1.2.0).

logan-markewich · 2026-03-25T01:51:57Z

Sorry, right now we are pausing contributions that contribute net-new packages. I appreciate the contribution but going to close this out.

daric93 · 2026-03-25T14:55:16Z

Thanks for the review and for letting me know. I understand the pause on new packages. If the policy changes in the future, I'd be happy to rebase and resubmit.

dosubot Bot added the size:XXL This PR changes 1000+ lines, ignoring generated files. label Mar 5, 2026

daric93 changed the title ~~Feature/valkey vector store~~ draft:Feature/valkey vector store Mar 5, 2026

daric93 changed the title ~~draft:Feature/valkey vector store~~ Feature/valkey vector store Mar 5, 2026

daric93 marked this pull request as draft March 5, 2026 17:52

AstraBert reviewed Mar 11, 2026

View reviewed changes

daric93 added 11 commits March 18, 2026 17:10

valkey vector store implementation

9ab96da

added readme

f24d791

Revert Redis conftest.py to original version

c749b25

fixes

cfff0a2

addressed comments

d7255ca

addressed comments

2f67dfc

addressed comments

4e750b7

Signed-off-by: Daria Korenieva <daric2612@gmail.com>

removed valkey.md

75308ce

Signed-off-by: Daria Korenieva <daric2612@gmail.com>

fix test

1f053ee

Signed-off-by: Daria Korenieva <daric2612@gmail.com>

fix tests

a7098bf

Signed-off-by: Daria Korenieva <daric2612@gmail.com>

formatting

c6b795b

Signed-off-by: Daria Korenieva <daric2612@gmail.com>

daric93 force-pushed the feature/valkey-vector-store branch from cdf9f14 to c6b795b Compare March 19, 2026 00:10

daric93 marked this pull request as ready for review March 19, 2026 00:11

logan-markewich closed this Mar 25, 2026

		[tool.uv.sources]
		llama-index-core = {path = "../../../llama-index-core", editable = true}

		pass


		@pytest.mark.integration

Conversation

daric93 commented Mar 5, 2026

Description

Dependencies

Required

Development

Motivation and Context

New Package?

Version Bump?

Type of Change

How Has This Been Tested?

Suggested Checklist:

Uh oh!

review-notebook-app Bot commented Mar 5, 2026

Uh oh!

daric93 commented Mar 5, 2026

Uh oh!

AstraBert left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

daric93 commented Mar 13, 2026

Uh oh!

daric93 commented Mar 19, 2026

Uh oh!

logan-markewich commented Mar 25, 2026

Uh oh!

daric93 commented Mar 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants