Metadata Filter Extraction for Disambiguated Queries Prompt

This prompt is designed for platform engineers who have already resolved ambiguity in a user's natural language query. Its job is to extract structured metadata constraints—such as date ranges, source filters, categorical facets, and entity identifiers—from a disambiguated query and map them to a filter object compatible with vector database syntax (e.g., Pinecone, Weaviate, Qdrant, Elasticsearch). The prompt assumes the upstream disambiguation step has already resolved entity collisions, expanded acronyms, and normalized temporal expressions. Feeding it raw, ambiguous user input will cause the model to hallucinate constraints that were never confirmed, producing filter clauses that silently narrow or distort the retrieval scope.

Use this prompt when you have a resolved, unambiguous query string and need to generate a structured filter payload before executing a search. The ideal input is the output of a prior disambiguation or query rewriting step. The prompt expects placeholders for the resolved query text, a schema defining the valid filter fields and their types, and any domain-specific constraints (e.g., 'only filter on fields present in the index mapping'). The output should be a JSON object with keys like filter, must, must_not, or range that can be directly passed to your search backend's filter API. Do not use this prompt if the query still contains pronouns, vague temporal references like 'recently,' or entity names that could refer to multiple records. Those must be resolved first.

The most common production failure occurs when the prompt is applied to queries that appear disambiguated but still contain implicit constraints. For example, a query like 'show me active contracts' may have resolved the entity 'contracts' but still carries an implicit filter on status = active that the model must infer. Always validate the extracted filter against a known schema and reject filter clauses that reference fields not present in your index mapping. For high-stakes domains where an incorrect filter could exclude critical results, implement a human review step or a confidence threshold that escalates uncertain extractions. The next section provides the copy-ready prompt template you can adapt for your own filter schema and backend syntax.

This prompt template converts a disambiguated natural language query into a structured metadata filter object. It assumes that entity resolution and ambiguity handling have already occurred upstream. The prompt's job is to map resolved entities, temporal constraints, categorical facets, and source restrictions into a filter syntax compatible with common vector databases like Pinecone, Weaviate, Qdrant, or Milvus. Use this when your retrieval pipeline has a clear, unambiguous query string but needs explicit filter clauses to scope the search space before vector or keyword ranking.

textCopy
SYSTEM:
You are a metadata filter extraction engine for a hybrid search system. Your task is to analyze a disambiguated user query and extract all explicit and implied metadata constraints. Output only a valid JSON filter object. Do not include commentary, markdown fences, or additional text.

INPUT QUERY:
[DISAMBIGUATED_QUERY]

AVAILABLE METADATA FIELDS:
[AVAILABLE_FIELDS_SCHEMA]

OUTPUT SCHEMA:
{
  "filters": {
    "must": [
      {"field": "string", "operator": "eq|gte|lte|in|contains", "value": "string|number|array"}
    ],
    "must_not": [
      {"field": "string", "operator": "eq|gte|lte|in|contains", "value": "string|number|array"}
    ],
    "should": [
      {"field": "string", "operator": "eq|gte|lte|in|contains", "value": "string|number|array"}
    ]
  },
  "confidence": 0.0,
  "unmapped_constraints": ["string"]
}

RULES:
1. Extract only constraints that map to fields in AVAILABLE METADATA FIELDS.
2. Use "must" for hard constraints explicitly stated in the query.
3. Use "must_not" for explicit exclusions.
4. Use "should" for soft preferences or implied constraints.
5. Normalize temporal expressions to ISO 8601 date strings.
6. If a constraint cannot be mapped to any available field, add it to "unmapped_constraints".
7. Set "confidence" between 0.0 and 1.0 reflecting extraction certainty.
8. If no filters are extractable, return an empty "must" array with confidence 1.0.

EXAMPLES:
[FEW_SHOT_EXAMPLES]

USER:
[DISAMBIGUATED_QUERY]

To adapt this template, replace [DISAMBIGUATED_QUERY] with the resolved query string from your disambiguation step. Populate [AVAILABLE_FIELDS_SCHEMA] with a JSON schema or list describing the filterable metadata fields in your index, including field names, types, and valid values. For example: {"fields": [{"name": "source", "type": "string", "values": ["arxiv", "internal_wiki", "support_tickets"]}, {"name": "published_date", "type": "date"}, {"name": "author", "type": "string"}]}. Provide [FEW_SHOT_EXAMPLES] as 2-4 input-output pairs showing correct filter extraction for your domain's typical query patterns. This is critical for teaching the model your field naming conventions and operator preferences.

Before deploying, validate the output against your database's actual filter syntax. A common failure mode is the model inventing field names not present in [AVAILABLE_FIELDS_SCHEMA] or using operators your backend doesn't support. Add a post-processing validator that rejects filter objects with unknown fields or unsupported operators, logs the unmapped constraints, and falls back to an unfiltered search if confidence is below your threshold. For high-stakes domains, route outputs with confidence below 0.7 or non-empty unmapped_constraints to a human review queue before retrieval executes.

This prompt is designed to sit between a query disambiguation step and your search backend. It expects a resolved, unambiguous natural language query as input—not a raw user query. The upstream disambiguation process should have already resolved entity collisions, expanded acronyms, and grounded temporal expressions. Feeding an ambiguous query into this prompt will produce unreliable filter objects. The prompt's job is strictly to extract structured metadata constraints from the clarified query and map them to your search backend's filter syntax.

Integration flow: 1) User submits raw query. 2) Disambiguation prompt resolves entities, acronyms, and temporal references. 3) This prompt receives the disambiguated query and your filter schema definition. 4) The model outputs a JSON filter object. 5) A validator function checks the output against your schema before it touches the search backend. The validator should confirm that field names exist in your index mapping, value types match (string vs. integer vs. array), date ranges are well-formed, and no hallucinated fields appear. Reject and retry once if validation fails, including the validation error in the retry prompt. If the second attempt also fails, log the failure and fall back to a filter-free search rather than injecting a malformed filter.

Model choice and latency: This is a structured extraction task with a constrained output schema. Use a model with strong JSON mode or function-calling support (e.g., GPT-4o with response_format set to json_schema, Claude 3.5 Sonnet with tool use configured for the filter schema, or a fine-tuned smaller model if your filter taxonomy is stable). Latency is critical here because this prompt sits on the retrieval critical path. Cache the filter schema definition in the system prompt prefix to reduce per-request token processing. If your filter schema is large, consider shipping only the relevant subset based on the query domain rather than the full taxonomy.

Observability and debugging: Log the disambiguated query input, the raw model output, the validator result, and the final filter object applied to the search backend. When retrieval quality degrades, these logs let you trace whether the problem originated in disambiguation, filter extraction, or the search backend itself. Common failure modes include: the model inventing filter keys not present in your schema (caught by the validator), misinterpreting a content keyword as a metadata constraint (e.g., treating 'Q3 report' as a date filter when the user meant a document titled 'Q3 Report'), and over-constraining the filter such that zero results are returned. Monitor the rate of validator rejections and zero-result queries as leading indicators of prompt drift.

When to add product code instead: If your metadata taxonomy is small and stable (fewer than 20 filterable fields with well-defined value sets), a classifier or rule-based parser will be faster, cheaper, and more reliable than an LLM call. Reserve this prompt for cases where the filter schema is large, the mapping from natural language to metadata is non-obvious, or the upstream disambiguation step already justifies the LLM latency budget. Do not use this prompt for access control or permission filtering—those must be applied deterministically at the search backend based on authenticated user context, never derived from the query text.