Queries
Olytix Core's GraphQL API provides query operations for accessing cubes, executing semantic queries, exploring lineage, and searching the semantic layer.
Cube Queries
List All Cubes
Retrieve all available cubes in your semantic layer.
query {
cubes {
name
title
description
}
}
Response:
{
"data": {
"cubes": [
{
"name": "orders",
"title": "Orders",
"description": "Order transactions and revenue metrics"
},
{
"name": "customers",
"title": "Customers",
"description": "Customer demographics and lifetime value"
}
]
}
}
Get a Specific Cube
Retrieve a cube by name with its measures and dimensions.
query {
cube(name: "orders") {
name
title
description
measures {
name
title
type
description
}
dimensions {
name
title
type
isPrimaryTimeDimension
}
segments {
name
title
}
}
}
Response:
{
"data": {
"cube": {
"name": "orders",
"title": "Orders",
"description": "Order transactions and revenue metrics",
"measures": [
{
"name": "total_revenue",
"title": "Total Revenue",
"type": "SUM",
"description": "Sum of all order amounts"
},
{
"name": "count",
"title": "Order Count",
"type": "COUNT",
"description": "Total number of orders"
}
],
"dimensions": [
{
"name": "region",
"title": "Region",
"type": "STRING",
"isPrimaryTimeDimension": false
},
{
"name": "order_date",
"title": "Order Date",
"type": "TIME",
"isPrimaryTimeDimension": true
}
],
"segments": [
{
"name": "completed_orders",
"title": "Completed Orders"
}
]
}
}
}
Get Dimension Values
Retrieve distinct values for a dimension.
query {
cube(name: "orders") {
dimensions {
name
values(limit: 10, search: "North") {
value
label
count
}
}
}
}
Semantic Queries
Execute a Query
Run a semantic query with measures and dimensions.
query {
query(
measures: ["orders.total_revenue", "orders.count"]
dimensions: ["orders.region", "orders.order_date"]
filters: [
{ member: "orders.status", operator: EQUALS, values: ["completed"] }
]
timeDimensions: [
{ dimension: "orders.order_date", granularity: MONTH, dateRange: ["2024-01-01", "2024-12-31"] }
]
order: [{ member: "orders.total_revenue", direction: DESC }]
limit: 100
) {
data
meta {
totalCount
executionTimeMs
fromCache
preAggregationUsed
}
}
}
Response:
{
"data": {
"query": {
"data": [
{
"orders.region": "NORTH",
"orders.order_date": "2024-01-01T00:00:00.000Z",
"orders.total_revenue": 125000.00,
"orders.count": 1523
},
{
"orders.region": "SOUTH",
"orders.order_date": "2024-01-01T00:00:00.000Z",
"orders.total_revenue": 98000.00,
"orders.count": 1245
}
],
"meta": {
"totalCount": 48,
"executionTimeMs": 42.5,
"fromCache": false,
"preAggregationUsed": null
}
}
}
}
Query with Time Dimensions
Execute a time-series query with granularity.
query MonthlyRevenue {
query(
measures: ["orders.total_revenue"]
timeDimensions: [
{
dimension: "orders.order_date"
granularity: MONTH
dateRange: ["2024-01-01", "2024-06-30"]
}
]
) {
data
meta {
executionTimeMs
}
}
}
Query with Segments
Apply pre-defined filter segments.
query CompletedOrdersRevenue {
query(
measures: ["orders.total_revenue"]
dimensions: ["orders.region"]
segments: ["orders.completed_orders"]
) {
data
}
}
Query Scoped to a Cube
Execute a query within a specific cube context.
query {
cube(name: "orders") {
query(
measures: ["total_revenue", "count"]
dimensions: ["region"]
limit: 10
) {
data
meta {
executionTimeMs
}
}
}
}
SQL Generation
Get Generated SQL
Retrieve the SQL that would be executed without running the query.
query {
sql(
measures: ["orders.total_revenue"]
dimensions: ["orders.region"]
filters: [
{ member: "orders.status", operator: EQUALS, values: ["completed"] }
]
)
}
Response:
{
"data": {
"sql": "SELECT\n UPPER(region) AS \"orders.region\",\n SUM(total_amount) AS \"orders.total_revenue\"\nFROM fct_orders\nWHERE status = 'completed'\nGROUP BY UPPER(region)"
}
}
Query Explanation
Explain a Query Plan
Get detailed information about how a query will be executed.
query {
explain(
measures: ["orders.total_revenue"]
dimensions: ["orders.region"]
) {
logicalPlan
physicalPlan
estimatedCost {
estimatedRows
estimatedBytesScanned
estimatedTimeMs
}
preAggregationMatch {
matched
preAggregationName
reason
suggestion
}
optimizationHints
}
}
Response:
{
"data": {
"explain": {
"logicalPlan": "1. Scan: fct_orders\n2. Filter: status = completed\n3. Aggregate: SUM(total_amount) GROUP BY region",
"physicalPlan": "SELECT UPPER(region), SUM(total_amount) FROM fct_orders GROUP BY UPPER(region)",
"estimatedCost": {
"estimatedRows": 50000,
"estimatedBytesScanned": 2500000,
"estimatedTimeMs": 150.0
},
"preAggregationMatch": {
"matched": true,
"preAggregationName": "orders_by_region_daily",
"reason": "Query matches pre-aggregation dimensions and measures",
"suggestion": null
},
"optimizationHints": []
}
}
}
Lineage Queries
Get Upstream Lineage
Trace data lineage upstream from a measure to its source columns.
query {
lineage(
cube: "orders"
member: "total_revenue"
direction: UPSTREAM
depth: 5
) {
nodes {
id
name
type
cube
sql
}
edges {
source
target
relationship
}
}
}
Response:
{
"data": {
"lineage": {
"nodes": [
{
"id": "orders.total_revenue",
"name": "total_revenue",
"type": "measure",
"cube": "orders",
"sql": "SUM(total_amount)"
},
{
"id": "fct_orders.total_amount",
"name": "total_amount",
"type": "column",
"cube": null,
"sql": null
},
{
"id": "stg_orders.amount",
"name": "amount",
"type": "column",
"cube": null,
"sql": null
}
],
"edges": [
{
"source": "orders.total_revenue",
"target": "fct_orders.total_amount",
"relationship": "aggregated"
},
{
"source": "fct_orders.total_amount",
"target": "stg_orders.amount",
"relationship": "direct"
}
]
}
}
}
Get Downstream Lineage
Find what depends on a specific column or measure.
query {
lineage(
cube: "orders"
member: "customer_id"
direction: DOWNSTREAM
depth: 3
) {
nodes {
id
name
type
}
edges {
source
target
relationship
}
}
}
Search
Search the Semantic Layer
Search across cubes, measures, and dimensions.
query {
search(query: "revenue", types: ["measure", "cube"], limit: 10) {
type
name
title
description
cube
relevanceScore
}
}
Response:
{
"data": {
"search": [
{
"type": "MEASURE",
"name": "total_revenue",
"title": "Total Revenue",
"description": "Sum of all order amounts",
"cube": "orders",
"relevanceScore": 0.95
},
{
"type": "MEASURE",
"name": "monthly_revenue",
"title": "Monthly Revenue",
"description": "Revenue aggregated by month",
"cube": "orders",
"relevanceScore": 0.85
}
]
}
}
Error Handling
GraphQL errors are returned in the standard errors array:
{
"data": null,
"errors": [
{
"message": "Measure 'invalid_measure' not found in cube 'orders'",
"locations": [{ "line": 2, "column": 3 }],
"path": ["query"],
"extensions": {
"code": "INVALID_MEASURE"
}
}
]
}