Synonym Expansion with Knowledge Graph Traversal Prompt

This prompt is for retrieval engineers and RAG developers who have access to a structured knowledge graph—such as a product catalog, internal ontology, or domain-specific entity store—and need to expand user queries with terms that are semantically linked, not just textually similar. The core job-to-be-done is improving recall in vector and keyword search systems by traversing explicit relationships (e.g., has_alias, is_child_of, is_related_to) to find synonyms, hyponyms, and conceptual alternatives that a naive embedding model or thesaurus would miss. You use this prompt when your retrieval system is underperforming on domain-specific terminology, product name variants, or entity aliases that are defined in your graph but absent from general-purpose language models.

The ideal user is a search infrastructure engineer or RAG pipeline owner who can supply a serialized subgraph snapshot as part of the prompt context. This is not a prompt for teams without a knowledge graph; if you lack structured entity relationships, use the standard Synonym Expansion Prompt Template for Keyword Search instead. You should also avoid this prompt when the user query contains no recognizable entities from your graph, as traversal will produce noise rather than signal. The prompt requires you to define a maximum traversal depth to prevent runaway expansion, and it expects you to provide an output schema that captures the traversal path for each suggested term so that downstream re-rankers or explainability modules can attribute why a term was added.

Before wiring this into production, you must decide how the knowledge graph subgraph is fetched and injected into the prompt. A typical implementation queries the graph database with the extracted entities from the user's original query, retrieves the N-hop neighborhood, and serializes it as a structured JSON or edge list in the prompt's [KNOWLEDGE_GRAPH_CONTEXT] placeholder. You should also implement a pre-retrieval entity extraction step to identify which nodes to start traversal from. If your graph is large, set a strict depth limit (start with 2) and a maximum node count to keep latency predictable. Validate outputs against a golden set of query-expansion pairs to catch over-traversal, where the prompt follows relationships too far and introduces irrelevant concepts that degrade precision. For high-stakes regulated domains, log the full traversal path for every expanded term and require human review of the expansion logic before enabling automatic retrieval.

The following prompt template is designed to be copied directly into your prompt management system, IDE, or orchestration layer. It accepts a user query and a serialized knowledge graph, then produces a structured set of expanded terms by traversing entity relationships, aliases, and linked concepts. The template uses square-bracket placeholders for all dynamic inputs, making it safe to store in version control and inject at runtime. Before using it in production, replace each placeholder with your application's data and configure the traversal depth and output schema to match your retrieval backend's requirements.

textCopy
You are a query expansion engine that traverses a knowledge graph to find synonyms, aliases, and related concepts for search retrieval.

## INPUT
User Query: [USER_QUERY]
Knowledge Graph (JSON): [KNOWLEDGE_GRAPH]

## TRAVERSAL RULES
- Traverse up to [MAX_TRAVERSAL_DEPTH] hops from each identified entity.
- Follow relationship types: [ALLOWED_RELATIONSHIP_TYPES].
- Do not follow relationship types: [BLOCKED_RELATIONSHIP_TYPES].
- For each hop, collect: preferred labels, aliases, and [ADDITIONAL_PROPERTIES_TO_COLLECT].
- Stop traversal if a node's relevance score falls below [RELEVANCE_THRESHOLD].

## OUTPUT SCHEMA
Return a JSON object with this exact structure:
{
  "expanded_terms": [
    {
      "term": "string",
      "source_entity": "string",
      "traversal_path": ["entity_a", "entity_b"],
      "hop_distance": integer,
      "relationship_type": "string",
      "confidence": float
    }
  ],
  "rejected_terms": [
    {
      "term": "string",
      "rejection_reason": "string"
    }
  ]
}

## CONSTRAINTS
- [CONSTRAINTS]
- If no valid expansions are found, return an empty expanded_terms array.
- Do not invent terms not present in the knowledge graph.
- Preserve the original query entities without modification.

## EXAMPLES
[FEW_SHOT_EXAMPLES]

## RISK LEVEL
[RISK_LEVEL]

To adapt this template, start by defining your knowledge graph serialization format. The [KNOWLEDGE_GRAPH] placeholder expects a JSON structure containing nodes, edges, and properties. For Neo4j-backed systems, you might inject a subgraph extracted via Cypher. For RDF stores, a SPARQL CONSTRUCT result serialized as JSON-LD works well. The [MAX_TRAVERSAL_DEPTH] parameter is your primary cost and relevance control: start with a depth of 2 for most domains, then adjust based on graph density and retrieval latency budgets. The [ALLOWED_RELATIONSHIP_TYPES] and [BLOCKED_RELATIONSHIP_TYPES] arrays let you constrain traversal to semantically meaningful edges—for example, allowing skos:broader, skos:narrower, and owl:sameAs while blocking administrative or provenance relationships that add noise.

The output schema enforces per-term provenance through the traversal_path and source_entity fields. This is critical for debugging, audit, and downstream re-ranking. When a re-ranker sees that a document matched because of a term three hops away with low confidence, it can down-weight that match. The rejected_terms array is equally important: it captures terms the model considered but excluded, along with a reason. In production, log these rejections to detect when your traversal rules or relevance thresholds are too aggressive. If you see high-confidence terms repeatedly rejected, your [RELEVANCE_THRESHOLD] or [BLOCKED_RELATIONSHIP_TYPES] likely need tuning.

Before deploying, validate the output against your schema in the application layer, not just in the prompt. A common failure mode is the model returning a slightly different JSON structure—missing the rejected_terms array or using distance instead of hop_distance. Implement a JSON Schema validator in your harness that rejects malformed responses and triggers a retry with a corrected example. For high-risk domains where incorrect expansions could surface irrelevant or misleading documents, add a human review step for terms with confidence below 0.7 or hop distances above 2. Wire this prompt into your retrieval pipeline after query cleaning but before vector or keyword search execution, and log every expansion with the original query for offline eval and regression testing.

The knowledge graph traversal prompt is not a standalone query rewriter; it is a structured data retrieval step that must be integrated into a broader search pipeline. The prompt expects a serialized subgraph—typically a JSON object containing nodes, edges, aliases, and relationship types—alongside the user's original query and a traversal depth parameter. Before calling the LLM, your application must query your graph database (e.g., Neo4j, Amazon Neptune, or a custom entity index) to extract the relevant subgraph centered on entities detected in the user query. This subgraph becomes the [KNOWLEDGE_GRAPH] input. The LLM then traverses this provided structure to generate expanded terms, synonyms, and related concepts, attributing each expansion to a specific graph path. The output is a structured JSON payload containing expanded terms, their source paths, and confidence indicators.

To wire this into an application, implement a pre-call validation layer that checks: (1) the subgraph is not empty or trivially small, (2) the detected entities in the query have corresponding nodes in the subgraph, and (3) the traversal depth parameter is within configured bounds (typically 1–3 hops). After the LLM returns, validate the output JSON against a strict schema that requires each expanded term to include a source_path (the sequence of nodes and edges traversed), a term string, and a confidence score between 0 and 1. Reject any expansion that lacks a complete path back to an original query entity. For high-recall applications, implement a retry loop with exponential backoff (max 3 attempts) when validation fails or the model returns malformed JSON. Log every call—including the subgraph size, traversal depth, generated terms, and validation results—to your observability platform for later recall impact analysis and prompt debugging.

Model choice matters here. This prompt requires strong instruction-following and structured output discipline. Use models with native JSON mode support (e.g., GPT-4o with response_format, Claude 3.5 Sonnet with tool-use schemas) rather than open-weight models without fine-tuning for graph traversal tasks. If you must use a smaller model, implement a post-processing step that verifies every returned path exists in the original subgraph by walking the node and edge IDs. For regulated or high-stakes domains, route expansions with confidence below 0.7 to a human review queue before they enter the retrieval pipeline. Never inject unverified graph-traversal expansions directly into a search query without path attribution—downstream re-rankers and citation systems need provenance to weight expanded terms appropriately against original query terms.