Skip to content
M↓ View as Markdown ↗

Semantic SQL (SemQL)

SemQL is the query language Actian AI Analyst uses to query your data. SemQL accepts portable, standard analytical SQL. The difference is that instead of physical tables and columns, you reference the business concepts in your semantic layer: Models, Dimensions, Measures and Filters.

Database-specific syntax, such as PostgreSQL's DISTINCT ON or ~ regex matching, is refused with a suggestion for the portable form.

-- Instead of this (raw SQL):
SELECT o.organization_name, COUNT(DISTINCT u.user_id) AS user_count
FROM analytics_marts.dim_app_organizations o
JOIN analytics_marts.dim_app_users u ON o.organization_id = u.organization_id
WHERE o.current_member_count > 0
GROUP BY o.organization_name

-- You write this (SemQL):
SELECT name, user_count
FROM organizations[active_only]
GROUP BY name

Same result, without table schemas, guessed column names or re-implemented business logic.

Your database still runs SQL. AI Analyst compiles each SemQL query into your database's own SQL dialect (Snowflake, BigQuery, Amazon Redshift and more) every time it runs. See Compilation & Dialects.

New to SemQL? Start with the SemQL overview.

Why AI Analyst uses SemQL

When you ask "Show me revenue by region for last quarter", AI Analyst needs to write a query. With raw SQL, it would have to work out:

  • The exact table and column names in your schema
  • How your team defines "revenue" (which columns, which exclusions)
  • What "last quarter" means in your data
  • Which tables to join, and on which columns

With SemQL, it references total_revenue and region. Your semantic layer already defines:

  • total_revenue, for example SUM(amount - refunds)
  • region, a Dimension of the customers Model
  • The relationship between the two Models, on customer_id

AI Analyst uses the definitions your data team controls instead of inventing its own, so metrics stay consistent from one question to the next.

Rules at a glance

  • Read-only statements. Only SELECT queries are accepted, so a SemQL query can't contain statements that change data. SemQL alone doesn't guarantee read-only access, because some connectors can't enforce it. Connect with a read-only database user.
  • Your Models only. A query can only use the Models, Dimensions and Measures granted to the AI Analyst you chose for the conversation. Anything else is refused with an "Access denied" error. See Models in the AI Analyst configuration.
  • One data source per query. All Models in a query must come from the same data connection. A query that mixes Models from different data connections is refused, and the error names each data source.
  • Default Filters always apply. A Filter with Apply to every query turned on is applied to every query on its Model, and AI Analyst cannot turn it off.
  • One Workspace. The semantic layer belongs to a Workspace, so a query only sees the Models in the active Workspace.
  • Measures are already aggregated. Never wrap a Measure in SUM() or another aggregate. See Dimensions, Measures & Filters.

What's in this section

  • Core Syntax: the full SemQL syntax, including SELECT, FROM, WHERE, joins, CTEs, set operations, window functions and common functions
  • Dimensions, Measures & Filters: the most important concepts in SemQL, and why you never wrap a Measure in SUM()
  • Geo Functions: GEO_DISTANCE() and GEO_WITHIN_RADIUS() for location-based queries
  • Examples: queries for common analytical scenarios, from simple to complex
  • Compilation & Dialects: how SemQL is compiled, which databases are supported, and what each database doesn't support