proxysql/doc/NL2SQL/API.md

NL2SQL API Reference

Complete API Documentation

This document provides a comprehensive reference for all NL2SQL APIs, including configuration variables, data structures, and methods.

Table of Contents

• Configuration Variables
• Data Structures
• NL2SQL_Converter Class
• AI_Features_Manager Class
• MySQL Protocol Integration

Configuration Variables

All NL2SQL variables use the ai_nl2sql_ prefix and are accessible via the ProxySQL admin interface.

Master Switch

ai_nl2sql_enabled

• Type: Boolean
• Default: true
• Description: Enable/disable NL2SQL feature
• Runtime: Yes
• Example:

  SET ai_nl2sql_enabled='true';
  LOAD MYSQL VARIABLES TO RUNTIME;
  

Query Detection

ai_nl2sql_query_prefix

• Type: String
• Default: NL2SQL:
• Description: Prefix that identifies NL2SQL queries
• Runtime: Yes
• Example:

  SET ai_nl2sql_query_prefix='SQL:';
  -- Now use: SQL: Show customers
  

Model Selection

ai_nl2sql_model_provider

• Type: Enum (ollama, openai, anthropic)
• Default: ollama
• Description: Preferred LLM provider
• Runtime: Yes
• Example:

  SET ai_nl2sql_model_provider='openai';
  LOAD MYSQL VARIABLES TO RUNTIME;
  

ai_nl2sql_ollama_model

• Type: String
• Default: llama3.2
• Description: Ollama model name
• Runtime: Yes
• Example:

  SET ai_nl2sql_ollama_model='llama3.3';
  

ai_nl2sql_openai_model

• Type: String
• Default: gpt-4o-mini
• Description: OpenAI model name
• Runtime: Yes
• Example:

  SET ai_nl2sql_openai_model='gpt-4o';
  

ai_nl2sql_anthropic_model

• Type: String
• Default: claude-3-haiku
• Description: Anthropic model name
• Runtime: Yes
• Example:

  SET ai_nl2sql_anthropic_model='claude-3-5-sonnet-20241022';
  

API Keys

ai_nl2sql_openai_key

• Type: String (sensitive)
• Default: NULL
• Description: OpenAI API key
• Runtime: Yes
• Example:

  SET ai_nl2sql_openai_key='sk-proj-...';
  

ai_nl2sql_anthropic_key

• Type: String (sensitive)
• Default: NULL
• Description: Anthropic API key
• Runtime: Yes
• Example:

  SET ai_nl2sql_anthropic_key='sk-ant-...';
  

Cache Configuration

ai_nl2sql_cache_similarity_threshold

• Type: Integer (0-100)
• Default: 85
• Description: Minimum similarity score for cache hit
• Runtime: Yes
• Example:

  SET ai_nl2sql_cache_similarity_threshold='90';
  

Performance

ai_nl2sql_timeout_ms

• Type: Integer
• Default: 30000 (30 seconds)
• Description: Maximum time to wait for LLM response
• Runtime: Yes
• Example:

  SET ai_nl2sql_timeout_ms='60000';
  

Routing

ai_nl2sql_prefer_local

• Type: Boolean
• Default: true
• Description: Prefer local Ollama over cloud APIs
• Runtime: Yes
• Example:

  SET ai_nl2sql_prefer_local='false';
  

Data Structures

NL2SQLRequest

struct NL2SQLRequest {
    std::string natural_language;           // Natural language query text
    std::string schema_name;                 // Current database/schema name
    int max_latency_ms;                      // Max acceptable latency (ms)
    bool allow_cache;                        // Enable semantic cache lookup
    std::vector<std::string> context_tables; // Optional table hints for schema

    NL2SQLRequest() : max_latency_ms(0), allow_cache(true) {}
};

Fields

Field	Type	Default	Description
natural_language	string	""	The user's query in natural language
schema_name	string	""	Current database/schema name
max_latency_ms	int	0	Max acceptable latency (0 = no constraint)
allow_cache	bool	true	Whether to check semantic cache
context_tables	vector	{}	Optional table hints for schema context

NL2SQLResult

struct NL2SQLResult {
    std::string sql_query;                  // Generated SQL query
    float confidence;                        // Confidence score 0.0-1.0
    std::string explanation;                 // Which model generated this
    std::vector<std::string> tables_used;    // Tables referenced in SQL
    bool cached;                             // True if from semantic cache
    int64_t cache_id;                        // Cache entry ID for tracking

    NL2SQLResult() : confidence(0.0f), cached(false), cache_id(0) {}
};

Fields

Field	Type	Default	Description
sql_query	string	""	Generated SQL query
confidence	float	0.0	Confidence score (0.0-1.0)
explanation	string	""	Model/provider info
tables_used	vector	{}	Tables referenced in SQL
cached	bool	false	Whether result came from cache
cache_id	int64	0	Cache entry ID

ModelProvider Enum

enum class ModelProvider {
    LOCAL_OLLAMA,      // Local models via Ollama
    CLOUD_OPENAI,      // OpenAI API
    CLOUD_ANTHROPIC,   // Anthropic API
    FALLBACK_ERROR     // No model available
};

NL2SQL_Converter Class

Constructor

NL2SQL_Converter::NL2SQL_Converter();

Initializes with default configuration values.

Destructor

NL2SQL_Converter::~NL2SQL_Converter();

Frees allocated resources.

Methods

init()

int NL2SQL_Converter::init();

Initialize the NL2SQL converter.

Returns: 0 on success, non-zero on failure

close()

void NL2SQL_Converter::close();

Shutdown and cleanup resources.

convert()

NL2SQLResult NL2SQL_Converter::convert(const NL2SQLRequest& req);

Convert natural language to SQL.

Parameters:

• req: NL2SQL request with natural language query and context

Returns: NL2SQLResult with generated SQL and metadata

Example:

NL2SQLRequest req;
req.natural_language = "Show top 10 customers";
req.allow_cache = true;
NL2SQLResult result = converter->convert(req);
if (result.confidence > 0.7f) {
    execute_sql(result.sql_query);
}

clear_cache()

void NL2SQL_Converter::clear_cache();

Clear all cached NL2SQL conversions.

get_cache_stats()

std::string NL2SQL_Converter::get_cache_stats();

Get cache statistics as JSON.

Returns: JSON string with cache metrics

Example:

{
  "entries": 150,
  "hits": 1200,
  "misses": 300
}

AI_Features_Manager Class

Methods

get_nl2sql()

NL2SQL_Converter* AI_Features_Manager::get_nl2sql();

Get the NL2SQL converter instance.

Returns: Pointer to NL2SQL_Converter or NULL

Example:

NL2SQL_Converter* nl2sql = GloAI->get_nl2sql();
if (nl2sql) {
    NL2SQLResult result = nl2sql->convert(req);
}

get_variable()

char* AI_Features_Manager::get_variable(const char* name);

Get configuration variable value.

Parameters:

• name: Variable name (without ai_nl2sql_ prefix)

Returns: Variable value or NULL

Example:

char* model = GloAI->get_variable("ollama_model");

set_variable()

bool AI_Features_Manager::set_variable(const char* name, const char* value);

Set configuration variable value.

Parameters:

• name: Variable name (without ai_nl2sql_ prefix)
• value: New value

Returns: true on success, false on failure

Example:

GloAI->set_variable("ollama_model", "llama3.3");

MySQL Protocol Integration

Query Format

NL2SQL queries use a special prefix:

NL2SQL: <natural language query>

Result Format

Results are returned as a standard MySQL resultset with columns:

Column	Type	Description
sql_query	TEXT	Generated SQL query
confidence	FLOAT	Confidence score
explanation	TEXT	Model info
cached	BOOLEAN	From cache
cache_id	BIGINT	Cache entry ID

Example Session

mysql> USE my_database;
mysql> NL2SQL: Show top 10 customers by revenue;
+---------------------------------------------+------------+-------------------------+--------+----------+
| sql_query                                    | confidence | explanation             | cached | cache_id |
+---------------------------------------------+------------+-------------------------+--------+----------+
| SELECT * FROM customers ORDER BY revenue    |      0.850 | Generated by Ollama    |      0 |        0 |
| DESC LIMIT 10                               |            | llama3.2                |        |          |
+---------------------------------------------+------------+-------------------------+--------+----------+
1 row in set (1.23 sec)

Error Codes

Code	Description	Action
ER_NL2SQL_DISABLED	NL2SQL feature is disabled	Enable via ai_nl2sql_enabled
ER_NL2SQL_TIMEOUT	LLM request timed out	Increase ai_nl2sql_timeout_ms
ER_NL2SQL_NO_MODEL	No LLM model available	Configure API key or Ollama
ER_NL2SQL_API_ERROR	LLM API returned error	Check logs and API key
ER_NL2SQL_INVALID_QUERY	Query doesn't start with prefix	Use correct prefix format

Status Variables

Monitor NL2SQL performance via status variables:

-- View all AI status variables
SELECT * FROM runtime_mysql_servers
WHERE variable_name LIKE 'ai_nl2sql_%';

-- Key metrics
SELECT * FROM stats_ai_nl2sql;

Variable	Description
nl2sql_total_requests	Total NL2SQL conversions
nl2sql_cache_hits	Cache hit count
nl2sql_local_model_calls	Ollama API calls
nl2sql_cloud_model_calls	Cloud API calls

See Also

• README.md - User documentation
• ARCHITECTURE.md - System architecture
• TESTING.md - Testing guide