From 349320a67f76354795500523d529101e049c4ceb Mon Sep 17 00:00:00 2001 From: Rene Cannao Date: Sat, 17 Jan 2026 00:04:55 +0000 Subject: [PATCH] docs: Fix NL2SQL documentation with genai variables and async architecture Updated documentation to reflect the architectural changes: - Changed all ai_* variables to genai-* variables - Changed LOAD MYSQL VARIABLES to LOAD GENAI VARIABLES - Clarified that NL2SQL queries run on MySQL module, not Admin - Updated ARCHITECTURE.md to document async/non-blocking architecture - Added LOAD GENAI VARIABLES TO RUNTIME after variable changes - Changed stats_ai_nl2sql_cache to SHOW STATUS LIKE 'genai-nl2sql%' Key corrections in README.md: - Variables now use genai-* prefix (genai-nl2sql_enabled, etc.) - Commands use LOAD GENAI VARIABLES instead of LOAD MYSQL VARIABLES - Added note that NL2SQL queries are on MySQL module, not Admin interface Key corrections in ARCHITECTURE.md: - Updated system flow diagram to show async socketpair path - Added detailed async flow explanation - Documented that MySQL threads are NOT blocked during LLM calls Related to: https://github.com/ProxySQL/proxysql-vec/pull/13 --- doc/NL2SQL/ARCHITECTURE.md | 43 ++++++++++++++++---- doc/NL2SQL/README.md | 80 ++++++++++++++++++++------------------ 2 files changed, 78 insertions(+), 45 deletions(-) diff --git a/doc/NL2SQL/ARCHITECTURE.md b/doc/NL2SQL/ARCHITECTURE.md index 29b3fab99..d8d4f2d0a 100644 --- a/doc/NL2SQL/ARCHITECTURE.md +++ b/doc/NL2SQL/ARCHITECTURE.md @@ -7,18 +7,47 @@ Client Query (NL2SQL: ...) ↓ MySQL_Session (detects prefix) ↓ -AI_Features_Manager::get_nl2sql() +Convert to JSON: {"type": "nl2sql", "query": "...", "schema": "..."} ↓ -NL2SQL_Converter::convert() - ├─ check_vector_cache() ← sqlite-vec similarity search - ├─ build_prompt() ← Schema context via MySQL_Tool_Handler - ├─ select_model() ← Ollama/OpenAI/Anthropic selection - ├─ call_llm_api() ← libcurl HTTP request - └─ validate_sql() ← Keyword validation +GenAI Module (async via socketpair) + ├─ GenAI worker thread processes request + └─ AI_Features_Manager::get_nl2sql() + ↓ + NL2SQL_Converter::convert() + ├─ check_vector_cache() ← sqlite-vec similarity search + ├─ build_prompt() ← Schema context via MySQL_Tool_Handler + ├─ select_model() ← Ollama/OpenAI/Anthropic selection + ├─ call_llm_api() ← libcurl HTTP request + └─ validate_sql() ← Keyword validation + ↓ + Async response back to MySQL_Session ↓ Return Resultset (sql_query, confidence, ...) ``` +**Important**: NL2SQL uses an **asynchronous, non-blocking architecture**. The MySQL thread is not blocked while waiting for the LLM response. The request is sent via socketpair to the GenAI module, which processes it in a worker thread and delivers the result asynchronously. + +## Async Flow Details + +1. **MySQL Thread** (non-blocking): + - Detects `NL2SQL:` prefix + - Constructs JSON: `{"type": "nl2sql", "query": "...", "schema": "..."}` + - Creates socketpair for async communication + - Sends request to GenAI module immediately + - Returns to handle other queries + +2. **GenAI Worker Thread**: + - Receives request via socketpair + - Calls `process_json_query()` with nl2sql operation type + - Invokes `NL2SQL_Converter::convert()` + - Processes LLM response (HTTP via libcurl) + - Sends result back via socketpair + +3. **Response Delivery**: + - MySQL thread receives notification via epoll + - Retrieves result from socketpair + - Builds resultset and sends to client + ## Components ### 1. NL2SQL_Converter diff --git a/doc/NL2SQL/README.md b/doc/NL2SQL/README.md index 1f14501a4..035107bf6 100644 --- a/doc/NL2SQL/README.md +++ b/doc/NL2SQL/README.md @@ -27,8 +27,8 @@ NL2SQL (Natural Language to SQL) is a ProxySQL feature that converts natural lan ```sql -- Via admin interface -SET ai_nl2sql_enabled='true'; -LOAD MYSQL VARIABLES TO RUNTIME; +SET genai-nl2sql_enabled='true'; +LOAD GENAI VARIABLES TO RUNTIME; ``` ### 2. Configure LLM Provider @@ -40,31 +40,31 @@ ProxySQL uses a **generic provider configuration** that supports any OpenAI-comp Ollama is used via its OpenAI-compatible endpoint: ```sql -SET ai_nl2sql_provider='openai'; -SET ai_nl2sql_provider_url='http://localhost:11434/v1/chat/completions'; -SET ai_nl2sql_provider_model='llama3.2'; -SET ai_nl2sql_provider_key=''; -- Empty for local Ollama -LOAD MYSQL VARIABLES TO RUNTIME; +SET genai-nl2sql_provider='openai'; +SET genai-nl2sql_provider_url='http://localhost:11434/v1/chat/completions'; +SET genai-nl2sql_provider_model='llama3.2'; +SET genai-nl2sql_provider_key=''; -- Empty for local Ollama +LOAD GENAI VARIABLES TO RUNTIME; ``` **Using OpenAI:** ```sql -SET ai_nl2sql_provider='openai'; -SET ai_nl2sql_provider_url='https://api.openai.com/v1/chat/completions'; -SET ai_nl2sql_provider_model='gpt-4o-mini'; -SET ai_nl2sql_provider_key='sk-...'; -LOAD MYSQL VARIABLES TO RUNTIME; +SET genai-nl2sql_provider='openai'; +SET genai-nl2sql_provider_url='https://api.openai.com/v1/chat/completions'; +SET genai-nl2sql_provider_model='gpt-4o-mini'; +SET genai-nl2sql_provider_key='sk-...'; +LOAD GENAI VARIABLES TO RUNTIME; ``` **Using Anthropic:** ```sql -SET ai_nl2sql_provider='anthropic'; -SET ai_nl2sql_provider_url='https://api.anthropic.com/v1/messages'; -SET ai_nl2sql_provider_model='claude-3-haiku'; -SET ai_nl2sql_provider_key='sk-ant-...'; -LOAD MYSQL VARIABLES TO RUNTIME; +SET genai-nl2sql_provider='anthropic'; +SET genai-nl2sql_provider_url='https://api.anthropic.com/v1/messages'; +SET genai-nl2sql_provider_model='claude-3-haiku'; +SET genai-nl2sql_provider_key='sk-ant-...'; +LOAD GENAI VARIABLES TO RUNTIME; ``` **Using any OpenAI-compatible endpoint:** @@ -72,37 +72,39 @@ LOAD MYSQL VARIABLES TO RUNTIME; This works with **any** OpenAI-compatible API (vLLM, LM Studio, Z.ai, etc.): ```sql -SET ai_nl2sql_provider='openai'; -SET ai_nl2sql_provider_url='https://your-endpoint.com/v1/chat/completions'; -SET ai_nl2sql_provider_model='your-model-name'; -SET ai_nl2sql_provider_key='your-api-key'; -- Empty for local endpoints -LOAD MYSQL VARIABLES TO RUNTIME; +SET genai-nl2sql_provider='openai'; +SET genai-nl2sql_provider_url='https://your-endpoint.com/v1/chat/completions'; +SET genai-nl2sql_provider_model='your-model-name'; +SET genai-nl2sql_provider_key='your-api-key'; -- Empty for local endpoints +LOAD GENAI VARIABLES TO RUNTIME; ``` ### 3. Use NL2SQL ```sql --- In your SQL client, prefix your query with "NL2SQL:" -mysql> SELECT * FROM runtime_mysql_servers WHERE variable_name='ai_nl2sql_enabled'; +-- Verify NL2SQL is enabled (run this in the Admin interface) +SHOW VARIABLES LIKE 'genai-nl2sql%'; --- Query converted to SQL +-- Use NL2SQL in your MySQL client (MySQL module, not Admin) mysql> NL2SQL: Show top 10 customers by revenue; ``` +**Important**: NL2SQL queries are executed in the **MySQL module** (your regular SQL client), not in the ProxySQL Admin interface. The Admin interface is only for configuration. + ## Configuration ### Variables | Variable | Default | Description | |----------|---------|-------------| -| `ai_nl2sql_enabled` | true | Enable/disable NL2SQL | -| `ai_nl2sql_query_prefix` | NL2SQL: | Prefix for NL2SQL queries | -| `ai_nl2sql_provider` | openai | Provider format: `openai` or `anthropic` | -| `ai_nl2sql_provider_url` | http://localhost:11434/v1/chat/completions | Endpoint URL | -| `ai_nl2sql_provider_model` | llama3.2 | Model name | -| `ai_nl2sql_provider_key` | (none) | API key (optional for local endpoints) | -| `ai_nl2sql_cache_similarity_threshold` | 85 | Semantic similarity threshold (0-100) | -| `ai_nl2sql_timeout_ms` | 30000 | LLM request timeout in milliseconds | +| `genai-nl2sql_enabled` | false | Enable/disable NL2SQL | +| `genai-nl2sql_query_prefix` | NL2SQL: | Prefix for NL2SQL queries | +| `genai-nl2sql_provider` | openai | Provider format: `openai` or `anthropic` | +| `genai-nl2sql_provider_url` | http://localhost:11434/v1/chat/completions | Endpoint URL | +| `genai-nl2sql_provider_model` | llama3.2 | Model name | +| `genai-nl2sql_provider_key` | (none) | API key (optional for local endpoints) | +| `genai-nl2sql_cache_similarity_threshold` | 85 | Semantic similarity threshold (0-100) | +| `genai-nl2sql_timeout_ms` | 30000 | LLM request timeout in milliseconds | ### Request Configuration (Advanced) @@ -156,7 +158,7 @@ This allows tracing a single request through all log lines for debugging. The system automatically selects the best model based on: -1. **Provider format**: Uses `ai_nl2sql_provider` setting (openai or anthropic) +1. **Provider format**: Uses `genai-nl2sql_provider` setting (openai or anthropic) 2. **API key availability**: For cloud endpoints, API key is required 3. **Local endpoints**: API key is optional for local endpoints (localhost, 127.0.0.1) @@ -285,12 +287,14 @@ NL2SQL [request-id]: Request succeeded after 1 retries 1. **Try a different model:** ```sql - SET ai_nl2sql_provider_model='gpt-4o'; + SET genai-nl2sql_provider_model='gpt-4o'; + LOAD GENAI VARIABLES TO RUNTIME; ``` 2. **Increase timeout for complex queries:** ```sql - SET ai_nl2sql_timeout_ms=60000; + SET genai-nl2sql_timeout_ms=60000; + LOAD GENAI VARIABLES TO RUNTIME; ``` 3. **Check confidence score:** @@ -305,7 +309,7 @@ NL2SQL [request-id]: Request succeeded after 1 retries -- TODO: Add cache clearing command -- Check cache stats -SELECT * FROM stats_ai_nl2sql_cache; +SHOW STATUS LIKE 'genai-nl2sql%'; ``` ## Performance @@ -319,7 +323,7 @@ SELECT * FROM stats_ai_nl2sql_cache; **Tips for better performance:** - Use local Ollama for faster responses - Enable caching for repeated queries -- Use `ai_nl2sql_timeout_ms` to limit wait time +- Use `genai-nl2sql_timeout_ms` to limit wait time - Consider pre-warming cache with common queries ## Security