--- title: GROUP BY description: Group aggregated ShopifyQL results by dimensions. api_version: 2026-07 source_url: html: 'https://shopify.dev/docs/api/shopifyql/latest/syntax/group-by' md: 'https://shopify.dev/docs/api/shopifyql/latest/syntax/group-by.md' api_name: shopifyql --- # GROUP BY Use `GROUP BY` to break aggregated results down by [dimensions](#dimensions). Grouped dimensions shape the rows returned by a query. Use [time dimensions](#time-dimensions) for time-based groups, or use [`TOP`](#top) to limit dimensions with many possible values. ## Syntax ```shopifyql GROUP BY item[, ...] item: dimension [ONLY] TOP count dimension [OVERALL] ``` *** ## Dimensions `GROUP BY` uses dimensions, which are fields defined by the selected table's [schema](https://shopify.dev/docs/api/shopifyql/latest/schemas). Available dimensions vary by table. Group by one dimension, or list multiple comma-separated dimensions in the order that ShopifyQL should apply the grouping. A dimension returned by [`SHOW`](https://shopify.dev/docs/api/shopifyql/latest/syntax/from-and-show#show) must appear in `GROUP BY`, unless it's a time dimension represented by [`TIMESERIES`](https://shopify.dev/docs/api/shopifyql/latest/syntax/timeseries). If you rename a `SHOW` dimension with `AS`, then use the name after `AS` in `GROUP BY`. For multiple-table queries, use dimensions that the selected schemas can group together in a [multi-fact query](https://shopify.dev/docs/api/shopifyql/latest/syntax/from-and-show#multi-fact-queries). Examples ### Examples * #### ##### Description Rank the top 10 payment methods by \[\`net\_payments\`]\(/docs/api/shopifyql/latest/schemas/finance\_and\_payments/payments#paymentsmetric-propertydetail-netpayments) over the last 30 days. This example uses \`GROUP BY payment\_method\` to collapse transactions into one row per method, which \[\`ORDER BY\`]\(/docs/api/shopifyql/latest/syntax/order-by) and \[\`LIMIT\`]\(/docs/api/shopifyql/latest/syntax/limit) then rank and trim. ##### ShopifyQL ```shopifyql FROM payments SHOW net_payments GROUP BY payment_method WITH TOTALS SINCE -30d UNTIL today ORDER BY net_payments DESC LIMIT 10 ``` * #### ##### Description Break down \[\`sessions\`]\(/docs/api/shopifyql/latest/schemas/sessions\_and\_behavior/sessions#sessionsmetric-propertydetail-sessions) by both day and device type for last month. This example lists two fields in \`GROUP BY\` to return a row for every combination. ##### ShopifyQL ```shopifyql FROM sessions SHOW sessions GROUP BY day, session_device_type WITH TOTALS DURING last_month ORDER BY day ASC, sessions DESC ``` *** ## Time dimensions Group aggregated results by time dimensions, including intervals such as `day` and `month`, and date or clock values such as `day_of_week` and `hour_of_day`. `GROUP BY` returns only values that exist in the data for a grouped time dimension. Use [`TIMESERIES`](https://shopify.dev/docs/api/shopifyql/latest/syntax/timeseries) when the result should include values for one time dimension even when those values have no data. * **second** **yyyy-MM-ddThh:mm:ss** Groups rows into one-second intervals. * **minute** **yyyy-MM-ddThh:mm** Groups rows into one-minute intervals. * **hour** **yyyy-MM-ddThh** Groups rows into one-hour intervals. * **day** **yyyy-MM-dd** Groups rows into calendar days. * **week** **yyyy-MM-dd** Groups rows into calendar weeks. * **month** **yyyy-MM-dd** Groups rows into calendar months. * **quarter** **yyyy-MM-dd** Groups rows into calendar quarters. * **year** **yyyy-MM-dd** Groups rows into calendar years. * **hour\_​of\_​day** **0-23** Groups rows by hour of the day, combining that hour across all dates. * **day\_​of\_​week** **0-6** Groups rows by day of the week, combining that weekday across all dates. * **week\_​of\_​year** **1-53** Groups rows by week of the year, combining that week across years. * **month\_​of\_​year** **1-12** Groups rows by month of the year, combining that month across years. Examples ### Examples * #### ##### Description Group \[\`total\_sales\`]\(/docs/api/shopifyql/latest/schemas/sales\_revenue/sales#salesmetric-propertydetail-totalsales) into one row per month for the year to date. This example uses \`GROUP BY month\` for plain monthly rows instead of the gap-filling series that \[\`TIMESERIES month\`]\(/docs/api/shopifyql/latest/syntax/timeseries) returns. ##### ShopifyQL ```shopifyql FROM sales SHOW total_sales GROUP BY month SINCE startOfYear(0y) UNTIL today ORDER BY month ASC ``` * #### ##### Description Total \[\`sessions\`]\(/docs/api/shopifyql/latest/schemas/sessions\_and\_behavior/sessions#sessionsmetric-propertydetail-sessions) for last month into one row per day of the week. This example uses \`GROUP BY day\_of\_week\` to collapse dates into one row per weekday that has data. ##### ShopifyQL ```shopifyql FROM sessions SHOW sessions GROUP BY day_of_week DURING last_month ORDER BY day_of_week ASC ``` *** ## TOP Use `TOP` to limit a high-cardinality dimension, such as `product_title` or `shipping_country`, to its most significant values. `TOP count` returns the `count` highest-ranked values, ranked by the metric the query aggregates. `count` must be a positive integer. By default, ShopifyQL collects the remaining values into a single `Other` row, so the results still add up to the query's total. Optional keywords change this behavior: * `ONLY`, placed before `TOP`, drops the `Other` row and returns only the top values. * `OVERALL`, placed after the dimension, ranks values across the entire result instead of within each preceding `GROUP BY` dimension. It has no effect on the first dimension. You can combine `TOP` with plain dimensions and use more than one `TOP` in a single `GROUP BY`. ## Syntax ```shopifyql GROUP BY [ONLY] TOP count dimension [OVERALL][, ...] ``` Examples ### Examples * #### ##### Description Show \[\`total\_sales\`]\(/docs/api/shopifyql/latest/schemas/sales\_revenue/sales#salesmetric-propertydetail-totalsales) for the 10 best-selling product titles last month. This example uses \`GROUP BY TOP 10\` to fold every other product into one remainder group. ##### ShopifyQL ```shopifyql FROM sales SHOW total_sales GROUP BY TOP 10 product_title DURING last_month ORDER BY total_sales DESC ``` * #### ##### Description Find the five months with the most \[\`new\_customer\_records\`]\(/docs/api/shopifyql/latest/schemas/customers/customers#customersmetric-propertydetail-newcustomerrecords) so far this year. This example uses plain \`TOP 5\` to bucket the rest into a remainder group, where \`ONLY TOP 5\` would drop them. ##### ShopifyQL ```shopifyql FROM customers SHOW new_customer_records GROUP BY TOP 5 month SINCE startOfYear(0y) UNTIL today ORDER BY new_customer_records DESC ``` ***