Skip to content
HeliosDB HeliosDB Full

Enhanced Natural Language to SQL (Agentic NL2SQL) - User Guide

Enhanced Natural Language to SQL (Agentic NL2SQL) - User Guide

Feature ID: F5.1.2 Version: v5.1 Status: Production-Ready (Target: 90%) ARR Value: $20M Patent Status: Patent Application Filed (November 2025)

OVERVIEW

Enhanced Natural Language to SQL (NL2SQL) transforms how users interact with databases by enabling natural language queries that are automatically converted to optimized SQL statements. Unlike traditional NL2SQL systems, HeliosDB’s agentic approach uses multiple AI agents working together to understand context, generate accurate queries, validate results, and learn from user feedback.

Key Features

  • Multi-agent architecture for robust query understanding
  • Context-aware query generation with schema understanding
  • Automatic query validation and error correction
  • Learning from user feedback and query patterns
  • Support for complex joins, aggregations, and subqueries
  • Natural language result explanations
  • Integration with HeliosDB’s query optimizer

Business Value

  • Reduce time-to-insight by 10x for business analysts
  • Eliminate SQL expertise barrier for data access
  • Decrease query development time from hours to seconds
  • Enable self-service analytics across organizations
  • Reduce data team workload by 40-60%

Target Users

  • Business analysts without SQL knowledge
  • Data scientists focusing on analysis vs. query writing
  • Executives requiring ad-hoc data exploration
  • Product managers analyzing user behavior
  • Marketing teams tracking campaign performance

GETTING STARTED

Prerequisites

  • HeliosDB v5.1 or later
  • Natural Language API enabled
  • Schema metadata populated
  • User authentication configured

Quick Start

1. Enable NL2SQL for Your Database

use heliosdb_nl2sql::{NL2SQLEngine, AgentConfig};


// Initialize the NL2SQL engine
let nl2sql = NL2SQLEngine::new()
    .with_database_connection(db_pool)
    .with_schema_metadata(schema)
    .with_agent_config(AgentConfig::default())
    .build()?;

2. Run Your First Natural Language Query

// Simple query
let query = "Show me all customers who signed up last month";
let result = nl2sql.execute(query).await?;


println!("Generated SQL: {}", result.sql);
println!("Results: {:?}", result.data);
println!("Explanation: {}", result.explanation);

Output:

Generated SQL: SELECT * FROM customers WHERE signup_date >= '2025-10-01' AND signup_date < '2025-11-01'
Results: [
  Customer { id: 1, name: "Acme Corp", signup_date: "2025-10-15", ... },
  ...
]
Explanation: Found 142 customers who created accounts between October 1st and October 31st, 2025.

3. Complex Query with Joins

// Multi-table query with aggregation
let query = "What's the average order value for customers in California, broken down by month?";
let result = nl2sql.execute(query).await?;

Generated SQL:

SELECT
    DATE_TRUNC('month', o.order_date) AS month,
    AVG(o.total_amount) AS avg_order_value,
    COUNT(*) AS order_count
FROM orders o
JOIN customers c ON o.customer_id = c.id
WHERE c.state = 'CA'
GROUP BY DATE_TRUNC('month', o.order_date)
ORDER BY month DESC;

CONFIGURATION

Agent Configuration

The NL2SQL system uses multiple specialized agents:

use heliosdb_nl2sql::{AgentConfig, Agent};


let config = AgentConfig {
    // Parser agent: Understands query intent
    parser: Agent {
        model: "claude-3-opus",
        temperature: 0.1,  // Low temperature for accuracy
        max_tokens: 4000,
    },


    // Schema agent: Understands database structure
    schema_analyzer: Agent {
        model: "claude-3-sonnet",
        enable_caching: true,  // Cache schema understanding
    },


    // Generator agent: Creates SQL queries
    sql_generator: Agent {
        model: "claude-3-opus",
        temperature: 0.0,  // Deterministic SQL generation
        max_retries: 3,
    },


    // Validator agent: Checks query correctness
    validator: Agent {
        model: "claude-3-sonnet",
        validation_mode: ValidationMode::Strict,
    },


    // Explainer agent: Generates human-readable explanations
    explainer: Agent {
        model: "claude-3-haiku",  // Fast explanations
        temperature: 0.3,
    },
};


let nl2sql = NL2SQLEngine::new()
    .with_agent_config(config)
    .build()?;

Schema Metadata Configuration

Enhance query accuracy by providing rich schema metadata:

use heliosdb_nl2sql::SchemaMetadata;


let schema = SchemaMetadata::builder()
    .add_table("customers")
        .with_description("Customer accounts and contact information")
        .add_column("id", "Primary key")
        .add_column("company_name", "Legal business name")
        .add_column("industry", "Business sector (tech, finance, retail, etc.)")
        .add_synonym("clients", "customers")  // Understand "clients" means customers
        .add_synonym("companies", "customers")
    .add_table("orders")
        .with_description("Purchase orders and transactions")
        .add_column("total_amount", "Order value in USD")
        .add_column("status", "Order status: pending, completed, cancelled")
        .add_relationship("customer_id", "customers.id")
    .build();


nl2sql.update_schema(schema).await?;

Context Configuration

Enable context-aware queries for follow-up questions:

use heliosdb_nl2sql::ContextConfig;


let context_config = ContextConfig {
    enable_conversation_history: true,
    max_history_items: 10,
    enable_result_context: true,  // Remember previous results
    context_window_minutes: 30,   // Reset context after 30 min
};


nl2sql.set_context_config(context_config)?;

EXAMPLES

Example 1: Simple Filtering

// Natural language
let query = "Show customers in New York";


// Generated SQL
SELECT * FROM customers WHERE state = 'NY';

Example 2: Aggregation

// Natural language
let query = "How many orders did we receive each day this week?";


// Generated SQL
SELECT
    DATE(order_date) AS day,
    COUNT(*) AS order_count
FROM orders
WHERE order_date >= DATE_TRUNC('week', CURRENT_DATE)
GROUP BY DATE(order_date)
ORDER BY day;

Example 3: Complex Join with Multiple Conditions

// Natural language
let query = "Which products have been ordered more than 100 times by enterprise customers in Q4?";


// Generated SQL
SELECT
    p.product_name,
    COUNT(DISTINCT o.id) AS order_count,
    SUM(oi.quantity) AS total_quantity
FROM products p
JOIN order_items oi ON p.id = oi.product_id
JOIN orders o ON oi.order_id = o.id
JOIN customers c ON o.customer_id = c.id
WHERE c.customer_type = 'enterprise'
  AND o.order_date >= '2025-10-01'
  AND o.order_date < '2026-01-01'
GROUP BY p.id, p.product_name
HAVING COUNT(DISTINCT o.id) > 100
ORDER BY order_count DESC;

Example 4: Conversational Context

// First query
let result1 = nl2sql.execute("Show me top 10 customers by revenue").await?;


// Follow-up query (uses context)
let result2 = nl2sql.execute("Which of them are in the tech industry?").await?;


// The system understands "them" refers to the top 10 customers
// Generated SQL for second query:
WITH top_customers AS (
    SELECT customer_id, SUM(total_amount) AS revenue
    FROM orders
    GROUP BY customer_id
    ORDER BY revenue DESC
    LIMIT 10
)
SELECT c.*
FROM customers c
JOIN top_customers tc ON c.id = tc.customer_id
WHERE c.industry = 'technology';

Example 5: Time-Based Comparisons

// Natural language
let query = "Compare this month's sales to last month";


// Generated SQL
SELECT
    'Current Month' AS period,
    SUM(total_amount) AS total_sales,
    COUNT(*) AS order_count
FROM orders
WHERE order_date >= DATE_TRUNC('month', CURRENT_DATE)


UNION ALL


SELECT
    'Previous Month' AS period,
    SUM(total_amount) AS total_sales,
    COUNT(*) AS order_count
FROM orders
WHERE order_date >= DATE_TRUNC('month', CURRENT_DATE) - INTERVAL '1 month'
  AND order_date < DATE_TRUNC('month', CURRENT_DATE);

Example 6: Advanced Analytics

// Natural language
let query = "What's the customer lifetime value for each acquisition channel, showing retention rates?";


// Generated SQL
SELECT
    c.acquisition_channel,
    COUNT(DISTINCT c.id) AS customer_count,
    AVG(customer_revenue.total_revenue) AS avg_ltv,
    AVG(customer_orders.order_count) AS avg_orders,
    COUNT(DISTINCT CASE
        WHEN customer_orders.last_order_date > CURRENT_DATE - INTERVAL '90 days'
        THEN c.id
    END) * 100.0 / COUNT(DISTINCT c.id) AS retention_rate_90d
FROM customers c
LEFT JOIN (
    SELECT customer_id, SUM(total_amount) AS total_revenue
    FROM orders
    GROUP BY customer_id
) customer_revenue ON c.id = customer_revenue.customer_id
LEFT JOIN (
    SELECT
        customer_id,
        COUNT(*) AS order_count,
        MAX(order_date) AS last_order_date
    FROM orders
    GROUP BY customer_id
) customer_orders ON c.id = customer_orders.customer_id
GROUP BY c.acquisition_channel
ORDER BY avg_ltv DESC;

API REFERENCE

Core API

NL2SQLEngine

Main entry point for natural language query processing.

pub struct NL2SQLEngine {
    // Engine configuration
}


impl NL2SQLEngine {
    /// Create a new NL2SQL engine builder
    pub fn new() -> NL2SQLEngineBuilder;


    /// Execute a natural language query
    pub async fn execute(&self, query: &str) -> Result<QueryResult>;


    /// Execute with custom options
    pub async fn execute_with_options(
        &self,
        query: &str,
        options: ExecutionOptions
    ) -> Result<QueryResult>;


    /// Update schema metadata
    pub async fn update_schema(&self, schema: SchemaMetadata) -> Result<()>;


    /// Get query explanation without execution
    pub async fn explain(&self, query: &str) -> Result<Explanation>;


    /// Validate a natural language query
    pub async fn validate(&self, query: &str) -> Result<ValidationResult>;
}

QueryResult

Result of a natural language query execution.

pub struct QueryResult {
    /// The generated SQL query
    pub sql: String,


    /// Query execution results
    pub data: Vec<Row>,


    /// Human-readable explanation
    pub explanation: String,


    /// Confidence score (0.0 - 1.0)
    pub confidence: f64,


    /// Execution metrics
    pub metrics: QueryMetrics,


    /// Suggested follow-up questions
    pub suggestions: Vec<String>,
}


impl QueryResult {
    /// Check if result has high confidence
    pub fn is_confident(&self) -> bool {
        self.confidence >= 0.8
    }


    /// Get result as JSON
    pub fn to_json(&self) -> serde_json::Value;


    /// Get result as CSV
    pub fn to_csv(&self) -> String;
}

ExecutionOptions

Options for query execution.

pub struct ExecutionOptions {
    /// Maximum rows to return
    pub limit: Option<usize>,


    /// Enable query caching
    pub use_cache: bool,


    /// Timeout for query execution
    pub timeout: Duration,


    /// Enable detailed explanations
    pub verbose_explanation: bool,


    /// User context for personalization
    pub user_context: Option<UserContext>,
}

Advanced API

SchemaMetadata

Structured schema information for better query understanding.

pub struct SchemaMetadata {
    pub tables: Vec<TableMetadata>,
    pub relationships: Vec<Relationship>,
}


pub struct TableMetadata {
    pub name: String,
    pub description: Option<String>,
    pub columns: Vec<ColumnMetadata>,
    pub synonyms: Vec<String>,
}


pub struct ColumnMetadata {
    pub name: String,
    pub data_type: DataType,
    pub description: Option<String>,
    pub is_nullable: bool,
    pub is_primary_key: bool,
    pub is_foreign_key: bool,
}

AgentOrchestration

Advanced agent coordination for complex queries.

pub trait AgentOrchestration {
    /// Coordinate multiple agents for query processing
    async fn orchestrate(&self, query: &str) -> Result<OrchestrationResult>;


    /// Add custom agent to the pipeline
    fn add_agent(&mut self, agent: Box<dyn Agent>);


    /// Configure agent communication
    fn set_communication_mode(&mut self, mode: CommunicationMode);
}

TROUBLESHOOTING

Common Issues

Issue: Low Confidence Scores

Problem: Query results show confidence < 0.7

Solutions:

  1. Improve schema metadata with better descriptions
  2. Add table/column synonyms for common business terms
  3. Provide example queries for the domain
  4. Enable conversation history for context
// Add better metadata
schema_builder
    .add_table("orders")
    .with_description("Customer purchase orders including both one-time and recurring")
    .add_column("mrr", "Monthly Recurring Revenue for subscription orders")
    .add_synonym("sales", "orders")
    .add_synonym("purchases", "orders")
    .add_synonym("transactions", "orders");

Issue: Incorrect Table Selection

Problem: Query uses wrong table

Solutions:

  1. Add table relationships explicitly
  2. Improve table descriptions
  3. Add business logic hints
schema_builder
    .add_relationship(Relationship {
        from_table: "orders",
        from_column: "customer_id",
        to_table: "customers",
        to_column: "id",
        relationship_type: RelationshipType::ManyToOne,
        description: Some("Each order belongs to exactly one customer"),
    });

Issue: Slow Query Generation

Problem: NL2SQL takes > 5 seconds to generate SQL

Solutions:

  1. Enable schema caching
  2. Use faster models for non-critical agents
  3. Reduce context window size
let config = AgentConfig {
    schema_analyzer: Agent {
        enable_caching: true,
        cache_ttl: Duration::from_hours(24),
    },
    explainer: Agent {
        model: "claude-3-haiku",  // Faster model
    },
    ..Default::default()
};

Issue: Query Fails Validation

Problem: Generated SQL has syntax errors

Solutions:

  1. Update to latest model versions
  2. Enable strict validation mode
  3. Provide SQL dialect hints
let nl2sql = NL2SQLEngine::new()
    .with_sql_dialect(SQLDialect::PostgreSQL)
    .with_validation_mode(ValidationMode::Strict)
    .with_syntax_checker(Box::new(PostgreSQLSyntaxChecker))
    .build()?;

Performance Optimization

Optimize for Throughput

// Use connection pooling
let nl2sql = NL2SQLEngine::new()
    .with_connection_pool(pool_size: 50)
    .with_agent_config(AgentConfig {
        sql_generator: Agent {
            enable_batching: true,
            batch_size: 10,
        },
        ..Default::default()
    })
    .build()?;

Optimize for Latency

// Minimize agent calls
let nl2sql = NL2SQLEngine::new()
    .with_agent_config(AgentConfig {
        parser: Agent {
            model: "claude-3-haiku",  // Fast parsing
        },
        enable_parallel_agents: true,  // Run agents concurrently
        ..Default::default()
    })
    .build()?;

FAQ

General Questions

Q: Does NL2SQL work with all SQL dialects? A: Yes, NL2SQL supports PostgreSQL, MySQL, SQLite, SQL Server, and Oracle. Configure the dialect during engine initialization.

Q: How accurate is the SQL generation? A: With proper schema metadata, accuracy is typically 85-95% for standard business queries. Complex analytical queries may require refinement.

Q: Can I customize the SQL generation? A: Yes, you can provide custom templates, hints, and constraints to guide SQL generation.

Q: Does it support multi-tenant databases? A: Yes, configure tenant-aware schema metadata and enable row-level security filters.

Security Questions

Q: How do you prevent SQL injection? A: All generated queries use parameterized statements. The system never concatenates user input into SQL strings.

Q: Can users access tables they shouldn’t see? A: No, the system respects database permissions and can be configured with additional access controls.

Q: Is PII data protected? A: Yes, enable PII masking and the system will automatically redact sensitive data in results.

Integration Questions

Q: Can I integrate with BI tools? A: Yes, NL2SQL provides REST API endpoints compatible with Tableau, PowerBI, and Looker.

Q: Does it work with data warehouses? A: Yes, tested with Snowflake, BigQuery, Redshift, and Databricks.

Q: Can I use it in production? A: Yes, the system is production-ready with high availability, monitoring, and fallback mechanisms.

BEST PRACTICES

1. Provide Rich Schema Metadata

Good schema metadata is critical for accuracy:

// Bad: Minimal metadata
schema.add_table("ord").add_column("amt");


// Good: Rich metadata
schema.add_table("orders")
    .with_description("Customer purchase orders")
    .add_column("total_amount")
        .with_description("Order total in USD including tax")
        .with_data_type(DataType::Decimal(10, 2))
    .add_synonym("sales", "orders")
    .add_synonym("purchases", "orders");

2. Use Conversation Context

Enable context for better follow-up queries:

// Enable context
nl2sql.enable_conversation_context()?;


// Queries build on each other
nl2sql.execute("Show top customers by revenue").await?;
nl2sql.execute("Which are in California?").await?;  // Uses previous context
nl2sql.execute("What did they buy?").await?;  // Further refinement

3. Monitor and Learn

Track query patterns to improve the system:

// Enable learning from feedback
nl2sql.enable_feedback_learning()?;


// User provides feedback
let result = nl2sql.execute(query).await?;
nl2sql.record_feedback(result.query_id, Feedback {
    was_helpful: true,
    sql_correct: true,
    result_relevant: true,
    suggested_improvement: None,
})?;

4. Handle Ambiguity

Guide users when queries are ambiguous:

let result = nl2sql.execute("Show me sales").await?;


if result.confidence < 0.7 {
    println!("Did you mean:");
    for suggestion in result.suggestions {
        println!("  - {}", suggestion);
    }
}

PERFORMANCE CHARACTERISTICS

Latency

  • Simple queries: 200-500ms
  • Complex queries: 500ms-2s
  • Very complex queries: 2-5s

Throughput

  • Concurrent queries: 100+ QPS per instance
  • Batch processing: 1000+ queries/minute

Accuracy

  • Simple queries: 95%+ accuracy
  • Medium complexity: 85-90% accuracy
  • Complex analytical: 75-85% accuracy

Resource Usage

  • Memory: 512MB-2GB per instance
  • CPU: 1-2 cores per instance
  • Storage: Minimal (caching only)

NEXT STEPS

  1. Try Advanced Features: Explore conversational queries and complex analytics
  2. Integrate with Applications: Use the REST API for application integration
  3. Monitor Performance: Set up dashboards to track query accuracy and performance
  4. Customize Agents: Fine-tune agent configurations for your domain
  5. Contribute Feedback: Help improve the system by reporting issues and edge cases
  • Architecture: /home/claude/HeliosDB/docs/architecture/AGENTIC_NL2SQL_ARCHITECTURE.md
  • API Reference: Complete rustdoc in heliosdb-nl2sql/src/lib.rs
  • Implementation Report: /home/claude/HeliosDB/docs/releases/v5.2-v5.4/F5.1.2_IMPLEMENTATION_REPORT.md
  • Invention Disclosure: /home/claude/HeliosDB/docs/ip/invention-disclosures/F5.1.2_AGENTIC_NL2SQL_INVENTION_DISCLOSURE.md

Version: 1.0 Last Updated: November 1, 2025 Author: HeliosDB Engineering Team Patent Status: Application Filed