AI SQL Agents: Natural Language to Database Queries

How Text-to-SQL Actually Works

The text-to-SQL pipeline has four stages, and each stage determines the quality of the final query.

Stage 1: Schema retrieval. Before generating any SQL, the agent needs to know what tables and columns exist in your database. For small databases (under 50 tables), the agent can load the entire schema into its context window. For larger databases with hundreds or thousands of tables, the agent uses semantic search to find the tables most relevant to the current question. If you ask "What was total revenue by region last quarter?", the agent searches for tables related to revenue, regions, and dates, rather than loading the entire 400-table schema. This retrieval step is critical because if the agent does not find the right tables, no amount of query-writing skill will produce a correct answer.

Stage 2: Intent mapping. The agent maps your natural language question to SQL concepts. "Total revenue" maps to a SUM aggregation. "By region" maps to a GROUP BY clause. "Last quarter" maps to a date filter with calendar quarter logic. Ambiguous terms get resolved using schema context. If the schema has a column called "net_revenue" and another called "gross_revenue", the agent needs to decide which one "revenue" refers to. Well-documented schemas with column descriptions help the agent make the right choice. Without documentation, the agent guesses based on naming conventions and often gets it right, but not always.

Stage 3: Query generation. The agent writes the actual SQL query. This involves selecting the correct tables, writing join conditions, applying filters, choosing aggregation functions, and ordering the results. The query needs to be syntactically valid for the specific SQL dialect (PostgreSQL, MySQL, Snowflake, BigQuery all have slightly different syntax) and logically correct (the right joins, the right filter conditions, no accidental cross joins that inflate results). Multi-table queries with complex joins are where most errors occur. The agent might join on the wrong key, miss a necessary join that creates a Cartesian product, or apply a filter at the wrong point in the query chain.

Stage 4: Execution and error correction. The agent runs the query against the database. If the query fails (syntax error, timeout, permission denied), the agent reads the error message, diagnoses the problem, and generates a corrected query. This self-correction loop typically runs 2-3 times before giving up. Most syntax errors are caught and fixed on the first retry. Logical errors (the query runs but returns wrong results) are harder to catch automatically, though some agents compare results against expected ranges or known totals to detect obvious problems.

Current Accuracy Benchmarks

Text-to-SQL accuracy is measured by execution accuracy: does the generated query produce the same result set as a human-written gold-standard query? The major benchmarks tell a consistent story about where the technology stands.

Spider benchmark tests across 200 databases with varying complexity. The top models achieve 85-90% execution accuracy on Spider as of mid-2026. However, Spider databases are relatively small and well-structured, which makes them easier than real-world schemas. Spider is useful for comparing models against each other but overstates the accuracy you will see in production.

BIRD benchmark tests on larger, more realistic databases with dirty data and ambiguous column names. Top accuracy on BIRD is 70-80%, which is more representative of enterprise use. BIRD includes questions that require understanding implicit business rules (like "big order" meaning orders above a certain threshold that is not defined in the schema), which is a common challenge in real-world analytics.

Real-world enterprise accuracy depends heavily on schema complexity and configuration. Organizations that invest in schema documentation, provide example queries, and build a semantic layer see 85-92% accuracy. Organizations that point an agent at an undocumented database with 500 tables and cryptic column names typically see 65-75% accuracy. The difference is not the model, it is the quality of context provided to the model.

The 10-30% error rate sounds concerning, and it should be taken seriously, but context matters. Many "errors" are not wrong answers but different-but-valid interpretations. If you ask "top customers" and the agent sorts by total revenue when you meant by number of orders, the query is technically wrong but the result is still useful. Other errors are immediately obvious (empty results, impossibly large numbers) and prompt the user to rephrase. The genuinely dangerous errors, the ones that return plausible but quietly incorrect results, account for roughly 3-8% of queries in well-configured systems. That is the number to manage.

Schema Configuration That Improves Accuracy

The single most impactful thing you can do to improve SQL agent accuracy is provide better schema context. The model's query-writing ability is strong. What it lacks is institutional knowledge about your specific data. Here is how to provide it.

Column descriptions. Add a plain English description to every column, especially when the column name is abbreviated or ambiguous. "amt_usd" should be described as "Transaction amount in US dollars, after discounts but before tax." "status" should be described as "Order status: pending, processing, shipped, delivered, cancelled, returned." These descriptions go into the schema context the agent reads before generating queries, and they eliminate an entire category of errors where the agent guesses wrong about what a column means.

Table relationship documentation. Explicitly document which tables join to which, and on which keys. While foreign key constraints define this formally, many production databases have implicit relationships (tables that logically join on a shared column but have no formal constraint) or multiple valid join paths between the same tables. Documenting the intended join paths prevents the agent from choosing a valid but unintended join that produces different results.

Business term glossary. Define what business terms mean in the context of your data. "Active customer" might mean someone who logged in within the last 30 days, or someone with a non-cancelled subscription, or someone who made a purchase in the last 90 days. Each definition implies a completely different query. A glossary that maps business terms to specific SQL conditions (active_customer = users WHERE last_login > NOW() - INTERVAL 30 DAY AND status = 'active') eliminates this ambiguity.

Example queries. Providing 10-50 example queries with their natural language descriptions is one of the most effective accuracy improvements. The agent uses these examples as patterns when generating new queries. If your examples show that "revenue" always comes from the "invoices.total_amount" column and always excludes refunded invoices, the agent will follow that pattern for new revenue questions. Tools like Vanna.ai are built specifically around this pattern, letting you train the agent on your organization's actual query history.

Value examples. Show the agent what actual values look like in important columns. If "region" contains values like "EMEA", "APAC", "AMER", and "LATAM", providing those examples prevents the agent from guessing at region names or misinterpreting user input. A user who asks about "European revenue" needs the agent to know that Europe maps to "EMEA" in the data.

Multi-Database and Cross-Schema Queries

Real organizations store data across multiple databases, schemas, and even different database engines. A marketing database might be in MySQL, a financial database in PostgreSQL, and web analytics in BigQuery. Joining data across these boundaries is something human analysts do regularly, often by exporting to spreadsheets and matching manually.

Advanced SQL agents handle cross-database queries by executing separate queries against each database and joining the results in Python. The agent writes a SQL query for each source, retrieves the results into DataFrames, then joins them using pandas merge operations. This is functionally equivalent to what a data engineer does when building a cross-system report, but the agent handles the orchestration automatically.

The accuracy challenge with cross-database queries is entity resolution, ensuring that "customer_id" in one database matches the same real-world customer in another database. If the databases use different ID systems, the agent needs a mapping table or a common key (like email address) to join on. Without explicit configuration, the agent might attempt a join that produces incorrect matches. Always document cross-database relationships explicitly when configuring the agent.

Security and Access Control

Giving an AI agent access to your database raises immediate security questions. The fundamental rule is that the agent should have the minimum privileges needed to answer queries, nothing more.

Read-only access. The agent should connect with a database user that has SELECT privileges only. No INSERT, UPDATE, DELETE, or DDL permissions. This prevents the agent from accidentally modifying data, even if a prompt injection or model error causes it to generate a data-modifying statement. Most database systems support creating users with read-only roles, so this is a one-time configuration step.

Schema-level restrictions. Grant access only to the schemas and tables that are appropriate for analysis. Production systems often contain tables with sensitive data (personally identifiable information, payment details, authentication credentials) that should not be exposed to an analytical agent. Restrict the agent's database user to analytical schemas or views that exclude sensitive columns.

Row-level security. For multi-tenant systems or role-based access, apply row-level security policies that filter data based on the requesting user's identity. A regional manager should only see data for their region, even when asking an unrestricted question like "What was total revenue?". PostgreSQL's row-level security policies and Snowflake's data masking features handle this at the database level, which is more reliable than trying to enforce it in the agent's prompt.

Query review and audit logging. Log every query the agent generates and executes. This creates an audit trail for compliance purposes and lets you review what the agent accessed. Some organizations add a query approval step for the initial deployment period, where a DBA reviews generated queries before they execute. This is conservative but catches potential issues early.

Resource limits. Set query timeouts and row limits on the agent's database connection. A poorly written query (like one missing a WHERE clause on a billion-row table) should time out rather than consuming database resources for hours. Most databases support setting these limits per user or per session.

When SQL Agents Are Not Enough

SQL agents excel at structured analytical queries against relational databases. They struggle or fail in several specific situations.

Unstructured data analysis (text mining, document analysis, image classification) requires tools beyond SQL. If your analytical question involves reading PDF reports, analyzing email text, or classifying images, a SQL agent cannot help because the data is not in tabular form. These tasks require specialized NLP or computer vision models, often integrated into a broader data pipeline.

Real-time streaming analysis is poorly served by SQL agents designed for batch queries. If you need sub-second analysis of streaming event data, tools like Apache Flink, Kafka Streams, or Materialize are more appropriate. Some SQL agents can query streaming databases using SQL, but the conversational query model does not fit the continuous monitoring use case well.

Advanced statistical and ML modeling that goes beyond basic statistics (regression, hypothesis testing) into areas like deep learning, Bayesian modeling, or reinforcement learning requires Python-based analysis agents rather than pure SQL agents. The SQL agent can prepare and extract the data, but the modeling happens in a different environment.

For most business analytical needs, though, SQL agent capabilities are sufficient. The majority of business questions ("How much?", "How many?", "What changed?", "Why did this happen?") can be answered with SQL queries against structured data, which is exactly what SQL agents are designed to do.