liveBook · Manning

Metadata filter

As explained in Designing AI Systems

A metadata filter is a query condition that restricts candidate records according to descriptive key-value attributes.

A metadata filter restricts search candidates by descriptive key-value attributes. It complements semantic similarity when documents discuss the same subject but serve different audiences or departments. section 5.1 section 5.3.4

Restrict a support search

A customer-facing troubleshooting guide and an internal runbook may describe the same device reset. Filtering for audience: customer selects the customer-facing domain even when both documents are semantically similar. section 5.3.4

Document metadata includes attributes extracted during parsing, such as filename and ingestion timestamp, and caller-supplied attributes such as department, document type, and tags. A flat dictionary of string key-value pairs keeps custom metadata straightforward to store and filter across vector-store backends. Consistent naming matters: dept=engineering and department=eng will not produce reliable shared filters. An optional metadata schema can validate keys and values at ingestion. section 5.3.4

Listing 5.17 VectorStore abstract base class: search operation and result model
@dataclass
class SearchResult:
    chunk_id: str
    document_id: str
    text: str
    score: float    #A
    metadata: Dict[str, str]
 
class VectorStore(ABC):
    # ... write operations from Listing 5.16 ...
 
    @abstractmethod
    def search(
        self,
        index_name: str,
        query_embedding: List[float],
        top_k: int = 5,
        metadata_filters: Optional[Dict[str, str]] = None,
        score_threshold: Optional[float] = None
    ) -> List[SearchResult]:    #B
        """Find chunks most similar to the query embedding."""
        pass

The vector-store search interface accepts an optional metadata_filters dictionary alongside the index, query embedding, top-k limit, and score threshold. Results carry the chunk text, score, source document ID, and metadata. section 5.4.1

For example, metadata_filters={"department": "legal"} restricts results to chunks from legal documents. The similarity score threshold serves a different purpose: it discards matches below a quality floor, while top_k limits the number returned. section 5.4.1

Listing 5.19 pgvectorStore search implementation
class PgvectorStore(VectorStore):
 
    def __init__(self, connection_string: str):
        self.conn = psycopg2.connect(connection_string)
 
    def search(
        self,
        index_name: str,
        query_embedding: List[float],
        top_k: int = 5,
        metadata_filters: Optional[Dict[str, str]] = None,
        score_threshold: Optional[float] = None
    ) -> List[SearchResult]:
 
        query = """
            SELECT chunk_id, document_id, chunk_text, metadata,
                   1 - (embedding <=> %s::vector) AS score
            FROM chunks
            WHERE index_name = %s
        """    #A
        params = [query_embedding, index_name]
 
        if metadata_filters:
            for key, value in metadata_filters.items():
                query += " AND metadata->>%s = %s"
                params.extend([key, value])    #B
 
        if score_threshold:
            query += " AND 1 - (embedding <=> %s::vector) >= %s"
            params.extend
➥([query_embedding, score_threshold])    #C
 
        query += " ORDER BY embedding <=> %s::vector LIMIT %s"
        params.extend([query_embedding, top_k])    #D
 
        cursor = self.conn.cursor()
        cursor.execute(query, params)
 
        return [
            SearchResult(
                chunk_id=row[0], document_id=row[1],
                text=row[2], metadata=row[3], score=row[4]
            )
            for row in cursor.fetchall()
        ]

In the pgvector implementation, each metadata key-value pair adds a parameterized condition to the SQL WHERE clause. PostgreSQL applies those conditions with the index restriction, then ranks and limits the remaining matches. section 5.4.3

How Designing AI Systems covers it

How deep it goes
Defines a search interface and illustrates SQL filtering, while leaving vector indexing and similarity internals backend-dependent.
Examples
Uses customer versus internal device-reset documents and a legal-department search to illustrate attribute restrictions.
What you can do after
Apply metadata filters through a vector-store search interface and understand their pgvector query implementation.
How it connects
Connects semantic search, document ingestion, vector stores, and retrieval-augmented generation.

Also explained in

Compare how 5 books explain metadata filter →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Designing AI Systems. The section links point to the parts of the book it draws on.