> ## Documentation Index
> Fetch the complete documentation index at: https://docs.textql.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Text to SQL

> Convert natural language to SQL queries

![Text to SQL](https://mintcdn.com/textql/wnLSBqpI2oAn0dxe/images/how-it-works/ana/modes/Text%20to%20SQL.png?fit=max\&auto=format\&n=wnLSBqpI2oAn0dxe\&q=85\&s=8185b248c2e94a1018e54d316d169a97)

Converts natural language questions into SQL queries and fetches data from your connected data warehouses. Results are automatically loaded as pandas DataFrames into the Python sandbox.

> [!NOTE]
>
> This is Ana's **primary tool for data retrieval** from your connected databases and warehouses.

##  How It Works

When you ask a question, Ana intelligently processes your request through these steps:

**1. Analyze Your Question**

Ana parses your natural language question to understand what data you're looking for.

**2. Examine Database Schema**

Inspects your database structure to identify relevant tables and columns.

**3. Generate SQL Query**

Constructs an optimized SQL query in your warehouse's specific dialect.

**4. Execute Query**

Runs the query against your data warehouse securely.

**5. Load Results**

Automatically loads results as a pandas DataFrame in the Python sandbox for further analysis.

![SQL Query Tool in action](https://mintcdn.com/textql/_MjEsXv_WMgj05pB/images/tool/sql.png?fit=max\&auto=format\&n=_MjEsXv_WMgj05pB\&q=85\&s=21375163f7f1cb606584d6019cbdb3e4)

SQL Query Tool in action

##  When to Use

> [card] Data Exploration
>
> "Show me the top 10 customers by revenue"

> [card] Trend Analysis
>
> "What are our monthly sales for the past year?"

> [card] Aggregations
>
> "Calculate the average order value by region"

> [card] Filtering & Joining
>
> "Find all orders from customers in California with a value over \$1000"

##  Available For

All connected database connectors:

> [accordion] Cloud Data Warehouses
>
> * **Snowflake** - Cloud data platform
> * **BigQuery** - Google Cloud data warehouse
> * **Redshift** - Amazon Web Services data warehouse
> * **Databricks** - Lakehouse platform
> * **Azure Synapse Analytics** - Microsoft cloud analytics

> [accordion] Traditional Databases
>
> * **Postgres** - Open source relational database
> * **MySQL** - Popular open source database
> * **Amazon Aurora MySQL** - AWS managed database
> * **Supabase** - Open source Firebase alternative

> [accordion] Specialized Databases
>
> * **ClickHouse** - OLAP database for analytics
> * **Motherduck** - Serverless analytics
> * **Athena** - AWS serverless query service

##  Best Practices

> [!TIP]
>
> **Pro Tip:** The more specific and detailed your question, the more accurate the generated SQL will be!

> [card] Be Specific
>
> Include details like column names, table names, and exact metrics you want to calculate.
>
> **Good:** "Show me total revenue from the `orders` table grouped by month"
>
> **Vague:** "Show me sales"

> [card] Mention Table Names
>
> If you know the table names, include them in your question to help Ana target the right data.
>
> **Example:** "Query the `customers` table for users who signed up this year"

> [card] Specify Time Ranges
>
> Always include date ranges when querying time-series data for better performance.
>
> **Example:** "Sales from January 1, 2024 to March 31, 2024"

> [card] Review the Query
>
> Check the generated SQL to ensure it matches your intent and doesn't miss any important filters.
>
> You can view both the SQL query and the results in the chat interface.

> [!WARNING]
>
> **Performance Note:** For large tables, be specific with your filters and time ranges to avoid long-running queries that may time out.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.