Skip to main content

Quick Start Guide

Learn how to use Actyze to query your data using natural language.

Prerequisites​

Before starting, ensure you have:

  • Actyze installed (Docker or Helm)
  • LLM provider configured (Configuration Guide)
  • Database connected (Trino or PostgreSQL)
  • Services running and healthy

Step 1: Access Actyze​

Open your browser and navigate to:

  • Local (Docker): http://localhost:3000
  • Kubernetes: Your configured ingress URL or port-forwarded address

Step 2: Your First Query​

Natural Language Query​

In the query interface, type a question in plain English:

Show me all customers from California

What Happens Next​

  1. Schema Detection: Actyze uses FAISS and spaCy to identify relevant tables
  2. SQL Generation: Your LLM provider generates accurate SQL
  3. Query Execution: SQL runs against your database (Trino/PostgreSQL)
  4. Results Display: Data appears in a formatted table

Generated SQL Example​

SELECT *
FROM customers
WHERE state = 'California'

Step 3: Explore More Queries​

Simple Aggregations​

What is the total revenue for 2025?

Generates:

SELECT SUM(revenue) as total_revenue
FROM sales
WHERE year = 2025

Grouping and Filtering​

Show top 10 products by sales in Q4

Generates:

SELECT product_name, SUM(quantity) as total_sales
FROM sales
WHERE quarter = 'Q4'
GROUP BY product_name
ORDER BY total_sales DESC
LIMIT 10

Joins Across Tables​

List customers with their total order value

Generates:

SELECT 
  c.customer_name,
  SUM(o.order_total) as total_value
FROM customers c
JOIN orders o ON c.customer_id = o.customer_id
GROUP BY c.customer_name
ORDER BY total_value DESC

Time-Based Analysis​

Compare monthly revenue for 2024 vs 2025

Generates:

SELECT 
  month,
  SUM(CASE WHEN year = 2024 THEN revenue ELSE 0 END) as revenue_2024,
  SUM(CASE WHEN year = 2025 THEN revenue ELSE 0 END) as revenue_2025
FROM sales
WHERE year IN (2024, 2025)
GROUP BY month
ORDER BY month

Step 4: Understanding Results​

Table View​

Results appear in an interactive table with:

  • Sorting: Click column headers to sort
  • Filtering: Search within results
  • Export: Download as CSV or Excel

Visualization​

Actyze can automatically suggest visualizations:

  • Bar charts for comparisons
  • Line charts for trends
  • Pie charts for distributions

Step 5: Query History​

View Past Queries​

Access your query history to:

  • Rerun previous queries
  • Share queries with team members
  • Build on previous work

Save Queries​

Save frequently used queries as templates:

  1. Run your query
  2. Click "Save Query"
  3. Give it a descriptive name
  4. Access from "Saved Queries" menu

Common Query Patterns​

Filtering Data​

Show orders from last week
Show products with price > $100
Find customers in New York or California

Aggregations​

Calculate average order value
Count total number of transactions
Sum revenue by region

Rankings​

Top 5 customers by revenue
Bottom 10 performing products
Most frequent buyers

Date Ranges​

Sales for last 30 days
Year-over-year comparison
Monthly trends for 2025

Tips for Better Results​

Be Specific​

Vague: "Show sales" Specific: "Show total sales by region for Q4 2025"

Use Business Terms​

Actyze understands your business terminology:

  • "Revenue" → maps to revenue or sales_amount
  • "Customers" → maps to customers or clients table
  • "Last quarter" → automatically calculates date range

Refine Queries​

If results aren't what you expected:

  1. Add more context: "Show sales for California only"
  2. Specify time ranges: "for the last 6 months"
  3. Add sorting: "ordered by date descending"

Use Conversation History​

Actyze remembers context within a session:

You: Show all customers
Actyze: [Returns customer list]

You: Now filter for California
Actyze: [Filters previous results for California]

You: Sort by revenue
Actyze: [Sorts California customers by revenue]

Advanced Features​

Schema Exploration​

Ask Actyze about your data structure:

What tables contain customer information?
Show me the schema for the sales table
What columns are in the orders table?

Complex Joins​

Show customers with their orders and order items
Join sales data with product information
Combine customer demographics with purchase history

Window Functions​

Calculate running total of sales
Show rank of products by revenue
Moving average of daily sales

Troubleshooting​

Query Returns No Results​

Check:

  • Is the table name correct?
  • Does the filter match your data?
  • Are there any typos in your query?

Try:

Show me all records from [table_name]

SQL Generation Errors​

Common causes:

  • Ambiguous table names
  • Missing schema context
  • Complex business logic

Solution:

  • Be more specific in your query
  • Verify table/column names exist
  • Break complex queries into steps

Performance Issues​

For large datasets:

  • Add time range filters
  • Limit results: "Show top 100..."
  • Use aggregations instead of raw data

Next Steps​

Learn More​

Get Help​

  • Documentation: Browse other guides
  • GitHub: Report issues
  • Community: Join our discussions

Example Use Cases​

Business Intelligence​

What were our top 10 products by revenue last quarter?
Show customer churn rate by region
Calculate year-over-year growth for each product category

Operations​

How many orders are pending shipment?
Show inventory levels below reorder point
List suppliers with late deliveries

Finance​

Calculate monthly recurring revenue
Show accounts receivable aging
Compare actual vs budgeted expenses

Sales Analytics​

Which products have the highest conversion rate?
Show customer acquisition trends over time
Calculate average deal size by sales rep

Best Practices​

  1. Start Simple: Begin with basic queries and add complexity
  2. Verify Results: Check a few rows to ensure accuracy
  3. Save Frequently Used Queries: Build a library of templates
  4. Use Filters: Narrow down data for faster results
  5. Leverage History: Build on previous successful queries

Support​

Need help? We're here for you:

Happy querying!