Chapter 4: Generating Cypher queries from natural language questions

Introduction

This chapter introduces generating Cypher queries from natural-language questions to make knowledge-graph retrieval more flexible and dynamic.

• Natural-language Cypher generation: Explain that the chapter moves from hardcoded Cypher queries to generating Cypher queries from natural-language questions. State that this enables retrieval to adapt to different questions and knowledge graphs.
  Why it matters: Generating queries from questions lets a GraphRAG retriever access graph data without requiring a predefined query for every question type.
• Chapter implementation scope: Describe the chapter's stated progression: query-language-generation basics, its place in RAG, useful prompting practices, a base-model text2cypher implementation, and specialized finetuned LLMs. State that the implementation uses the Movies dataset.
  Why it matters: This roadmap distinguishes the conceptual, prompting, implementation, and model-specialization parts of the chapter.

Key terms: Cypher queries, natural language questions, text2cypher, hardcoded Cypher queries, retrieval system, query language generation, text2cypher retriever, base model, specialized (finetuned) LLMs, Movies dataset

4.1 The basics of query language generation

This section defines text-to-Cypher generation, explains why graph schema is essential for accurate queries, and outlines the generation workflow.

• Text-to-Cypher generation purpose: Explain query language generation as converting a natural-language question into an executable database query, specifically a Cypher query for a knowledge graph.
  Why it matters: This is the foundation for using an LLM to retrieve graph data through precise database queries.
• Schema-guided query accuracy: Describe why a generated Cypher query must be both syntactically correct and relevant to the question, and explain how the knowledge-graph schema maps question semantics to actual node labels, relationship types, properties, and valid connections.
  Why it matters: A schema prevents the LLM from guessing graph vocabulary and structure that do not exist in the database.
• Text-to-Cypher workflow steps: Trace the workflow for generating a Cypher query: obtain the user question and graph schema, assemble optional terminology mappings, format instructions, and few-shot examples, build the prompt, and send it to the LLM for Cypher generation.
  Why it matters: The workflow shows that reliable query generation depends on preparing grounded prompt context before calling the LLM.

Key terms: query language generation, Cypher queries, natural language questions, knowledge graph, schema, graph model, node labels, relationship types, properties, semantics

4.2 Where query language generation fits in the RAG pipeline

This section explains when text2cypher retrieval belongs in a RAG pipeline: for graph questions that require structured querying or aggregation rather than similarity search alone.

• Limits of similarity retrieval: Distinguish questions that vector similarity search can answer from questions that require a generated Cypher query. Explain that similarity search retrieves semantically similar graph content, but cannot fulfill requests requiring a specific database query and aggregation.
  Why it matters: Choosing the wrong retrieval method can prevent a RAG system from answering an otherwise answerable question.
• Cypher aggregation queries: Describe how generated Cypher can answer a question such as listing Steven Spielberg's three highest-rated movies and their average score. State that the query aggregates and ranks graph data rather than merely retrieving similar nodes.
  Why it matters: Cypher generation lets the RAG application obtain precise structured results from a knowledge graph.
• Text2cypher retriever role: Explain that text2cypher can be one retriever among multiple retrievers in a RAG system and can serve as a catchall when no other retriever is a good fit for a user question.
  Why it matters: A system with several retrieval options can route each question to the approach most likely to produce a useful answer.

Key terms: vector similarity search, Cypher, text2cypher, aggregation, generated Cypher, knowledge graph, catchall retriever, retrievers, agentic system

4.3 Useful practices for query language generation

This section introduces practices for improving the correctness and relevance of Cypher queries generated by LLMs from natural-language questions.

• Text2Cypher error risks: Explain why LLM-generated Cypher queries can be incorrect or irrelevant, particularly for complex or ambiguous questions and schemas whose elements do not have semantically meaningful names.
  Why it matters: Recognizing these failure conditions explains why text2cypher generation needs additional guidance rather than relying on an LLM alone.
• Query generation quality practices: Describe the purpose of applying useful practices during natural-language-to-Cypher generation: to make generated queries correct and relevant.
  Why it matters: The practices in the following subsections are all intended to improve the quality of generated database queries.

Key terms: Cypher queries, natural language questions, database schema, schema elements, query language generation, correct, relevant

4.3.1 Using few-shot examples for in-context learning

This section explains how manually supplied, graph-specific question-and-Cypher examples help an LLM generate better Cypher queries through in-context learning.

• Few-shot in-context learning: Explain how few-shot prompting gives an LLM several natural-language questions paired with their Cypher queries so it can generate similar queries for new questions. Distinguish this from zero-shot prompting, where the model receives no examples or hints.
  Why it matters: Examples provide concrete patterns that can make text2cypher generation more reliable than asking the model to infer everything without guidance.
• Graph-specific error correction: Describe why few-shot examples must be created manually for the particular knowledge graph being queried. Explain that they are especially useful for correcting recurring schema misinterpretations, such as treating a graph traversal as a node property.
  Why it matters: A well-chosen example can correct a repeated query-generation failure for a graph's actual structure rather than merely fixing one wording of one question.
• Country relationship query pattern: Trace the example pattern for asking a movie's country of production: match the Movie by its title, traverse the PRODUCED_IN relationship to a Country node, and return the country's name. Explain that this example can generalize to similar country questions, not just the named movie in the example.
  Why it matters: This concrete pattern shows how an example teaches the model to use the graph's relationship structure instead of querying a nonexistent movie property.

Key terms: few-shot examples, in-context learning, zero-shot examples, text2cypher, knowledge graph, schema, property, traversal, Movie, Country

4.3.2 Using database schema in the prompt to show the LLM the structure of the knowledge graph

This section shows how to ground text-to-Cypher generation in an explicit graph schema, infer that schema from Neo4j, and format it for an LLM prompt.

• Schema-grounded Cypher prompting: Explain why a knowledge graph schema should be included in a text-to-Cypher prompt. State that the prompt identifies available node labels, relationship types, and properties, and instructs the LLM to use only those supplied schema elements.
  Why it matters: Schema grounding reduces the chance that an LLM invents graph elements that do not exist when generating Cypher.
• Schema exposure and sampling: Describe the trade-off in exposing or inferring a graph schema for the prompt. Explain that complete schema exposure depends on schema size and use-case relevance, and that sampling the database before schema inference is common because automatic inference can be expensive on large data.
  Why it matters: Choosing a relevant sampled schema can make schema grounding practical for large knowledge graphs.
• Neo4j schema extraction workflow: Trace the workflow for producing a prompt-ready schema string from Neo4j: use APOC procedures to infer the schema, run and store the results in a structured form, then format that structured response into the desired schema string. State that APOC is free and available in Aura and other Neo4j distributions.
  Why it matters: This workflow turns the actual database structure into reusable prompt context for text-to-Cypher generation.

Key terms: schema, node labels, relationship types, properties, Cypher, complete knowledge graph, schema inference, sample the database, Neo4j, APOC library

4.3.3 Adding terminology mapping to semantically map the user question to the schema

This section explains how graph-specific terminology mappings in the prompt help an LLM translate user wording into the correct knowledge-graph schema terms.

• Terminology mapping purpose: Explain how terminology mappings help an LLM connect words in a natural-language question to the appropriate labels, relationship types, or properties in a graph schema.
  Why it matters: Mappings reduce incorrect Cypher queries caused by the model misunderstanding how user language corresponds to the schema.
• Graph-specific mapping examples: Describe the example mappings in which a person described by trade maps to a Person node and a film or movie maps to a Movie node.
  Why it matters: Concrete mappings show the kind of prompt guidance that prevents the LLM from choosing the wrong schema label for synonymous user terms.
• Mapping maintenance and scope: Explain why terminology mappings should be included in the prompt for a specific knowledge graph and updated as query-generation problems reveal schema misunderstandings.
  Why it matters: Treating mappings as graph-specific, evolving prompt content helps maintain query accuracy as real failures are discovered.

Key terms: terminology mappings, schema, labels, relationship types, properties, Person, Movie, node label, terminology mapping, knowledge graph specific

4.3.4 Format instructions

This section shows how explicit prompt format instructions make text2cypher LLM outputs consistently usable as raw Cypher queries.

• Cypher output format control: Explain why format instructions are added to a text2cypher prompt and state the required output constraints: return only the generated Cypher statement, with no surrounding text or code blocks.
  Why it matters: Consistent raw-Cypher output makes an LLM response easier to pass directly to a database query workflow.

Key terms: format instructions, Cypher statement, code blocks

4.4 Implementing a text2cypher generator using a base model

This section puts text2cypher prompting into practice by assembling a base-model prompt from graph guidance and using it to generate a Cypher statement.

• Text2cypher prompt assembly: Describe how to form a text2cypher prompt for a base LLM by combining the graph schema, terminology mappings, format instructions, few-shot examples, and the user's question.
  Why it matters: A complete prompt makes the intended graph query task clear enough for a general-purpose LLM to attempt Cypher generation.
• Schema-bound Cypher generation: Explain that the prompt instructs the model to generate a Cypher statement using only relationship types and properties supplied in the graph database schema.
  Why it matters: Restricting the generated query to the supplied schema helps prevent it from inventing graph structure.
• Terminology-to-schema translation: Describe how terminology mappings connect words in a user's question, such as actor or film, to the graph's schema labels, such as Person or Movie.
  Why it matters: Terminology mappings help the model interpret user vocabulary in terms of the labels used by the knowledge graph.
• Cypher-only response format: State that the format instructions require only the generated Cypher statement, with no explanations, apologies, code blocks, or responses to requests outside Cypher construction.
  Why it matters: A Cypher-only response is easier for an application to use directly as the generated database query.

Key terms: text2cypher generator, base model, schema, terminology mapping, few-shot examples, format instructions, Cypher statement, graph database schema, relationship types, properties

4.5 Specialized (finetuned) LLMs for text2cypher

This section introduces Neo4j's specialized finetuned text2cypher models, their efficiency tradeoff against larger models, and prompt practices that can improve them.

• Neo4j text2cypher resources: Describe the specialized text2cypher resources Neo4j provides, including open-source training data and finetuned models based on open-source LLMs.
  Why it matters: These resources provide starting points for using or investigating models tailored to natural-language-to-Cypher generation.
• Specialized model tradeoff: Explain the performance and efficiency tradeoff of Neo4j's finetuned open-source text2cypher models relative to finetuned larger GPT and Gemini models, including when the smaller models are useful.
  Why it matters: A model that is less capable but faster can be the practical production choice when large models are too slow.
• Prompting specialized models: Apply the prompt practices from this chapter to improve a specialized text2cypher model: few-shot examples, database schema, terminology mappings, and format instructions.
  Why it matters: Finetuning does not eliminate the need to give a text2cypher model the examples, graph context, vocabulary translation, and output constraints it needs.

Key terms: text2cypher, finetuning, open source training data, Gemma2, Llama 3.1, finetuned models, GPT, Gemini, efficiency, production systems

4.6 What we’ve learned and what text2cypher enables

This section summarizes how to build and iteratively improve a text2cypher retriever that generates reliable Cypher queries for a knowledge graph.

• Text2cypher retriever implementation: Describe what a text2cypher retriever enables: generating correct Cypher queries for a wide range of natural-language questions against a knowledge graph.
  Why it matters: A reliable text2cypher retriever lets a RAG application retrieve graph data through structured Cypher queries.
• Prompt-based query improvement: Explain how few-shot examples, database schema, terminology mappings, and format instructions improve text2cypher query generation.
  Why it matters: These prompt inputs guide the model toward queries that match the graph's structure and expected output format.
• Iterative example refinement: Trace the improvement loop for a text2cypher retriever: identify question types it struggles with, add few-shot examples for those cases, and observe more correct and reliable generated queries over time.
  Why it matters: Targeting observed failures with examples provides a practical path to making the retriever more reliable.

Key terms: text2cypher retriever, Cypher queries, knowledge graph, few-shot examples, schema, terminology mappings, format instructions, prompt, generated queries, retriever

4.7 Summary

This summary positions text2cypher query generation as a complementary RAG retriever and recaps prompt-based and finetuned approaches for producing Cypher queries.