npx skills add ...
npx skills add exploreomni/omni-claude-skills --skill omni-query
npx skills add exploreomni/omni-claude-skills --skill omni-query
Run queries against Omni Analytics' semantic layer using the REST API, interpret results, and chain queries for multi-step analysis. Use this skill whenever someone wants to query data through Omni, run a report, get metrics, pull numbers, analyze data, ask "how many", "what's the trend", "show me the data", retrieve dashboard query results, or perform any data retrieval through Omni's query engine. Also use when someone wants to programmatically extract data from an existing Omni dashboard or workbook.
Run queries against Omni's semantic layer via the REST API. Omni translates field selections into optimized SQL — you specify what you want (dimensions, measures, filters), not how to get it.
Tip: Use
omni-model-explorerfirst if you don't know the available topics and fields.
You also need a model ID and knowledge of available topics and fields.
When unsure whether an endpoint or parameter exists, fetch the OpenAPI spec:
Use this to verify endpoints, available parameters, and request/response schemas before making calls.
| Parameter | Required | Description |
|---|---|---|
modelId | Yes | UUID of the Omni model |
table | Yes | Base view name (the FROM clause) |
fields | Yes | Array of view.field_name references |
join_paths_from_topic_name | Recommended | Topic for join resolution |
limit | No | Row limit (default 1000, max 50000, null for unlimited) |
sorts | No | Array of sort objects |
filters | No | Filter object |
pivots | No | Array of field names to pivot on |
Fields use view_name.field_name. Date fields support timeframe brackets:
Expressions: "last 90 days", "this quarter", "2024-01-01 to 2024-12-31", "not California", "null", "not null", ">100", "between 10 and 100", "contains sales", "starts with A". See references/filter-expressions.md for the complete expression syntax reference.
Default response: base64-encoded Apache Arrow table. Arrow results are binary — you cannot parse individual row data from the raw response. To verify a query returned data, check summary.row_count in the response.
For human-readable results, request CSV instead:
If the response includes remaining_job_ids, poll until complete:
Extract and re-run queries powering existing dashboards:
For complex analysis, chain queries:
Time Series: fields + date dimension + ascending sort + date filter
Top N: fields + metric + descending sort + limit
Aggregation with Breakdown: multiple dimensions + multiple measures + descending sort by key metric
IS_NOT_NULL filter generates IS NULL (reported Omni bug) — workaround: invert the filter logic or use the base view to apply the filter differently.pivots array is present — if boolean filters aren't applying, remove the pivot and test again.Queries are ephemeral — there is no persistent URL for a query result. To give the user a shareable link:
{OMNI_BASE_URL}/dashboards/{identifier} (the identifier comes from the document API response)omni-content-builder with the query as a queryPresentation, then share {OMNI_BASE_URL}/dashboards/{identifier}curl -L -X POST "$OMNI_BASE_URL/api/v1/query/run" \
-H "Authorization: Bearer $OMNI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": {
"modelId": "your-model-id",
"table": "order_items",
"fields": [
"order_items.created_at[month]",
"order_items.total_revenue"
],
"limit": 100,
"join_paths_from_topic_name": "order_items"
}
}'users.created_at[date] — Daily
users.created_at[week] — Weekly
users.created_at[month] — Monthly
users.created_at[quarter] — Quarterly
users.created_at[year] — Yearly"sorts": [
{ "column_name": "order_items.total_revenue", "sort_descending": true }
]"filters": {
"order_items.created_at": "last 90 days",
"order_items.status": "complete",
"users.state": "California,New York"
}{
"query": {
"fields": ["order_items.created_at[month]", "order_items.status", "order_items.count"],
"pivots": ["order_items.status"],
"join_paths_from_topic_name": "order_items"
}
}{ "query": { ... }, "resultType": "csv" }import base64, pyarrow as pa
arrow_bytes = base64.b64decode(response["data"])
reader = pa.ipc.open_stream(arrow_bytes)
df = reader.read_all().to_pandas()curl -L -X POST "$OMNI_BASE_URL/api/v1/query/wait" \
-H "Authorization: Bearer $OMNI_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "jobIds": ["job-id-1", "job-id-2"] }'# Get all queries from a dashboard
curl -L "$OMNI_BASE_URL/api/v1/documents/{dashboardId}/queries" \
-H "Authorization: Bearer $OMNI_API_KEY"
# Run as a specific user
{ "query": { ... }, "userId": "user-uuid-here" }
# Cache policy (valid values: Standard, SkipRequery, SkipCache)
{ "query": { ... }, "cache": "SkipCache" }