> ## 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

<Frame>
  <img src="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" alt="Text to SQL" width="1784" height="510" data-path="images/how-it-works/ana/modes/Text to SQL.png" />
</Frame>

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.
</Note>

## <Icon icon="gears" iconType="solid" /> How It Works

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

<Steps>
  <Step title="Analyze Your Question">
    Ana parses your natural language question to understand what data you're looking for.
  </Step>

  <Step title="Examine Database Schema">
    Inspects your database structure to identify relevant tables and columns.
  </Step>

  <Step title="Generate SQL Query">
    Constructs an optimized SQL query in your warehouse's specific dialect.
  </Step>

  <Step title="Execute Query">
    Runs the query against your data warehouse securely.
  </Step>

  <Step title="Load Results">
    Automatically loads results as a pandas DataFrame in the Python sandbox for further analysis.
  </Step>
</Steps>

<Frame caption="SQL Query Tool in action">
  <img src="https://mintcdn.com/textql/_MjEsXv_WMgj05pB/images/tool/sql.png?fit=max&auto=format&n=_MjEsXv_WMgj05pB&q=85&s=21375163f7f1cb606584d6019cbdb3e4" alt="SQL Query Tool in action" width="3342" height="1922" data-path="images/tool/sql.png" />
</Frame>

## <Icon icon="circle-check" iconType="solid" /> When to Use

<CardGroup cols={2}>
  <Card title="Data Exploration" icon="magnifying-glass">
    "Show me the top 10 customers by revenue"
  </Card>

  <Card title="Trend Analysis" icon="chart-line">
    "What are our monthly sales for the past year?"
  </Card>

  <Card title="Aggregations" icon="calculator">
    "Calculate the average order value by region"
  </Card>

  <Card title="Filtering & Joining" icon="filter">
    "Find all orders from customers in California with a value over \$1000"
  </Card>
</CardGroup>

## <Icon icon="plug-circle-check" iconType="solid" /> Available For

All connected database connectors:

<AccordionGroup>
  <Accordion title="Cloud Data Warehouses" icon="cloud">
    * **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>

  <Accordion title="Traditional Databases" icon="database">
    * **Postgres** - Open source relational database
    * **MySQL** - Popular open source database
    * **Amazon Aurora MySQL** - AWS managed database
    * **Supabase** - Open source Firebase alternative
  </Accordion>

  <Accordion title="Specialized Databases" icon="layer-group">
    * **ClickHouse** - OLAP database for analytics
    * **Motherduck** - Serverless analytics
    * **Athena** - AWS serverless query service
  </Accordion>
</AccordionGroup>

## <Icon icon="lightbulb" iconType="solid" /> Best Practices

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

<CardGroup cols={2}>
  <Card title="Be Specific" icon="bullseye">
    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>

  <Card title="Mention Table Names" icon="table">
    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>

  <Card title="Specify Time Ranges" icon="clock">
    Always include date ranges when querying time-series data for better performance.

    **Example:** "Sales from January 1, 2024 to March 31, 2024"
  </Card>

  <Card title="Review the Query" icon="eye">
    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.
  </Card>
</CardGroup>

<Warning>
  **Performance Note:** For large tables, be specific with your filters and time ranges to avoid long-running queries that may time out.
</Warning>