Oracle Cloud Infrastructure Documentation

SQL Search (NL2SQL)

Use SQL Search (NL2SQL) to convert natural-language requests into validated SQL for enterprise data in OCI Generative AI.

NL2SQL helps Enterprise AI Agents work with federated enterprise data without moving or copying the underlying data. It uses a semantic enrichment layer to map business terms to database fields, tables, and joins, and then generates SQL from natural-language input.

NL2SQL generates SQL only. It doesn't execute the query.

Before you Begin

Before using NL2SQL, create a database and configure the required database connections.

At minimum, you need:

  • A source Oracle Autonomous Database
  • A Database Tools service enrichment connection
  • A Database Tools service query connection

Create a Semantic Store

To use NL2SQL, create an OCI Semantic Store resource.

A Semantic Store is backed by a vector store with structured data and includes two DBTools connections:

  • Enrichment Connection
  • Query Connection

In the Console

In the Console, create a vector store and select Structured data. When you select Structured data, the Semantic Store configuration options appear, including the enrichment settings and the database connection details.

By Using the OCI Generative AI API

In the OCI Generative AI API, create a Semantic Store by using the CreateSemanticStore operation.

Base URL Endpoint Path Authentication
https://generativeai.${region}.oci.oraclecloud.com/20231130 /semanticStores IAM session only

The CreateSemanticStore API is part of the OCI Generative AI service API and uses OCI IAM-based authentication.

DBTools Connections

NL2SQL uses two database connections with different purposes.

Enrichment Connection

The Enrichment Connection is the higher-privileged connection used during enrichment. It needs privileges to:

  • Execute queries
  • Perform DDL operations
  • Access example values from the database

OCI Generative AI uses this connection to read schema information and build the metadata needed for SQL generation.

Query Connection

The Query Connection is the lower-privileged connection used to run queries on behalf of the querying user.

This separation helps keep generation and execution responsibilities distinct and supports safer access control.

Enrichment

The enrichment process reads schema metadata, such as tables and columns, from the connected database. OCI Generative AI uses this metadata to generate a better SQL.

You can select when enrichment runs:

  • On create: Enrichment starts automatically after the Semantic Store is created
  • Manual: Enrichment runs later through a separate API call

To trigger enrichment manually, call the GenerateEnrichmentJob API.

Generate SQL from Natural Language

After enrichment completes, call the GenerateSqlFromNl API to convert natural-language input into SQL.

This API:

  • Accepts natural-language input
  • Uses the enriched semantic metadata
  • Returns generated SQL

This API doesn't run the SQL against the database.

Query Execution

The DBTools MCP Server orchestrates the full execution flow:

  1. Calls the NL2SQL service to generate SQL.
  2. Authorizes the request.
  3. Runs the query against the source database.
  4. Applies the appropriate guardrails.
  5. Uses the end user’s identity for execution.

This lets agents work with enterprise data while keeping execution in the source system under existing permissions.

Use NL2SQL in an Agentic Workflow

NL2SQL can be part of a broader agentic workflow.

A client can:

  1. Send a request to the Responses API to start agent planning and request validation
  2. Call GenerateSqlFromNl to convert the natural-language request into SQL
  3. Use the DBTools MCP Server to run the query, if needed
  4. Pass the generated SQL or query results back into the Responses API for the next step in the workflow

This lets you combine structured-data access with broader agent reasoning and orchestration.

How NL2SQL Fits with Agents

NL2SQL is an enterprise data capability in OCI Generative AI. It is useful when your agent needs to work with structured enterprise data by translating business-language requests into SQL.

Unlike File Search, Code Interpreter, Function Calling, and MCP Calling, NL2SQL isn't configured as a Responses API tools entry. It uses its own API flow and supporting resources, centered on:

  • Semantic Store
  • DBTools connections
  • Enrichment
  • GenerateSqlFromNl

NL2SQL API

You can use the following API for the NL2SQL tool:

Semantic Stores
  • CreateSemanticStore
  • ListSemanticStores
  • GetSemanticStore
  • UpdateSemanticStore
  • ChangeSemanticStoreCompartment
  • DeleteSemanticStore
Enrichment Jobs
  • ListEnrichmentJobs
  • GetEnrichmentJob
  • GenerateEnrichmentJob
  • CancelEnrichmentJob
  • GenerateSqlFromNl
Generate SQL
GenerateSqlFromNl