Dimensions define how you want to slice your measures. They are categorical or time-based attributes that group your data.
Note
Tip: For most reporting, use views like Sales which provide human-readable dimensions (e.g., Sales.location_name instead of Orders.location_id). The examples below use Orders.* to teach dimension concepts, but the same patterns apply to any view or cube.
{ "measures": ["Orders.net_sales"], "dimensions": ["Orders.location_id"] }
This returns net sales grouped by location.
{ "measures": ["Orders.net_sales"], "dimensions": [ "Orders.location_id", "Orders.sales_channel_id" ] }
This returns net sales grouped by location AND sales channel (creating a cross-tab).
Note
Dimensions use AND logic: Multiple dimensions create a cross-tabulation with one row per unique combination. For OR logic (e.g., "location A OR location B"), use filters with the equals operator and multiple values instead.
Warning
Avoid double counting with multi-cube joins. When querying across joined cubes (e.g., Orders and ItemTransactions), make a separate query for each level of aggregation. Summing measures from different cubes in a single query can cause double counting because of the join relationship (e.g., one order with 3 line items would count the order-level measure 3 times).
For example, to get both order-level net sales and item-level gross sales:
- Query 1 (order level):
measures: ["Orders.net_sales"] - Query 2 (item level):
measures: ["ItemTransactions.sales_gross_amount"]
Do not combine them in a single query with item-level dimensions, as this would inflate the order-level totals.
{ "measures": ["Orders.net_sales"], "dimensions": ["Orders.location_id"] }
{ "measures": ["Orders.net_sales"], "dimensions": ["Orders.sales_channel_id"] }
{ "measures": ["Orders.net_sales", "Orders.count"], "dimensions": ["Orders.customer_id"] }
{ "measures": ["Orders.net_sales"], "dimensions": [ "Orders.location_id", "Orders.sales_channel_id", "Orders.device_id" ] }
This returns net sales for every unique combination of location, sales channel, and device. For example: one row for "Location A, Online, iPad", another for "Location A, Online, Terminal", another for "Location A, In-Person, Terminal", and so on.
Warning
Performance Consideration: More dimensions = more result rows. A query with 3 dimensions might return thousands of rows. Use limit to control result size.
{ "measures": ["Orders.net_sales"], "dimensions": ["Orders.location_id"], "timeDimensions": [{ "dimension": "Orders.sale_timestamp", "dateRange": ["2024-01-01", "2024-01-31"], "granularity": "day" }] }
This returns daily sales by location (one row per day per location).