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]

Beyond Queries: Advanced Capabilities​

Once you're comfortable with natural language queries, explore Actyze's full platform:

Smart Relationship Graph​

Actyze learns how your tables connect — from naming conventions, query history, and admin input — so JOINs are accurate instead of guessed.

  • Navigate to Data Intelligence → Relationships to view and manage table connections
  • Click Mine Query History to discover JOIN patterns from past successful queries
  • Verify or disable relationships to fine-tune SQL accuracy
"Show orders with country names"
→ Graph finds path: orders → customers → nations
→ AI generates correct two-JOIN query automatically

→ Relationship Graph Guide

Scheduled KPIs​

Automate data collection and build a gold layer without ETL:

  1. Navigate to Scheduled KPIs in the sidebar
  2. Click Create KPI, write a SQL query (or import from saved queries)
  3. Set collection interval (1–24 hours)
  4. Data materializes as a real table, queryable via natural language
"Show me daily revenue trends" → AI discovers your KPI table automatically

→ Scheduled KPIs Guide

Predictive Intelligence​

Build ML models from your data without code:

  1. Navigate to Predictive Intelligence in the sidebar
  2. Choose: Forecast, Classify, Estimate, or Detect Anomalies
  3. Select your data source (KPI table or custom SQL)
  4. Click Train — Actyze validates data quality, selects the best model, and trains
"Show churn predictions" → AI finds your prediction output table

→ Predictive Intelligence Guide

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​

Explore Features​

Configure & Optimize​

Integrate​

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!