Permission-Aware Metadata Filter Generation Prompt

This prompt is designed for platform engineers building hybrid search systems where access controls are paramount. Its core job is to take a user's natural language query and their structured permission profile, then generate a complete, conflict-resolved metadata filter clause. This clause is ready to be applied directly to vector or keyword indexes, ensuring that the same query from different users retrieves only the documents they are authorized to see. Use this when your retrieval system must enforce strict, user-specific access boundaries at the index level, and you need a reliable, automated way to translate permissions into query-time filters.

The ideal user is an engineer integrating a large language model (LLM) into a retrieval pipeline for an enterprise application like a secure internal knowledge base, a compliance-sensitive document store, or a multi-tenant SaaS platform. Required context includes a well-defined metadata schema on your documents (e.g., department, classification, project_id) and a structured permission model for your users (e.g., { "departments": ["engineering", "product"], "clearance": "internal" }). The prompt is not a replacement for index-level security enforcement; it is a complementary layer that dynamically generates the correct filter syntax. Do not use this prompt for open-access knowledge bases, for generating the search query string itself, or as a standalone authorization service.

Before implementing, ensure you have a clear mapping between your permission model and your document metadata fields. A common failure mode is a mismatch where a user's permission attribute (e.g., group: eng-leads) does not directly correspond to a filterable metadata field on documents (e.g., audience: engineering-leadership). You must resolve this mapping logic, either in a pre-processing step or by providing a mapping schema as part of the prompt's [CONTEXT]. The prompt's value is in resolving conflicts—for instance, when a user with access to 'Sales' and 'Marketing' queries for 'Q3 reports,' it must generate a filter like (department:sales OR department:marketing) AND (type:report) AND (date:2024-Q3), not a contradictory or overly permissive clause.

To ship this safely, you must build a validation harness around the prompt's output. The generated filter string should be parsed and validated against your index's query syntax before execution. Implement automated tests with user profiles that have overlapping, minimal, and conflicting permissions to verify the prompt correctly handles filter conflict resolution and prevents over-permission. For high-risk domains, log every generated filter alongside the user's ID and query for audit trails. The next step is to integrate this prompt into your query rewriting pipeline, directly before the retrieval step, and monitor its performance with a specific focus on false-positive (over-permission) and false-negative (empty result set) rates.

The prompt below is designed to be copied directly into your application code. It takes a user's natural language query and their permission profile as input, then outputs a structured filter object that can be passed to a vector or keyword search index. Every placeholder is enclosed in square brackets and must be replaced with live data at runtime. The prompt enforces a strict output schema, resolves conflicts between user-derived filters and permission boundaries, and prevents over-permission by treating the permission profile as an absolute upper bound.

textCopy
You are a search filter generator for a permission-aware retrieval system. Your job is to analyze a user's query and their permission profile, then produce a complete metadata filter clause that respects access boundaries.

## INPUT
User Query: [USER_QUERY]
Permission Profile: [PERMISSION_PROFILE]
  - Allowed Document Scopes: [ALLOWED_SCOPES]
  - Denied Document Scopes: [DENIED_SCOPES]
  - User Role: [USER_ROLE]
  - Department: [USER_DEPARTMENT]
  - Clearance Level: [CLEARANCE_LEVEL]

## OUTPUT SCHEMA
Return a JSON object with the following structure:
{
  "filters": {
    "must": [
      {"field": "string", "operator": "eq|in|gte|lte|range", "value": "any"}
    ],
    "must_not": [
      {"field": "string", "operator": "eq|in", "value": "any"}
    ],
    "should": [
      {"field": "string", "operator": "eq|in", "value": "any", "boost": number}
    ]
  },
  "conflicts_resolved": [
    {"query_filter": "string", "permission_boundary": "string", "resolution": "string"}
  ],
  "warnings": ["string"]
}

## CONSTRAINTS
1. Extract all explicit metadata constraints from the user query (dates, document types, departments, authors, tags, categories, status fields).
2. The permission profile is the absolute upper bound. Any query-derived filter that exceeds the allowed scopes must be narrowed to the permission boundary.
3. If the user query requests a scope that is entirely denied, place it in `must_not` and add a warning.
4. If the user query is ambiguous about a filter field that has permission implications, default to the most restrictive interpretation.
5. `must` clauses are required matches. `must_not` clauses exclude documents. `should` clauses boost relevance without excluding.
6. Never generate a filter that would access documents outside [ALLOWED_SCOPES].
7. If no filters can be extracted from the query, return an empty `must` array and rely solely on permission-derived filters.
8. Document every conflict between query intent and permission boundaries in `conflicts_resolved`.

## EXAMPLES
Query: "Show me Q3 financial reports from the engineering team"
Permission: Allowed Scopes=["engineering", "product"], Denied=["finance", "hr"]
Output:
{
  "filters": {
    "must": [
      {"field": "document_type", "operator": "eq", "value": "report"},
      {"field": "department", "operator": "eq", "value": "engineering"},
      {"field": "date_range", "operator": "range", "value": {"gte": "2024-07-01", "lte": "2024-09-30"}}
    ],
    "must_not": [],
    "should": [
      {"field": "topic", "operator": "eq", "value": "financial", "boost": 0.5}
    ]
  },
  "conflicts_resolved": [
    {"query_filter": "financial reports", "permission_boundary": "finance scope denied", "resolution": "Moved 'financial' to should clause with reduced boost; restricted department to engineering only"}
  ],
  "warnings": ["Query requested financial content but user lacks finance scope access. Results limited to engineering department."]
}

Query: "Find all documents about project Alpha"
Permission: Allowed Scopes=["engineering"], Denied=[]
Output:
{
  "filters": {
    "must": [
      {"field": "project", "operator": "eq", "value": "Alpha"},
      {"field": "scope", "operator": "eq", "value": "engineering"}
    ],
    "must_not": [],
    "should": []
  },
  "conflicts_resolved": [],
  "warnings": []
}

## INSTRUCTIONS
Analyze the user query and permission profile. Extract filters, resolve conflicts, and return only the JSON object. Do not include explanations outside the JSON.

To adapt this prompt, replace each placeholder with live data from your application's authentication and authorization layer. The [PERMISSION_PROFILE] should be assembled from your identity provider or access control system before the prompt is rendered. The [ALLOWED_SCOPES] and [DENIED_SCOPES] arrays must be exhaustive for the current user session. If your search index uses a different filter syntax, modify the operator and value fields in the output schema to match your backend. The conflict resolution and warning fields are critical for auditability—do not remove them even if your initial use case does not require them, as they provide essential observability when filters behave unexpectedly in production.

This prompt is designed to sit between the user's natural language query and your search index. It should be treated as a pre-retrieval transformation step in a hybrid search pipeline. The application layer must supply two critical inputs: the raw user query and a structured permission profile object derived from the authenticated user's session. The prompt's output is a machine-readable filter clause, not a final answer, so it must be parsed, validated, and merged into the downstream search request before any documents are retrieved.

The implementation harness must enforce strict validation on the model's output. Parse the generated JSON and verify that every filter key matches your index's actual metadata schema. Reject any filter that references a field the user's permission profile does not explicitly grant access to. This is a hard security boundary: never pass an unvalidated model-generated filter directly to your database or search index. Implement a merge strategy where the user's base permission filters (e.g., department: [user_dept], classification: [user_clearance]) are AND-ed with the query-derived filters. If the model generates a filter that would broaden access beyond the user's entitlements, discard the conflicting clause and log the event as a potential over-permission attempt.

For retry logic, if the model returns malformed JSON or references unknown fields, retry once with a stricter prompt that includes the exact valid filter schema and the previous error message. If the retry also fails, fall back to using only the user's base permission filters without any query-derived constraints, and surface a non-blocking warning to the observability layer. Choose a fast, low-cost model for this task (e.g., a small fine-tuned model or a fast API endpoint) because this step adds latency to every search request. Cache the user's permission profile for the session to avoid repeated lookups, but never cache the generated filter across different queries or users. Log the raw query, the generated filter, the final merged filter, and any validation rejections for audit and debugging purposes.