[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.
Python aifaissgpt-osslangchainllama-indexllmlocalstorageoffline-firstollamaprivacypythonragretrieval-augmented-generationvector-databasevector-searchvectors
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.pyindex 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 commandwarmup_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.pyindex 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 testsengine = MetadataFilterEngine()diff --git a/uv.lock b/uv.lockindex b7b693d..d251859 100644--- a/uv.lock+++ b/uv.lock@@ -1,5 +1,5 @@version = 1-revision = 1+revision = 3requires-python = ">=3.10"resolution-markers = ["python_full_version >= '3.13'",