> For the complete documentation index, see [llms.txt](https://docs.buildings.ability.abb/collection/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.buildings.ability.abb/collection/academy/building-intelligence-ai-and-machine-learning-in-buildingpro-suites/agents/nl2sql.md).

# NL2SQL

Natural Language to SQL (NL2SQL) is the task of converting a user's plain-language\
question into a valid, executable SQL query against a specific database schema.

The motivation is straightforward: SQL is the standard interface for relational databases, but most users, particularly business users in operational roles, do not write SQL. \
They think in domain concepts ("What is the energy usage in Building A?"), not in joins, aggregations, and WHERE clauses.

Creating an Interface to interact with a database in natural language is an important step to provide non-technical users an easier access to data. 

Several alternative approaches exist for giving non-technical users access to structured data:

* **Dashboards and reports** cover known, recurring questions well but cannot handle ad-hoc exploration. Every new question requires someone to build a new view.
* **Graphical query builders** offer flexibility but still require users to understand the underlying data model: which tables exist, how they relate, what fields mean.
* **Tool calling** (where an LLM generates tool calls instead of SQL) works for simple lookups but constrains the query space to whatever the API surface exposes. Complex aggregations, joins across multiple entities, or time-series analysis with custom bucketing are difficult to express through predefined functions and their parameters and greatly reduce the flexibility.

NL2SQL removes these constraints. A well-implemented NL2SQL system allows users\
to ask arbitrary analytical questions in natural language and receive results grounded in what the actual database contains, with the full expressiveness of SQL available behind the scenes.

The NL2SQL solution space spans a spectrum from lightweight prompting to dedicated model training:

| Approach            | How it works                                                      | Strengths                                       | Limitations                                                                                       |
| ------------------- | ----------------------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Zero-shot prompting | Provide the full schema in the LLM prompt; ask for SQL            | No training needed; works immediately           | Breaks on complex or larger schemata; context window limits; poor on domain-specific syntax       |
| Few-shot prompting  | Add example question->SQL pairs to the prompt                     | Improves pattern coverage for known query types | Limited by context window; examples may not generalize                                            |
| RAG-augmented       | Dynamically retrieve relevant schema fragments or example queries | Scales to larger schemas; adaptive              | Retrieval quality becomes the bottleneck; still relies on the base model's SQL generation ability |
| Fine-tuned model    | Train a model on question->SQL pairs for the target schema        | Highest accuracy on the target domain           | Requires curated training data; needs retraining when schema changes significantly                |

No single approach dominates in all scenarios. The right choice depends on schema complexity, query diversity, accuracy requirements, and operational constraints (latency, hosting, data privacy).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.buildings.ability.abb/collection/academy/building-intelligence-ai-and-machine-learning-in-buildingpro-suites/agents/nl2sql.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.