Text2SQL¶

Use IBM watsonx.data intelligence to convert natural-language requests into SQL by using vectorized and enriched metadata as context — giving business users self-service access to governed relational and lakehouse data.

Product mapping

IBM watsonx.data intelligence — Text2SQL, natural-language query, vectorized metadata

GitHub Repository

The complete source code and examples are available in the GitHub repository:

Building Blocks - Text2SQL

Included Assets¶

`watsonx-text2sql` — Managed Text-to-SQL API¶

Built on the IBM watsonx.data intelligence managed Text-to-SQL API, using governed metadata as context for natural-language SQL generation.

Asset	Description
text_to_sql_app	FastAPI wrapper for the watsonx.data intelligence Text-to-SQL API with optional controlled SQL execution
metadata_enrichment_text2sql	Reference metadata-enrichment flow to improve Text-to-SQL context quality

flowchart TD
    Q["User question"]
    Q --> META["Governed metadata / examples\nIBM watsonx.data intelligence"]
    META --> API["Text-to-SQL API"]
    API --> GATE["SQL validation / policy gate"]
    GATE --> RET["return SQL"]
    GATE --> EXEC["optional controlled execution"]
    EXEC --> DB["IBM data source"]

`NL2SQL` — Custom NL-to-SQL with Schema Retrieval¶

A self-contained NL-to-SQL system using semantic schema retrieval and hardened read-only SQL execution, targeting PostgreSQL and IBM Db2.

Asset	Description
schema_retriever	FastAPI schema retriever using OpenSearch k-NN or pgvector for semantic schema lookup
sql_executor	FastAPI SQL executor with AST-based safety validation for read-only execution against PostgreSQL and Db2

flowchart TD
    Q["User question"]
    Q --> RETR["Schema Retriever (FastAPI)\nOpenSearch k-NN / pgvector"]
    RETR --> LLM["LLM SQL generation"]
    LLM --> EXSVC["SQL Executor (FastAPI)\nAST-based safety validation"]
    EXSVC --> DB["IBM data source\nPostgreSQL / Db2"]

Bob Modes¶

Mode	Description
Text-to-SQL	Natural language to SQL using IBM watsonx.data intelligence — FastAPI app, metadata enrichment (table/column descriptions, synonyms), and SQL accuracy evaluation

Bob Skills¶

Skill	Description
text2sql-metadata-enrichment	watsonx.data intelligence project onboarding, table/column description enrichment, synonym design, query example authoring, and accuracy measurement
text2sql-query-optimizer	Model selection, SQL safety validation, accuracy evaluation (exact-match + execution accuracy), error pattern diagnosis, and SQL dialect tuning

Installing skills and modes

Download the .zip files and copy the folders to ~/.bob/skills or ~/.bob/modes (global) or <project>/.bob/skills / <project>/.bob/modes (project-level). See the Data Skills and Modes page for full installation instructions.

Why It Matters¶

Most business users cannot write SQL. Analytical questions go unanswered or are queued to data teams, creating bottlenecks and delaying decisions. Text2SQL changes this by letting users ask questions in plain language, generating SQL behind the scenes and returning results through existing governed data infrastructure.

Text2SQL overview

Business Value¶

Key outcomes

Outcome	What It Means
Broaden data access	Users can express analytical intent without writing SQL by hand
Reduce routine analyst workload	Common exploratory queries can be generated faster, freeing analysts for higher-value work
Use governed metadata as context	Table and column descriptions plus business terms improve query generation quality
Keep SQL visible	Generated SQL can be reviewed, governed and executed through existing database controls
Accelerate self-service BI	Business users get answers in natural language while IT retains governance

When to Use¶

Text2SQL is a good fit when:

Business users need self-service access to relational data without SQL skills.
Data teams want to accelerate ad-hoc exploration while keeping SQL as the execution interface.
The schema is well-governed and metadata is enriched with meaningful descriptions and terms.

What Text2SQL is not

Do not treat Text2SQL as a replacement for authorization, row/column security, query limits or review of high-impact queries. Generated SQL must still flow through existing data access controls.

How It Works¶

IBM watsonx.data intelligence can vectorize project metadata for natural-language queries. The metadata is used to generate SQL based on available tables and columns. IBM documentation recommends metadata enrichment before using Text2SQL because enriched metadata adds descriptive, business-relevant context that directly improves generation quality.

flowchart LR
    U["User question"] --> T["watsonx.data intelligence<br/>Text2SQL"]
    M["Vectorized + enriched metadata"] --> T
    T --> S["Generated SQL"]
    S --> V["Validation / policy / review"]
    V --> D["Presto / Db2 / PostgreSQL / other supported source"]
    D --> R["Result"]

What to Demonstrate¶

Select a governed project with representative tables.
Show enriched table and column descriptions and business terms.
Ask a business question in natural language.
Show the generated SQL before execution.
Execute the query against a supported data source.
Refine the metadata and show how better descriptions improve results.

Best Practices¶

Metadata first, then Text2SQL

Enrich metadata before measuring Text2SQL quality.
Use clear business terms and examples for ambiguous metrics.
Keep a test set of expected questions and validate both SQL semantics and execution results.
Apply database-native authorization and query governance to all generated SQL.
Prefer read-only execution paths for broad self-service scenarios.

Demo Video¶

IBM Products Used¶

Product	Role
IBM watsonx.data intelligence — Text2SQL	Natural-language query generation using vectorized and enriched metadata as context
IBM watsonx.data intelligence — Metadata Enrichment	Provides business terms, descriptions and semantic context that improve Text2SQL quality