SQL AI - Your SQL Assistant

SQL AI, your intelligent SQL assistant in the Amorphic Cloud Platform! This powerful feature leverages advanced Large Language Models (LLMs) to simplify your data querying experience. Whether you're a SQL expert or new to database queries, SQL AI helps you interact with your datasets using natural language, making data exploration more intuitive and accessible.

With SQL AI, you can:

• Convert natural language questions into SQL queries
• Generate SQL code without writing complex syntax
• Get explanations for existing SQL queries
• Receive suggestions for exploring your datasets
• Execute generated queries directly from the interface and retrieve results
• Visualize query results in interactive charts
• Interact with your data using plain English

This guide will walk you through everything you need to know to leverage SQL AI's capabilities effectively.

Getting Started

Overview

SQL AI is a generative AI add-on that bridges the gap between natural language and SQL. It enables you to:

• Ask questions about your data in plain English
• Generate ready-to-use SQL queries from conversational prompts
• Understand existing SQL code through clear explanations
• Execute queries and retrieve results
• Visualize query results with interactive charts and graphs

The system supports domain-specific queries, ensuring datasets in different domains are easily distinguishable, even if they share the same name. SQL AI operates within the Playground's workbook interface, where you can maintain conversation history and manage multiple data exploration sessions.

Workbooks

SQL AI is integrated into the Playground's workbook interface, providing a powerful way to organize your AI-assisted SQL queries and conversations.

Workbook Interface

Each workbook in the Playground serves as a separate workspace for your SQL AI interactions:

• Dedicated SQL AI Sessions: Each workbook maintains its own SQL AI conversation history, allowing you to have separate AI-assisted query sessions for different projects or analysis tasks
• Query Window Integration: The SQL AI button is prominently displayed in the Query Window of each workbook, providing easy access to AI assistance for your queries. The button is located at the top-right of the Query Window, next to the settings icon. The workbook window displays the last query that was run in that specific workbook, making it easy to continue your SQL AI conversation context.
• Results Management: Query results and visualizations generated through SQL AI are displayed within the same workbook, keeping your analysis organized

Managing SQL AI Workbooks

• Create New Workbook: Click the '+' icon to create a new workbook and start a fresh SQL AI conversation session
• Multiple Concurrent Sessions: Switch between workbooks to maintain multiple independent SQL AI conversations, each with its own context and history. Each workbook displays the last query that was executed in that workbook.
• Workbook Tabs: Workbooks appear as tabs at the top of the interface (e.g., "History", "River Data", "New Workbook"), making it easy to navigate between different sessions
• Delete Workbooks: Use the 'x' icon on workbook tabs to permanently delete workbooks you no longer need

Benefits of Workbook-Based SQL AI

Using workbooks with SQL AI offers several advantages:

• Context Isolation: Each workbook maintains its own conversation context, preventing cross-contamination between different analysis tasks
• Organized Analysis: Keep separate workbooks for different datasets, projects, or analysis goals
• Flexible Workflow: Start new workbooks for exploratory queries while keeping your main analysis sessions separate

Note

The History tab shows all queries executed across the entire system, not just within a specific workbook. This provides a centralized view of all your query executions from any workbook.

Supported Data Sources

SQL AI currently supports:

• S3-Athena datasets

  • Standard S3 datasets accessible through AWS Athena
  • Supports querying structured data in various formats (Parquet, ORC, CSV)

• Redshift datasets

  • Data stored in Amazon Redshift clusters
  • Supports both provisioned and Redshift Serverless workgroups

• System datasets

  • Datasets created using Amorphic's system features
  • Includes sys_cost_analysis_table, api-sys_cloudtrail_logs, etc. tables to query upon (System Datasets)

Note

All datasets must be properly registered in the Amorphic platform to be accessible via SQL AI. For optimal performance, ensure that your datasets have complete and accurate metadata configured.

Key Features

Natural Language to SQL Translation

SQL AI leverages powerful LLMs to interpret your inquiries in natural language, converting them into executable SQL queries. This reduces the need for technical expertise, allowing you to ask questions in plain language while receiving the corresponding SQL code or results.

Feature	Description
Natural language processing	Converts English questions into SQL queries
Domain-specific queries	Distinguishes between datasets with the same name in different domains
Case-sensitive querying	Matches resource names exactly as created

Note

• When querying datasets with the same name but in different domains, use [domain-name].[dataset-name] for accurate results. (Querying is case-sensitive; resource names must match their exact case as created.)
• Alternatively, you can select the dataset from the dropdown list.
• It is recommended to use clear column names and descriptions in datasets to provide better context, improving query accuracy.
• Generated queries are based on the schema of the data source and not the actual data.

Interactive Query Categories

SQL AI supports five main categories of interaction:

Category	Description	Example
Natural Language Suggestions	Get insights and suggestions about your data	"Suggest some queries I can run on the sales dataset."
Query Generation	Convert natural language into SQL code	"Generate a query to find the top 10 salespeople by revenue."
Query Explanation	Understand what existing SQL code does	"Explain this query: SELECT * FROM orders WHERE order_date > '2023-01-01'"
Query Execution	Request SQL AI to execute queries and return results	"Get me the results" or "Execute this query"
Data Visualization	Generate charts and visualizations from query results	"Visualize it in a bar chart" or "Show me a line graph"

Once a query is generated, you can ask SQL AI to execute it for you and it will execute and retrieve the results within the conversation interface.

Model Customization

SQL AI offers flexibility in choosing between multiple LLM models for query generation and explanation: The models that can be used for SQL AI can be configured in the Assign Models section.

Note

SQL AI model configuration is limited to Anthropic Claude models, as they provide the best performance and accuracy for SQL generation. It is recommended to use Claude Sonnet 4 for optimal results.

Resource Selection

You can prompt SQL AI on resources in the following ways:

1. Select the resource from the Chat Configuration panel dropdown list
2. Select resources from the Explorer sidebar - use the dataset context menu options to quickly work with datasets
3. Enter the dataset name in your prompt
4. Enter the domain name followed by the dataset name in your prompt

The Chat Configuration panel allows you to:

• Select the model to be used
• Select multiple datasets/views for cross-dataset queries
• Select the target location of the dataset (s3athena/redshift)
• Set the Query Auto-Run configuration

Best Practices

• At least one resource must be selected for query suggestions or generation-related prompts to work
• For optimal results, select only the resources relevant to your question
• Selecting more than 20 resources is not recommended, as responses may become inaccurate due to context limitations
• The Chat Configuration panel provides easy access to manage your selected datasets before sending prompts

Query Execution and Target Configuration

Generated queries can be executed directly from SQL AI with configurable execution settings:

• Target Location: Select the execution engine (Athena, Redshift, etc.) through the Chat Configuration panel or query window
• Auto Run Configuration: Controls how SQL AI handles query execution:
  • Enabled: SQL AI automatically generates the query, executes it, and retrieves results without requiring user confirmation
  • Disabled: SQL AI generates the query and prompts for user confirmation before execution

Note

The default Auto-Run configuration can be set by administrators in the System Settings page. This default value applies when users haven't explicitly configured their preference in the Chat Configuration panel.

• Error Handling and Retry: In case of query execution failures, SQL AI will:
  • Prompt the user with the error message for guidance
  • Wait for user confirmation before retrying
  • Retry query generation (only after user confirms) incorporating the failure message to create an improved query
  • Learn from errors to avoid similar issues in subsequent attempts
• Results View: View query results in a table format with comprehensive viewing capabilities:
  • Results are displayed in the Results section below the Query Window
  • Search functionality allows filtering results in real-time
  • Fullscreen view option for better visibility of large datasets
  • Up to 50 records displayed initially
• Export Options: Multiple export capabilities for query results:
  • Export to Dataset: Save results directly to a new or existing dataset within the Amorphic platform
  • Download: Download complete result sets to your local machine in various formats (CSV, Excel, etc.)

Data Visualization

SQL AI can automatically generate visualizations for your query results:

• Automatic Chart Generation: When you request visualizations, SQL AI generates appropriate chart types (bar charts, line charts, etc.)
• Plot Visualization Card: Results are displayed in an interactive card within the conversation
• Visualization View Panel: A dedicated right-hand panel displays full-screen, interactive visualizations
• Download Visualizations: Export charts for use in reports and presentations
• Multiple Chart Types: Supports various visualization types based on your data and query requirements

Simply ask SQL AI to "visualize" your results or request specific chart types like "show me a bar chart" or "create a line graph" to generate interactive visualizations.

Use Cases

Query Suggestions

When you need ideas for exploring your data, SQL AI can suggest useful queries. The AI can generate comprehensive analytical questions covering various business areas including product performance, revenue optimization, regional comparisons, customer behavior patterns, and operational insights.

Example Prompt: "Suggest some queries I can run on the sales dataset."

SQL AI Response: I've generated 10 analytical questions covering key business areas including:

1. "What are the top-selling products by quantity and revenue across different product categories?"
2. "What are the most popular payment methods used by customers, and how does payment method correlate with order value?"
3. "Which customers are the top purchasers by total spending, and what are their buying patterns?"
4. "What is the daily sales trend throughout April 2025, and are there any notable peaks or dips in sales activity?"
5. "How does the relationship between discount offered and return rate vary across different regions and product categories?"

These questions will help you explore sales trends, identify top performers, understand customer preferences, and optimize your business strategy.

You can ask SQL AI to help execute any of these analyses or explore a specific area in more detail.

Note

Occasionally, implementing the suggested responses verbatim may not produce optimal results. For best outcomes, please incorporate prefixes such as 'Generate a query or SQL' when formulating your questions.

SQL Generation

When you need to query your data but prefer not to write SQL code manually:

Example Prompt: "Generate a query to retrieve top 10 salespeople sorted in ascending order by sales amount."

SQL AI Response:

SELECT
    salesperson_name,
    SUM(sales_amount) as total_sales
FROM
    sales_domain.sales_data
GROUP BY
    salesperson_name
ORDER BY
    total_sales ASC
LIMIT 10;

SQL Explanation

When you need to understand an existing SQL query, SQL AI provides detailed, structured explanations with clear breakdowns:

Example Prompt: "Explain this query: SELECT product, SUM(CAST(quantity AS INTEGER)) as total_quantity_sold, COUNT(*) as number_of_orders, SUM(CAST(quantity AS INTEGER) * CAST(price AS DECIMAL(10,2))) as total_revenue FROM sales2025.sales_april WHERE returned != 'Yes' GROUP BY product ORDER BY total_quantity_sold DESC LIMIT 10;"

SQL AI Response: SQL Query Analysis: Top 10 Products by Quantity Sold

Query Overview: This query analyzes sales performance by identifying the top 10 products with the highest total quantities sold from April 2025 sales data, excluding returned items.

Query Breakdown:

• SELECT Clause - Calculated Metrics: Calculates total quantity sold, number of orders, and total revenue per product. Since all columns are varchar, the quantity is cast to INTEGER for proper numerical operations.
• FROM Clause: Sources data from the sales_april table in the sales2025 domain
• WHERE Clause: Filters out returned items (WHERE returned != 'Yes') to focus on actual sales. The query handles potential NULL values in the returned column.
• GROUP BY Clause: Aggregates metrics by product
• ORDER BY Clause: Sorts results by total quantity sold in descending order to show the highest-selling products first
• LIMIT Clause: Restricts results to top 10 products

This query will efficiently identify your top-performing products by volume in April 2025, which is valuable for inventory planning, marketing focus, and business strategy decisions.

Geospatial Queries

SQL AI supports geospatial queries, allowing you to analyze location-based data and perform spatial operations. You can query geographic data, calculate distances, find points within boundaries, and perform other spatial analyses.

Example Prompt: "Find all stores within 10 miles of a specific location with coordinates latitude 40.7128 and longitude -74.0060."

SQL AI Response:

SELECT
    store_name,
    address,
    latitude,
    longitude,
    ST_Distance(
        ST_Point(longitude, latitude),
        ST_Point(-74.0060, 40.7128)
    ) * 69 as distance_miles
FROM
    retail_domain.store_locations
WHERE
    ST_Distance(
        ST_Point(longitude, latitude),
        ST_Point(-74.0060, 40.7128)
    ) * 69 <= 10
ORDER BY
    distance_miles ASC;

Note

SQL AI might not always select the most relevant geospatial functions for your queries. If you encounter issues, you can ask SQL AI to retry with additional context, or provide training data using the Train SQL AI feature to improve geospatial query accuracy.

Query Execution

SQL AI can execute generated queries and return results directly in the conversation interface. The behavior depends on the Query Auto-Run configuration:

When Auto-Run is Enabled:

Example Prompt: "Get me top 10 sold items"

SQL AI Response: SQL AI will automatically:

• Generate the SQL query
• Execute the query using the configured target location
• Fetch and display the results in a tabular format
• Offer options to export results or download as files

All of this happens automatically without requiring additional confirmation.

When Auto-Run is Disabled:

Example Prompt: "Get me top 10 sold items"

SQL AI Response: SQL AI will:

• Generate the SQL query
• Display the generated query and ask for your confirmation
• Wait for your approval (e.g., "yes get me the results" or "execute this query")
• Execute and retrieve results only after confirmation

Error Handling and Retry: If a query execution fails, SQL AI will:

• Display the error message to you
• Prompt you for guidance and ask if you want to retry
• Retry query generation only after you confirm (e.g., by saying "yes" or "retry"), incorporating the failure message to create an improved query that addresses the error
• Learn from the failure to prevent similar issues in future queries

Note

When Auto-Run is enabled, SQL AI automatically executes generated queries. These queries may scan large amounts of data and run for extended periods, which can result in costs based on the data scanned and query execution time.

Data Visualization

SQL AI can automatically generate visualizations from query results:

Example Prompt: "visualize it in a bar chart" or "show me the results as a bar chart"

SQL AI Response: SQL AI will:

• Generate code to visualize your results
• Display the chart in a "Plot Visualization" card within the conversation
• Provide a "Visualization View" panel on the right side for a full-screen, interactive view
• Show properly formatted charts with labeled axes (e.g., "Total Revenue by Product")
• Offer download and expand options for the visualization

The Visualization View panel provides a dedicated full-screen view of interactive content, making it easy to analyze trends, compare data points, and share your visualizations. Charts are automatically sized and formatted for optimal readability.

Note

Visualization generation may take some time to compute and render.

Limitations and Considerations

Current Limitations

• Query scope: The chatbot is limited to SQL-related actions mentioned above and cannot answer questions outside this context
• Query accuracy: Generated queries might not always be correct; precise prompts lead to more precise queries
• Geospatial queries: SQL AI might not always select relevant functions for geospatial queries. You can ask it to retry if this occurs. You can also provide additional context using the Train SQL AI feature
• Stopping queries: SQL AI does not offer a built-in way to stop running queries. You will need to use the DELETE /queries/{query-id} API endpoint to stop a query
• Redshift resources: For Redshift resources outside the default tenant, you need to manually add the tenant name as the generated queries use only the <domain>.<table_name> format instead of the required <tenant_name>.<domain_name>.<table_name> syntax
• Workgroup support: For query executions, only the primary workgroup is supported. Queries that require the Amazon Athena V3 Engine will not work
• Iceberg datasets: Iceberg datasets are not currently supported. Query generation might succeed, but executions may fail
• Lake Formation datasets: Lake Formation datasets are not supported
• WebSocket connections: WebSocket connections may timeout occasionally. You can close and re-open the workbook to fix this. If this doesn't work, reload the entire page

Tips for Better Results

To get the most out of SQL AI, consider these best practices:

1. Be specific in your prompts - Clearly state what data you're looking for
2. Mention column names when possible to improve query accuracy
3. Start simple and build complexity through follow-up prompts
4. Review generated queries before execution to ensure they match your intent
5. Provide context about your data and what you're trying to achieve

Improving Query Quality

Using clear and descriptive column names in your datasets will significantly improve SQL AI's ability to generate accurate queries. Consider adding comments and descriptions to your data schema when possible. You can also add training data for your datasets to improve SQL AI's context.