Skip to content

armgit / LEANN

Public Imported from GitHub
0

[MLsys2026 Best Paper]: https://arxiv.org/abs/2506.08276. RAG on Everything with LEANN. Enjoy 97% storage savings while running a fast, accurate, and 100% private RAG application on your personal device.

feat(cli): add --metadata-filters flag to leann search (#306)

Octopus3031b8ef34af
diff --git a/packages/leann-core/src/leann/cli.py b/packages/leann-core/src/leann/cli.py
index fec66f0..9f8280f 100644
--- a/packages/leann-core/src/leann/cli.py
+++ b/packages/leann-core/src/leann/cli.py
@@ -431,6 +431,17 @@ Examples:
default=True,
help="Enable/disable warmup when starting embedding server (default: enabled)",
)
+ search_parser.add_argument(
+ "--metadata-filters",
+ type=str,
+ default=None,
+ help=(
+ "Filter results by metadata fields (JSON string). "
+ 'Format: \'{"field": {"operator": value}}\'. '
+ "Operators: ==, !=, <, <=, >, >=, in, not_in, contains, starts_with, ends_with. "
+ 'Example: \'{"chapter": {"<=": 5}, "genre": {"==": "fiction"}}\''
+ ),
+ )
# Warmup command
warmup_parser = subparsers.add_parser("warmup", help="Warm up an index embedding server")
@@ -2615,6 +2626,22 @@ Examples:
if args.embedding_prompt_template:
provider_options["prompt_template"] = args.embedding_prompt_template
+ # Parse --metadata-filters JSON string
+ metadata_filters = None
+ raw_filters = getattr(args, "metadata_filters", None)
+ if raw_filters:
+ try:
+ metadata_filters = json.loads(raw_filters)
+ if not isinstance(metadata_filters, dict):
+ print(
+ "Error: --metadata-filters must be a JSON object, "
+ 'e.g. \'{"chapter": {"<=": 5}}\''
+ )
+ return
+ except json.JSONDecodeError as e:
+ print(f"Error: --metadata-filters is not valid JSON: {e}")
+ return
+
if json_mode:
sys.stdout.flush()
saved_fd = os.dup(1)
@@ -2638,6 +2665,7 @@ Examples:
recompute_embeddings=args.recompute_embeddings,
pruning_strategy=args.pruning_strategy,
provider_options=provider_options if provider_options else None,
+ metadata_filters=metadata_filters,
)
finally:
if json_mode:
diff --git a/tests/test_metadata_filtering.py b/tests/test_metadata_filtering.py
index cc6003c..4996964 100644
--- a/tests/test_metadata_filtering.py
+++ b/tests/test_metadata_filtering.py
@@ -340,6 +340,90 @@ class TestPassageManagerFiltering:
# Integration tests would go here, but they require actual LEANN backend setup
# These would test the full pipeline from LeannSearcher.search() with metadata_filters
+
+class TestCLIMetadataFilterParsing:
+ """Tests for CLI --metadata-filters argument parsing."""
+
+ def _parse_metadata_filters(self, raw_filters):
+ """Mirror the parsing logic from cli.py search_documents."""
+ import json
+
+ if not raw_filters:
+ return None
+ try:
+ parsed = json.loads(raw_filters)
+ if not isinstance(parsed, dict):
+ return "error: not a dict"
+ return parsed
+ except json.JSONDecodeError as e:
+ return f"error: {e}"
+
+ def test_valid_equality_filter(self):
+ raw = '{"genre": {"==": "fiction"}}'
+ result = self._parse_metadata_filters(raw)
+ assert result == {"genre": {"==": "fiction"}}
+
+ def test_valid_numeric_range_filter(self):
+ raw = '{"chapter": {"<=": 5}}'
+ result = self._parse_metadata_filters(raw)
+ assert result == {"chapter": {"<=": 5}}
+
+ def test_valid_compound_filter(self):
+ raw = '{"chapter": {"<=": 5}, "genre": {"==": "fiction"}}'
+ result = self._parse_metadata_filters(raw)
+ assert result == {"chapter": {"<=": 5}, "genre": {"==": "fiction"}}
+
+ def test_none_returns_none(self):
+ result = self._parse_metadata_filters(None)
+ assert result is None
+
+ def test_empty_string_returns_none(self):
+ result = self._parse_metadata_filters("")
+ assert result is None
+
+ def test_invalid_json_returns_error(self):
+ result = self._parse_metadata_filters("{not valid json}")
+ assert isinstance(result, str) and result.startswith("error:")
+
+ def test_non_dict_returns_error(self):
+ result = self._parse_metadata_filters("[1, 2, 3]")
+ assert result == "error: not a dict"
+
+ def test_filters_applied_to_results(self):
+ """Test that CLI-parsed filters actually work with MetadataFilterEngine."""
+ import json
+
+ engine = MetadataFilterEngine()
+ sample_results = [
+ {
+ "id": "doc1",
+ "score": 0.9,
+ "text": "Chapter 1 content",
+ "metadata": {"chapter": 1, "genre": "fiction"},
+ },
+ {
+ "id": "doc2",
+ "score": 0.8,
+ "text": "Chapter 6 content",
+ "metadata": {"chapter": 6, "genre": "fiction"},
+ },
+ {
+ "id": "doc3",
+ "score": 0.7,
+ "text": "Chapter 3 non-fiction",
+ "metadata": {"chapter": 3, "genre": "non-fiction"},
+ },
+ ]
+
+ # Parse filters as CLI would
+ raw = '{"chapter": {"<=": 5}, "genre": {"==": "fiction"}}'
+ filters = json.loads(raw)
+
+ results = engine.apply_filters(sample_results, filters)
+ assert len(results) == 1
+ assert results[0]["id"] == "doc1"
+
+
if __name__ == "__main__":
# Run basic smoke tests
engine = MetadataFilterEngine()
diff --git a/uv.lock b/uv.lock
index b7b693d..d251859 100644
--- a/uv.lock
+++ b/uv.lock
@@ -1,5 +1,5 @@
version = 1
-revision = 1
+revision = 3
requires-python = ">=3.10"
resolution-markers = [
"python_full_version >= '3.13'",