Structured JSON Filter Output Prompt Template

This prompt is for developers and platform engineers who need to translate a natural language query into a validated, structured JSON filter object that can be directly consumed by a search API such as Elasticsearch, OpenSearch, or a custom backend. The core job-to-be-done is bridging the gap between unstructured user input and the strict, typed filter clauses required by a search index. The ideal user is someone integrating an LLM into a retrieval pipeline where vector search alone is insufficient, and they need reliable metadata constraints to narrow the result set.

Use this prompt when you have a defined metadata schema and a search API that accepts structured filters. It is appropriate when the user's query implies constraints on fields like date ranges, categories, authors, or statuses. Do not use this prompt for generating the main search query text or vector; it is designed exclusively for the filter sidecar. It is also not a replacement for a full query parser. If your use case involves complex boolean logic with deeply nested AND/OR conditions, you should pair this prompt with the 'Combined AND/OR Filter Logic Prompt Template' and ensure your downstream system can execute the generated structure without security risks.

Before implementing, confirm that you have a strict output schema defined, a validation function ready to check operator correctness and field existence, and a clear policy for handling low-confidence or un-mappable constraints. The prompt includes a placeholder for a confidence threshold, which you should calibrate against a golden dataset of query-filter pairs. For high-stakes applications where a bad filter could hide critical information, always route low-confidence outputs for human review. The next step is to copy the prompt template, wire it into your application harness, and run it against your evaluation set to measure filter accuracy and schema compliance.

This template is designed to be the core instruction set you send to an LLM when you need to convert a user's natural language query into a structured JSON filter object. The output is intended for direct consumption by search backends like Elasticsearch, OpenSearch, or custom APIs. The prompt uses square-bracket placeholders to make it adaptable to your specific data schema, output requirements, and operational constraints without rewriting the core logic.

codeCopy
You are a search filter extraction engine. Your task is to analyze a user's natural language query and extract any explicit or implicit metadata constraints into a structured JSON filter object.

Your output must be a single, valid JSON object conforming to the provided [OUTPUT_SCHEMA]. Do not include any explanatory text, markdown fences, or code blocks outside the JSON object itself.

### INPUT QUERY
[USER_QUERY]

### AVAILABLE METADATA FIELDS
You may only generate filters for the following fields. If a constraint in the query does not map to one of these fields, ignore it.
[AVAILABLE_FIELDS]

### OUTPUT SCHEMA
Your JSON output must strictly follow this structure. Use `null` for any fields that have no applicable filter.
[OUTPUT_SCHEMA]

### OPERATOR AND VALUE RULES
- For text fields, use operators: `equals`, `contains`, `starts_with`, `in`.
- For date fields, use operators: `equals`, `before`, `after`, `between`. Always format dates as ISO 8601 strings (YYYY-MM-DD).
- For numeric fields, use operators: `equals`, `greater_than`, `less_than`, `between`.
- For categorical fields, use the operator `in` with an array of allowed values.
- Resolve all relative time expressions (e.g., 'last week', 'this year') into absolute ISO 8601 dates, using [ANCHOR_DATE] as 'today'.
- If a constraint is ambiguous or cannot be resolved with high confidence, set the `confidence` for that filter clause to a value between 0.0 and 0.5.

### EXAMPLES
[FEW_SHOT_EXAMPLES]

### CONSTRAINTS
[CONSTRAINTS]

To adapt this template, start by defining your [AVAILABLE_FIELDS] as a precise list of field names, types, and allowed values. The [OUTPUT_SCHEMA] should be a JSON Schema or a detailed example that dictates the exact structure your application parser expects, including a confidence field for each filter clause. The [FEW_SHOT_EXAMPLES] are critical for teaching the model how to handle edge cases like conflicting constraints or ambiguous language; include at least one example where no filter is generated and one where a relative time expression is resolved. The [CONSTRAINTS] placeholder is where you add final guardrails, such as 'Do not invent dates' or 'If a filter value is not in the allowed list for a categorical field, omit it and set confidence to 0.0'. After generating the output, your application harness must validate the JSON structure, confirm all field names are in the allowed list, and check operator-value type compatibility before sending the filter to your search backend.

The structured JSON filter output prompt is designed to sit between a natural language interface and a search backend like Elasticsearch, OpenSearch, or a custom API. Its job is to extract metadata constraints from user queries and produce a validated JSON filter object. In a production harness, this prompt is not a standalone endpoint—it is a component inside a retrieval pipeline that must handle schema validation, operator correctness, and graceful degradation when extraction confidence is low.

Wire the prompt into your application by placing it after query intake and before search execution. The typical flow: receive the user query, assemble the prompt with the query inserted into the [QUERY] placeholder and your metadata schema injected into [METADATA_SCHEMA], call the LLM, parse the JSON response, and validate it against your expected filter schema before passing it to the search backend. Validation is mandatory. Check that all field names exist in your actual index mapping, that operators (eq, gte, lte, in, range) are supported by your backend, and that value types match the field definitions. Reject or repair any filter object that references unknown fields or uses unsupported operators. Log every extraction attempt—including the raw query, the extracted filter, validation results, and the final filter sent to search—so you can debug extraction failures and measure precision/recall over time.

For high-reliability deployments, implement a retry-and-escalation pattern. If the LLM returns malformed JSON, retry once with a repair prompt that includes the original query, the schema, and the specific parse error. If the filter fails schema validation, retry with the validation errors injected as [CONSTRAINTS]. If confidence scores are part of your output schema, route low-confidence extractions to a human review queue or fall back to a broader search without filters. Avoid silently applying incorrect filters—an overly restrictive filter that excludes relevant documents is worse than no filter at all. When integrating with Elasticsearch, map the extracted filter directly into a bool query's filter clause to avoid scoring interference. For vector databases like Pinecone, translate the filter into their native metadata syntax before execution. Always test with edge cases: empty queries, queries with no filterable constraints, ambiguous entity names, and queries that mention fields outside your schema.