--- title: TIMESERIES description: Return ShopifyQL results by one time dimension. api_version: 2026-07 source_url: html: 'https://shopify.dev/docs/api/shopifyql/latest/syntax/timeseries' md: 'https://shopify.dev/docs/api/shopifyql/latest/syntax/timeseries.md' api_name: shopifyql --- # TIMESERIES Use `TIMESERIES` to return results by one [time dimension](#time-dimensions) across a [date range](#default-date-ranges). Time dimensions include intervals, such as `day` and `month`, and date or clock values, such as `day_of_week` and `hour_of_day`. Use `TIMESERIES` when the result should show every value of the selected time dimension in the reporting period. Use [`SHOW`](https://shopify.dev/docs/api/shopifyql/latest/syntax/from-and-show#show) to choose [returned columns](#result-columns), [`GROUP BY`](https://shopify.dev/docs/api/shopifyql/latest/syntax/group-by) to add dimensions, and [`SINCE`, `UNTIL`, or `DURING`](https://shopify.dev/docs/api/shopifyql/latest/syntax/since-until-during) to set the reporting period. Use [`VISUALIZE`](https://shopify.dev/docs/api/shopifyql/latest/syntax/visualize#visualize) to add a chart that needs a time axis. **Note:** A time dimension in `GROUP BY` without `TIMESERIES` groups results by time, but returns only values that exist in the data for that time dimension. ## Syntax ```shopifyql TIMESERIES time_dimension ``` *** ## Time dimensions Choose one time dimension for `TIMESERIES`. Time dimensions include intervals, such as `day` and `month`, and date or clock values, such as `day_of_week` and `hour_of_day`. Use [`GROUP BY`](https://shopify.dev/docs/api/shopifyql/latest/syntax/group-by) with a time dimension when the result needs only values that exist in the data for that dimension. * **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 Chart daily \[\`total\_sales\`]\(/docs/api/shopifyql/latest/schemas/sales\_revenue/sales#salesmetric-propertydetail-totalsales) over the last 30 days. This example uses \[\`WITH TOTALS\`]\(/docs/api/shopifyql/latest/syntax/with#total-columns) to add the period total as a \`total\_sales\_\_totals\` column beside the daily rows. ##### ShopifyQL ```shopifyql FROM sales SHOW total_sales TIMESERIES day WITH TOTALS SINCE -30d UNTIL today ORDER BY day ASC ``` * #### ##### Description Chart weekly \[\`sessions\`]\(/docs/api/shopifyql/latest/schemas/sessions\_and\_behavior/sessions#sessionsmetric-propertydetail-sessions) and \`conversion\_rate\` for the current quarter. This example uses a weekly \`TIMESERIES\` interval with \[\`DURING this\_quarter\`]\(/docs/api/shopifyql/latest/syntax/since-until-during) to aggregate daily values into weekly points. ##### ShopifyQL ```shopifyql FROM sessions SHOW sessions, conversion_rate TIMESERIES week DURING this_quarter ORDER BY week ASC ``` *** ## Default date ranges When a query uses `TIMESERIES` without explicit date bounds, ShopifyQL applies a default reporting period based on the selected time dimension. If you omit `SINCE` and the query doesn't use `DURING`, then ShopifyQL applies the default start date for that time dimension. If you omit `UNTIL` and the query doesn't use `DURING`, then ShopifyQL uses `now` as the end date. To set the reporting period explicitly, use [`SINCE`, `UNTIL`, or `DURING`](https://shopify.dev/docs/api/shopifyql/latest/syntax/since-until-during). The following table lists the default range that each time dimension applies: | Time dimension | Default range | | - | - | | `second` | `SINCE startOfMinute(-1min) UNTIL now` | | `minute` | `SINCE startOfHour(-1h) UNTIL now` | | `hour` | `SINCE startOfHour(-24h) UNTIL now` | | `day` | `SINCE startOfDay(-30d) UNTIL now` | | `week` | `SINCE startOfWeek(-4w) UNTIL now` | | `month` | `SINCE startOfMonth(-3m) UNTIL now` | | `quarter` | `SINCE startOfQuarter(-4q) UNTIL now` | | `year` | `SINCE startOfYear(-3y) UNTIL now` | | `hour_of_day` | `SINCE startOfDay(-3d) UNTIL now` | | `day_of_week` | `SINCE startOfWeek(-4w) UNTIL now` | | `week_of_year` | `SINCE startOfYear(-1y) UNTIL now` | | `month_of_year` | `SINCE startOfYear(-1y) UNTIL now` | Examples ### Examples * #### ##### Description Chart daily \[\`sessions\`]\(/docs/api/shopifyql/latest/schemas/sessions\_and\_behavior/sessions#sessionsmetric-propertydetail-sessions) and \`conversion\_rate\` for last month. This example uses \[\`SINCE startOfMonth(-1m) UNTIL endOfMonth(-1m)\`]\(/docs/api/shopifyql/latest/syntax/since-until-during) to pin the range to the previous calendar month. ##### ShopifyQL ```shopifyql FROM sessions SHOW sessions, conversion_rate TIMESERIES day SINCE startOfMonth(-1m) UNTIL endOfMonth(-1m) ORDER BY day ASC ``` * #### ##### Description Show \[\`gross\_sales\`]\(/docs/api/shopifyql/latest/schemas/sales\_revenue/sales#salesmetric-propertydetail-grosssales), \`discounts\`, and \`net\_sales\` for a fixed one-month range as a single aggregated row. This example sets fixed \[\`SINCE\` and \`UNTIL\`]\(/docs/api/shopifyql/latest/syntax/since-until-during) dates with no \`TIMESERIES\`, so the metrics collapse into one total for the range rather than a daily series. ##### ShopifyQL ```shopifyql FROM sales SHOW gross_sales, discounts, net_sales SINCE 2026-01-01 UNTIL 2026-01-31 ``` *** ## Result columns `TIMESERIES` adds the selected time dimension to the returned columns. Where the time dimension appears depends on whether you also reference it in [`SHOW`](https://shopify.dev/docs/api/shopifyql/latest/syntax/from-and-show#show) or [`GROUP BY`](https://shopify.dev/docs/api/shopifyql/latest/syntax/group-by): * If the time dimension isn't in `GROUP BY` or `SHOW`, then it's the first dimension in the result. * If the time dimension is in `GROUP BY`, then its position follows the `GROUP BY` order. * If the time dimension is also in `SHOW`, then its position follows the `SHOW` order. Examples ### Examples * #### ##### Description List daily \[\`total\_sales\`]\(/docs/api/shopifyql/latest/schemas/sales\_revenue/sales#salesmetric-propertydetail-totalsales) over the last 30 days alongside the \`day\` column. \`TIMESERIES day\` already returns that date column, so naming it in \[\`SHOW\`]\(/docs/api/shopifyql/latest/syntax/from-and-show#show) sets where it appears in the column order rather than adding it. ##### ShopifyQL ```shopifyql FROM sales SHOW total_sales, day TIMESERIES day SINCE -30d UNTIL today ORDER BY day ASC ``` * #### ##### Description Break out daily \[\`total\_sales\`]\(/docs/api/shopifyql/latest/schemas/sales\_revenue/sales#salesmetric-propertydetail-totalsales) over the last 30 days, split by sales channel. This example pairs \`TIMESERIES day\` with \[\`GROUP BY\`]\(/docs/api/shopifyql/latest/syntax/group-by) \`sales\_channel\` to return a separate daily series for each channel. ##### ShopifyQL ```shopifyql FROM sales SHOW total_sales GROUP BY sales_channel, day TIMESERIES day SINCE -30d UNTIL today ORDER BY sales_channel ASC, day ASC ``` ***