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."""
passThe 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




