Skip to content

Graph-Native Infrastructure for Context and Accountable AI Systems

feat(milvus): accept uri/token for Milvus Lite, remote server, and Zilliz Cloud (#1641)

Sakshi Jain99e6680602d0
diff --git a/semantica/vector_store/milvus_store.py b/semantica/vector_store/milvus_store.py
index 9496aad7..71653391 100644
--- a/semantica/vector_store/milvus_store.py
+++ b/semantica/vector_store/milvus_store.py
@@ -13,6 +13,8 @@ Key Features:
- Collection loading and release
- Batch insert and search operations
- Collection statistics and monitoring
+ - Connect via host/port (self-hosted server) or uri/token (Milvus Lite
+ file, remote server address, or Zilliz Cloud)
- Optional dependency handling
Main Classes:
@@ -31,6 +33,9 @@ Example Usage:
>>> results = store.search_vectors(query_vector, limit=10, expr="category == 'science'")
>>> stats = store.get_stats()
+ Or connect to Zilliz Cloud (or any uri-addressable Milvus) instead:
+ >>> store = MilvusStore(uri="https://<cluster>.zillizcloud.com", token="<api-key>")
+
Author: Semantica Contributors
License: MIT
"""
@@ -38,6 +43,7 @@ License: MIT
import math
import re
from typing import Any, Dict, List, Optional, Union
+from urllib.parse import urlsplit, urlunsplit
import numpy as np
@@ -46,6 +52,28 @@ from ..utils.logging import get_logger
from ..utils.progress_tracker import get_progress_tracker
+def _redact_uri(uri: str) -> str:
+ """Return a connection uri safe to log.
+
+ A uri may carry credentials as userinfo (``scheme://user:pass@host``) or
+ in query parameters (e.g. an embedded token); both would otherwise reach
+ the logger verbatim on every successful connection. Strip both, keeping
+ only scheme/host/port/path. A uri with no scheme/netloc (a local Milvus
+ Lite file path like ``"./milvus.db"``) carries no such secrets and is
+ returned unchanged.
+ """
+ try:
+ parts = urlsplit(uri)
+ except ValueError:
+ return "<redacted>"
+ if not parts.scheme and not parts.netloc:
+ return uri
+ netloc = parts.hostname or ""
+ if parts.port:
+ netloc = f"{netloc}:{parts.port}"
+ return urlunsplit((parts.scheme, netloc, parts.path, "", ""))
+
+
def _validate_milvus_key(key: str) -> str:
"""Validate and escape a metadata filter key for Milvus queries."""
if not key or not isinstance(key, str) or not re.match(r"^[a-zA-Z0-9_.-]+$", key):
@@ -122,21 +150,44 @@ class MilvusClient:
port: int = 19530,
user: Optional[str] = None,
password: Optional[str] = None,
+ uri: Optional[str] = None,
+ token: Optional[str] = None,
**options,
) -> bool:
- """Connect to Milvus server."""
+ """Connect to Milvus.
+
+ If ``uri`` is given (a Milvus Lite file path, a server address like
+ ``http://localhost:19530``, or a Zilliz Cloud endpoint), connect via
+ uri and ignore host/port — pymilvus treats uri and host/port as
+ mutually exclusive addressing, so passing both raises. user/password
+ and token are both still forwarded alongside uri: a self-hosted
+ server reached by uri may use RBAC user/password rather than a
+ token, so dropping them would silently strip valid credentials.
+ Otherwise fall back to the existing host/port/user/password server
+ connection.
+ """
if not MILVUS_AVAILABLE:
raise ProcessingError("Milvus not available")
try:
- connections.connect(
- alias=self.alias,
- host=host,
- port=port,
- user=user,
- password=password,
- **options,
- )
+ if uri:
+ connections.connect(
+ alias=self.alias,
+ uri=uri,
+ user=user,
+ password=password,
+ token=token,
+ **options,
+ )
+ else:
+ connections.connect(
+ alias=self.alias,
+ host=host,
+ port=port,
+ user=user,
+ password=password,
+ **options,
+ )
return True
except Exception as e:
raise ProcessingError(f"Failed to connect to Milvus: {str(e)}")
@@ -310,9 +361,26 @@ class MilvusStore:
port: int = 19530,
user: Optional[str] = None,
password: Optional[str] = None,
+ uri: Optional[str] = None,
+ token: Optional[str] = None,
**config,
):
- """Initialize Milvus store."""
+ """Initialize Milvus store.
+
+ Args:
+ host: Milvus server host. Ignored when ``uri`` is set.
+ port: Milvus server port. Ignored when ``uri`` is set.
+ user: Username for server auth (RBAC). Used with either host/port
+ or uri.
+ password: Password for server auth (RBAC). Used with either
+ host/port or uri.
+ uri: Connection URI — a Milvus Lite file path (e.g.
+ ``"./milvus.db"``), a server address (e.g.
+ ``"http://localhost:19530"``), or a Zilliz Cloud endpoint.
+ Takes precedence over host/port when set.
+ token: Auth token for ``uri`` (e.g. a Zilliz Cloud API key).
+ **config: Additional backend config.
+ """
self.logger = get_logger("milvus_store")
self.config = config
self.progress_tracker = get_progress_tracker()
@@ -323,6 +391,8 @@ class MilvusStore:
self.port = port or config.get("port", 19530)
self.user = user or config.get("user")
self.password = password or config.get("password")
+ self.uri = uri or config.get("uri")
+ self.token = token or config.get("token")
self.client: Optional[MilvusClient] = None
self.collection: Optional[MilvusCollection] = None
@@ -356,10 +426,15 @@ class MilvusStore:
port=self.port,
user=self.user,
password=self.password,
+ uri=self.uri,
+ token=self.token,
**options,
)
- self.logger.info(f"Connected to Milvus at {self.host}:{self.port}")
+ if self.uri:
+ self.logger.info(f"Connected to Milvus at {_redact_uri(self.uri)}")
+ else:
+ self.logger.info(f"Connected to Milvus at {self.host}:{self.port}")
return True
except Exception as e:
raise ProcessingError(f"Failed to connect to Milvus: {str(e)}")
diff --git a/tests/vector_store/test_milvus_connect_uri.py b/tests/vector_store/test_milvus_connect_uri.py
new file mode 100644
index 00000000..40dcc33a
--- /dev/null
+++ b/tests/vector_store/test_milvus_connect_uri.py
@@ -0,0 +1,107 @@
+"""Tests for MilvusStore's uri/token connection passthrough.
+
+Covers connecting to Milvus Lite / a remote server / Zilliz Cloud via a
+single `uri` (+ optional `token`), added alongside the existing host/port
+server-connection path. pymilvus is not installed in this environment, so
+these patch `connections` directly, following the pattern already used in
+test_milvus_store.py.
+"""
+
+from unittest.mock import patch
+
+from semantica.vector_store.milvus_store import MilvusStore, _redact_uri
+
+
+def test_redact_uri_strips_userinfo_credentials():
+ assert _redact_uri("https://user:pass@myhost:19530/db") == "https://myhost:19530/db"
+
+
+def test_redact_uri_strips_query_string_secrets():
+ assert _redact_uri("https://myhost:19530?token=secret") == "https://myhost:19530"
+
+
+def test_redact_uri_leaves_local_lite_path_unchanged():
+ # No scheme/netloc to redact -- a Milvus Lite file path carries no secrets.
+ assert _redact_uri("./milvus_demo.db") == "./milvus_demo.db"
+
+
+@patch("semantica.vector_store.milvus_store.connections")
+@patch("semantica.vector_store.milvus_store.MILVUS_AVAILABLE", True)
+def test_connect_logs_redacted_uri_not_raw_credentials(mock_connections):
+ store = MilvusStore(uri="https://user:s3cr3t@myhost:19530", token="tok")
+ with patch.object(store.logger, "info") as mock_info:
+ store.connect()
+
+ logged = " ".join(str(call) for call in mock_info.call_args_list)
+ assert "s3cr3t" not in logged
+ assert "myhost:19530" in logged
+
+
+@patch("semantica.vector_store.milvus_store.connections")
+@patch("semantica.vector_store.milvus_store.MILVUS_AVAILABLE", True)
+def test_connect_uses_uri_and_token_when_uri_given(mock_connections):
+ store = MilvusStore(uri="./milvus_demo.db", token="secret")
+ store.connect()
+
+ mock_connections.connect.assert_called_once()
+ _, kwargs = mock_connections.connect.call_args
+ assert kwargs["uri"] == "./milvus_demo.db"
+ assert kwargs["token"] == "secret"
+ assert "host" not in kwargs
+ assert "port" not in kwargs
+
+
+@patch("semantica.vector_store.milvus_store.connections")
+@patch("semantica.vector_store.milvus_store.MILVUS_AVAILABLE", True)
+def test_uri_wins_over_an_explicitly_set_host(mock_connections):
+ # uri must take precedence even when host/port are *explicitly* passed,
+ # not just when they're left at their defaults.
+ store = MilvusStore(host="explicit-host", port=9999, uri="./milvus_demo.db")
+ store.connect()
+
+ _, kwargs = mock_connections.connect.call_args
+ assert kwargs["uri"] == "./milvus_demo.db"
+ assert "host" not in kwargs
+ assert "port" not in kwargs
+
+
+@patch("semantica.vector_store.milvus_store.connections")
+@patch("semantica.vector_store.milvus_store.MILVUS_AVAILABLE", True)
+def test_uri_still_forwards_user_password_for_rbac(mock_connections):
+ # A self-hosted Milvus reached via uri (e.g. "http://host:19530") may use
+ # RBAC user/password rather than a token — those must not be dropped.
+ store = MilvusStore(uri="http://myserver:19530", user="alice", password="pw")
+ store.connect()
+
+ _, kwargs = mock_connections.connect.call_args
+ assert kwargs["uri"] == "http://myserver:19530"
+ assert kwargs["user"] == "alice"
+ assert kwargs["password"] == "pw"
+
+
+@patch("semantica.vector_store.milvus_store.connections")
+@patch("semantica.vector_store.milvus_store.MILVUS_AVAILABLE", True)
+def test_connect_falls_back_to_host_port_without_uri(mock_connections):
+ store = MilvusStore(host="localhost", port=19530)
+ store.connect()
+
+ mock_connections.connect.assert_called_once()
+ _, kwargs = mock_connections.connect.call_args
+ assert kwargs["host"] == "localhost"
+ assert kwargs["port"] == 19530
+ assert "uri" not in kwargs
+ assert "token" not in kwargs
+
+
+@patch("semantica.vector_store.milvus_store.connections")
+@patch("semantica.vector_store.milvus_store.MILVUS_AVAILABLE", True)
+def test_uri_and_token_flow_through_config_kwargs(mock_connections):
+ # Mirrors VectorStore(backend="milvus", config={...}) -> MilvusStore(**config)
+ store = MilvusStore(
+ **{"uri": "https://cluster.zillizcloud.com", "token": "tok", "dimension": 8}
+ )
+ store.connect()
+
+ _, kwargs = mock_connections.connect.call_args
+ assert kwargs["uri"] == "https://cluster.zillizcloud.com"
+ assert kwargs["token"] == "tok"