---
title: VISUALIZE
description: Render ShopifyQL query results graphically with the VISUALIZE clause.
api_version: 2026-07
source_url:
  html: 'https://shopify.dev/docs/api/shopifyql/latest/syntax/visualize'
  md: 'https://shopify.dev/docs/api/shopifyql/latest/syntax/visualize.md'
api_name: shopifyql
---

# VISUALIZE

`VISUALIZE` controls how a query's results are rendered. It sets the chart type and chooses which metric or metrics the ShopifyQL editor renders. When a query includes `SHOW`, `VISUALIZE` uses selected metrics, metric aliases, or generated metric columns. When a query omits `SHOW`, `VISUALIZE` is required and selects one or more metrics from the selected table or tables.

`VISUALIZE` only changes the chart shown in the [ShopifyQL editor](https://help.shopify.com/en/manual/reports-and-analytics/shopify-reports/report-types/shopifyql-editor). When you run a query programmatically, you always get table data: the [GraphQL Admin API](https://shopify.dev/docs/api/admin-graphql/latest/queries/shopifyqlQuery) returns the rows in its response, and the [Python SDK and CLI](https://shopify.dev/docs/apps/build/shopifyql/python-sdk-and-cli) return them as DataFrames, so your app renders the chart itself. ShopifyQL still validates both clauses, so an invalid `TYPE` or `ANNOTATE` returns `parseErrors` instead of `tableData`.

## Syntax

```shopifyql
VISUALIZE metric_or_alias [TYPE visualization_type] [, ...] [MAX number] [ANNOTATE annotation]
```

***

## VISUALIZE

Use `VISUALIZE` with one or more selected metrics, metric aliases, or generated metric columns. When the query doesn't include `SHOW`, use `VISUALIZE` with one or more metrics from the selected table or tables. Reference any renamed metric by its `AS` alias. Add `TYPE` to set the chart type, or omit it to let ShopifyQL choose one.

With multiple metrics, a `TYPE` applies to the metric it follows and any earlier metrics without their own `TYPE`. Use `MAX` to cap the number of data points rendered, and `ANNOTATE` to overlay contextual events on supported charts.

ShopifyQL supports a range of `TYPE` values, grouped into categories by what each does best, such as comparing values, tracking change over time, or breaking down parts of a whole. The following sections describe each category and its types, along with the supported modifiers.

The chart type doesn't change the rows a query returns. The same `VISUALIZE` query renders a chart in the ShopifyQL editor and returns table data through the GraphQL Admin API and the Python SDK and CLI.

#### ShopifyQL editor

## ShopifyQL

```shopifyql
FROM sales
  SHOW total_sales, orders
  TIMESERIES month
  SINCE -12m UNTIL today
VISUALIZE total_sales TYPE bar
```

![A bar chart visualizing sample ShopifyQL query results.](https://shopify.dev/assets/assets/images/shopifyql/examples/bar-Dl4FMJ_A.png)

#### GraphQL Admin API

## Request

```graphql
query RunShopifyQL {
  shopifyqlQuery(
    query: "FROM sales SHOW total_sales, orders TIMESERIES month SINCE -12m UNTIL today VISUALIZE total_sales TYPE bar"
  ) {
    tableData {
      columns {
        name
        dataType
        displayName
      }
      rows
    }
    parseErrors
  }
}
```

## Response

```json
{
  "data": {
    "shopifyqlQuery": {
      "tableData": {
        "columns": [
          {
            "name": "month",
            "dataType": "MONTH_TIMESTAMP",
            "displayName": "Month"
          },
          {
            "name": "total_sales",
            "dataType": "MONEY",
            "displayName": "Total sales"
          },
          {
            "name": "orders",
            "dataType": "INTEGER",
            "displayName": "Orders"
          }
        ],
        "rows": [
          {
            "month": "2026-01-01",
            "total_sales": "10000.00",
            "orders": 25
          }
        ]
      },
      "parseErrors": []
    }
  }
}
```

#### Python

## Request

```python
from shopifyql import ShopifyQLClient


client = ShopifyQLClient(shop="your-shop", access_token="shpat_...")
df = client.query_pandas(
    "FROM sales SHOW total_sales, orders TIMESERIES month SINCE -12m UNTIL today VISUALIZE total_sales TYPE bar"
)
print(df)
```

## Response

```text
month total_sales  orders
0  2026-01-01    10000.00      25
```

***

## Bar charts

Use bar charts to compare values across categories. Choose horizontal variants for long labels, grouped variants for side-by-side comparisons, and stacked variants for parts of a total.

##### `bar`

Compares a single metric across categories or time buckets using vertical bars. This is the default choice for straightforward "how much per category" comparisons.

This example compares `sessions` across device types for the last year, ranked from most to fewest.

##### `grouped_bar`

Places two or more series side by side within each category. Use it when every category carries several values you want to compare directly.

This example compares `total_sales` by day of week for the last year, with new and returning customers grouped side by side within each day.

##### `horizontal_bar`

Lays bars out horizontally, which keeps long category labels readable. Use it for rankings or for categories with descriptive names, such as product or city titles.

This example ranks `total_sales` by sales channel for the last year, with horizontal bars keeping the channel labels readable.

##### `horizontal_grouped_bar`

Combines a horizontal layout with grouped series, so several metrics share each row. Use it when categories have long labels and need a side-by-side comparison.

This example compares `total_sales` for new and returning customers within each sales channel for the last year, with horizontal bars keeping the channel labels readable.

##### `single_stacked_bar`

Shows one bar split into stacked segments, summarizing how a single total breaks down. Use it for a compact part-to-whole view, such as new and returning customers in a period.

This example breaks last year's `total_sales` into new and returning customers.

##### `stacked_bar`

Stacks series on top of each other within each bar, showing both the category total and its composition. Use it to track how parts contribute to a whole across time or categories.

This example breaks down each month's `total_sales` by new and returning customers for the last year, so you can see both the monthly total and how each segment contributes to it.

##### `stacked_horizontal_bar`

Stacks segments along horizontal bars, pairing part-to-whole composition with readable long labels. Use it when stacked categories have descriptive names.

This example breaks down `total_sales` by new and returning customers within each sales channel over the past 90 days, pairing the part-to-whole split with readable channel labels.

## Bar

```shopifyql
FROM sessions
  SHOW sessions
  GROUP BY session_device_type
  DURING last_year
  ORDER BY sessions DESC
  LIMIT 10
VISUALIZE sessions TYPE bar
```

![A bar chart visualizing sample ShopifyQL query results.](https://shopify.dev/assets/assets/images/shopifyql/examples/bar-Dl4FMJ_A.png)

## Grouped bar

```shopifyql
FROM sales
  SHOW total_sales
  GROUP BY day_of_week, new_or_returning_customer
  DURING last_year
  ORDER BY total_sales DESC
  LIMIT 25
VISUALIZE total_sales TYPE grouped_bar
```

![A grouped bar chart visualizing sample ShopifyQL query results.](https://shopify.dev/assets/assets/images/shopifyql/examples/grouped_bar-V369rpRF.png)

## Horizontal bar

```shopifyql
FROM sales
  SHOW total_sales
  GROUP BY sales_channel
  DURING last_year
  ORDER BY total_sales DESC
  LIMIT 25
VISUALIZE total_sales TYPE horizontal_bar
```

![A horizontal bar chart visualizing sample ShopifyQL query results.](https://shopify.dev/assets/assets/images/shopifyql/examples/horizontal_bar-tcSIEbML.png)

## Horizontal grouped bar

```shopifyql
FROM sales
  SHOW total_sales
  WHERE sales_channel IS NOT NULL AND new_or_returning_customer IS NOT NULL
  GROUP BY sales_channel, new_or_returning_customer WITH GROUP_TOTALS
  DURING last_year
  ORDER BY total_sales__sales_channel_totals DESC, sales_channel ASC,
    total_sales DESC
  LIMIT 25
VISUALIZE total_sales TYPE horizontal_grouped_bar
```

![A horizontal grouped bar chart visualizing sample ShopifyQL query results.](https://shopify.dev/assets/assets/images/shopifyql/examples/horizontal_grouped_bar--j5PFCPO.png)

## Single stacked bar

```shopifyql
FROM sales
  SHOW total_sales
  WHERE new_or_returning_customer IS NOT NULL
  GROUP BY new_or_returning_customer WITH TOTALS
  DURING last_year
  ORDER BY total_sales DESC
VISUALIZE total_sales TYPE single_stacked_bar
```

![A single stacked bar chart visualizing sample ShopifyQL query results.](https://shopify.dev/assets/assets/images/shopifyql/examples/single_stacked_bar-CVKTaX2J.png)

## Stacked bar

```shopifyql
FROM sales
  SHOW total_sales
  GROUP BY new_or_returning_customer WITH GROUP_TOTALS
  TIMESERIES month
  DURING last_year
  ORDER BY month ASC
  LIMIT 100
VISUALIZE total_sales TYPE stacked_bar
```

![A stacked bar chart visualizing sample ShopifyQL query results.](https://shopify.dev/assets/assets/images/shopifyql/examples/stacked_bar-DkF3aX_h.png)

## Stacked horizontal bar

```shopifyql
FROM sales
  SHOW total_sales, orders
  GROUP BY sales_channel, new_or_returning_customer WITH TOTALS, GROUP_TOTALS
  SINCE -90d UNTIL today
  ORDER BY total_sales DESC
  LIMIT 50
VISUALIZE total_sales TYPE stacked_horizontal_bar
```

![A stacked horizontal bar chart visualizing sample ShopifyQL query results.](https://shopify.dev/assets/assets/images/shopifyql/examples/stacked_horizontal_bar-CncsOLn1.png)

***

## Customer analysis charts

Use customer analysis charts to track how groups of customers behave over their lifecycle, from first purchase through retention and churn. Reach for them when you want to compare segments over time rather than raw totals.

##### `rfm_grid`

Arranges customer segments by recency, frequency, and monetary value. Use it to size and compare segments before targeting them.

This example sizes each RFM segment, like champions, at risk, and dormant, by how many customers fall into it.

## RFM grid

```shopifyql
FROM customers
  SHOW percent_of_customers, new_customer_records, days_since_last_order,
    total_number_of_orders, total_amount_spent
  WHERE rfm_group IN ('active', 'almost_lost', 'at_risk', 'champions', 'dormant',
    'loyal', 'needs_attention', 'new', 'previously_loyal', 'promising')
  GROUP BY rfm_group WITH TOTALS
  ORDER BY new_customer_records DESC
  LIMIT 1000
VISUALIZE new_customer_records TYPE rfm_grid
```

![An RFM grid chart visualizing sample ShopifyQL query results.](https://shopify.dev/assets/assets/images/shopifyql/examples/rfm_grid-Bbjsvn3Q.png)

***

## Distribution and relationship charts

Use distribution and relationship charts to show how values spread out and how metrics relate to one another. Reach for them to spot clusters, outliers, correlations, and the overall shape of your data.

##### `bubble_chart`

Positions points by two metrics and sizes each one by a third, packing three measures into a single view. Use it to compare entities across several dimensions at once.

This example plots each landing page type by its `sessions` and `pageviews`, with bubble size showing `online_store_visitors`.

##### `histogram`

Buckets values into ranges and shows how many records fall in each, revealing the shape of a distribution. Use it to understand frequency and spread, such as delivery times.

This example shows how `sessions` are distributed across session durations, counting how many sessions fall into each duration bucket.

##### `scatter_plot`

Plots one metric against another as points, exposing correlation, clusters, and outliers. Use it to explore the relationship between two measures.

This example plots each hour of the day by its `sessions` and `pageviews` for the last year.

## Bubble chart

```shopifyql
FROM sessions
  SHOW landing_page_type, sessions, pageviews, online_store_visitors
  WHERE landing_page_type IS NOT NULL
  GROUP BY landing_page_type
  DURING last_year
  ORDER BY sessions DESC
  LIMIT 20
VISUALIZE sessions, pageviews, online_store_visitors TYPE bubble_chart
```

![A bubble chart chart visualizing sample ShopifyQL query results.](https://shopify.dev/assets/assets/images/shopifyql/examples/bubble_chart-D1uAEA1t.png)

## Histogram

```shopifyql
FROM sessions
  SHOW sessions
  WHERE session_duration IS NOT NULL
  GROUP BY session_duration WITH TOTALS
  SINCE 2026-01-01 UNTIL 2026-02-01
  ORDER BY session_duration ASC
  LIMIT 100
VISUALIZE sessions TYPE histogram
```

![A histogram chart visualizing sample ShopifyQL query results.](https://shopify.dev/assets/assets/images/shopifyql/examples/histogram-QrZNkY3b.png)

## Scatter plot

```shopifyql
FROM sessions
  SHOW hour_of_day, sessions, pageviews
  GROUP BY hour_of_day
  DURING last_year
  ORDER BY sessions DESC
  LIMIT 50
VISUALIZE sessions, pageviews TYPE scatter_plot
```

![A scatter plot chart visualizing sample ShopifyQL query results.](https://shopify.dev/assets/assets/images/shopifyql/examples/scatter_plot-DBCiJKww.png)

***

## Funnel, flow, and change charts

Use funnel, flow, and change charts to follow how values move through stages or shift between periods. Reach for them to trace conversion drop-off, cumulative gains and losses, or how segments flow from one state to another.

##### `funnel`

Shows how a count narrows across sequential stages, making the drop-off between steps obvious. Use it for conversion paths, such as sessions through to completed checkouts.

This example follows store sessions from adding to cart, to reaching checkout, to completing it.

##### `waterfall`

Breaks a total into sequential positive and negative contributions, showing how you get from the starting value to the ending one. Use it to explain what drove a net change.

This example breaks `sessions` into contributions from the top five countries for the last year.

## Funnel

```shopifyql
FROM sessions
  SHOW sessions, sessions_that_reached_checkout,
    sessions_that_completed_checkout
  WITH TOTALS
  DURING last_year
  LIMIT 100
VISUALIZE sessions, sessions_that_reached_checkout,
  sessions_that_completed_checkout TYPE funnel
```

![A funnel chart visualizing sample ShopifyQL query results.](https://shopify.dev/assets/assets/images/shopifyql/examples/funnel-D0Fv-Ner.png)

## Waterfall

```shopifyql
FROM sessions
  SHOW sessions
  GROUP BY TOP 5 session_country WITH TOTALS
  DURING last_year
  ORDER BY sessions DESC
VISUALIZE sessions TYPE waterfall
```

![A waterfall chart visualizing sample ShopifyQL query results.](https://shopify.dev/assets/assets/images/shopifyql/examples/waterfall-BL2x0ZZC.png)

***

## Heatmap and calendar charts

Use heatmap and calendar charts to show intensity across a grid of two dimensions, with color standing in for magnitude. Reach for them to surface hot spots and recurring patterns, such as the busiest days, hours, or calendar dates.

##### `calendar_heatmap`

Shades calendar days by intensity. Use it to find recurring weekly or seasonal hotspots.

This example shades each day in the last year by `total_sales`.

##### `heatmap`

Shades a grid of two dimensions by value. Use it for patterns such as day of week against hour of day.

This example plots `sessions` across day of week and hour of day for the last year, revealing when shoppers visit most.

## Calendar heatmap

```shopifyql
FROM sales
  SHOW day, total_sales
  GROUP BY day
  DURING last_year
  ORDER BY day ASC
VISUALIZE total_sales TYPE calendar_heatmap
```

![A calendar heatmap chart visualizing sample ShopifyQL query results.](https://shopify.dev/assets/assets/images/shopifyql/examples/calendar_heatmap-BAaPfb_S.png)

## Heatmap

```shopifyql
FROM sessions
  SHOW sessions
  GROUP BY day_of_week, hour_of_day
  DURING last_year
  ORDER BY day_of_week ASC, hour_of_day ASC
VISUALIZE sessions TYPE heatmap
```

![A heatmap chart visualizing sample ShopifyQL query results.](https://shopify.dev/assets/assets/images/shopifyql/examples/heatmap-CND3xOE5.png)

***

## Line and area charts

Use line and area charts to show how metrics rise and fall over time. Reach for them to highlight trends, momentum, and cumulative growth across a continuous time axis.

##### `line`

Connects values over time, making trends, peaks, and dips easy to follow. This is the default choice for time-series metrics.

This example tracks weekly `online_store_visitors` over the last year, so you can follow the trend and spot peaks and dips at a glance.

##### `stacked_area`

Stacks filled series over time, showing both the running total and how each series contributes. Use it to track evolving composition across a period.

This example tracks monthly `total_sales` by sales channel over the last year, so you can see how each channel's contribution evolves over time.

## Line

```shopifyql
FROM sessions
  SHOW online_store_visitors
  TIMESERIES week WITH TOTALS
  DURING last_year
  ORDER BY week ASC
VISUALIZE online_store_visitors TYPE line
```

![A line chart visualizing sample ShopifyQL query results.](https://shopify.dev/assets/assets/images/shopifyql/examples/line-4gVot3ar.png)

## Stacked area

```shopifyql
FROM sales
  SHOW total_sales
  GROUP BY sales_channel WITH GROUP_TOTALS
  TIMESERIES month
  DURING last_year
  ORDER BY month ASC
VISUALIZE total_sales TYPE stacked_area
```

![A stacked area chart visualizing sample ShopifyQL query results.](https://shopify.dev/assets/assets/images/shopifyql/examples/stacked_area-B52SteCW.png)

***

## Part-to-whole and hierarchy charts

Use part-to-whole and hierarchy charts to show how segments contribute to a total and how categories nest within one another. Reach for them to compare proportions or explore data that breaks down into levels.

##### `donut`

Splits a total into proportional arcs around a ring, leaving the center open for a label or total. Use it for a quick part-to-whole read across a few categories.

This example breaks down last year's `total_sales` by sales channel.

##### `sunburst`

Renders a hierarchy as concentric rings radiating from a center, where each ring is one level deeper. Use it to explore nested categories and their contribution to the whole.

This example nests `sessions` by landing page type and then by referrer source for the last year, so you can explore where visitors come from within each entry point.

##### `treemap`

Tiles a rectangle into nested, area-sized boxes, packing many categories into a compact part-to-whole view. Use it to compare contribution across a large set of items.

This example sizes a tile for each country by its `sessions` for the last year, packing the top 20 into one part-to-whole view of where sessions come from.

## Donut

```shopifyql
FROM sales
  SHOW total_sales
  GROUP BY sales_channel WITH TOTALS
  DURING last_year
  ORDER BY total_sales DESC
  LIMIT 10
VISUALIZE total_sales TYPE donut
```

![A donut chart visualizing sample ShopifyQL query results.](https://shopify.dev/assets/assets/images/shopifyql/examples/donut-GNgoJCLe.png)

## Sunburst

```shopifyql
FROM sessions
  SHOW sessions
  WHERE landing_page_type IS NOT NULL AND referrer_source IS NOT NULL
    AND referrer_source != 'unknown'
  GROUP BY landing_page_type, referrer_source WITH GROUP_TOTALS, TOTALS
  DURING last_year
  ORDER BY sessions__landing_page_type_totals DESC, landing_page_type ASC,
    sessions DESC
  LIMIT 50
VISUALIZE sessions TYPE sunburst
```

![A sunburst chart visualizing sample ShopifyQL query results.](https://shopify.dev/assets/assets/images/shopifyql/examples/sunburst-EZAb5qdb.png)

## Treemap

```shopifyql
FROM sessions
  SHOW sessions
  GROUP BY session_country
  DURING last_year
  ORDER BY sessions DESC
  LIMIT 20
VISUALIZE sessions TYPE treemap
```

![A treemap chart visualizing sample ShopifyQL query results.](https://shopify.dev/assets/assets/images/shopifyql/examples/treemap-BTkNsHzG.png)

***

## Radial charts

Use radial charts to arrange values around a central point, mapping magnitude to angle or distance from the center. Reach for them to compare many categories at once or to emphasize cyclical, dial-like data.

##### `radar`

Plots several metrics on axes radiating from a center and connects them into a shape. Use it to contrast entities across multiple measures.

This example profiles each device type across `sessions` and `pageviews` for the last year, so you can compare their shapes at a glance.

## Radar

```shopifyql
FROM sessions
  SHOW sessions, pageviews
  GROUP BY session_device_type
  DURING last_year
  ORDER BY sessions DESC
  LIMIT 10
VISUALIZE sessions, pageviews TYPE radar
```

![A radar chart visualizing sample ShopifyQL query results.](https://shopify.dev/assets/assets/images/shopifyql/examples/radar-BkVMt8ZW.png)

***

## Single metric

Use a single metric when the result should read as one headline number rather than a chart. Use it on dashboards and scorecards where a KPI, such as total sales or conversion rate, needs to stand on its own.

##### `single_metric`

Displays one headline number, optionally with a comparison to a prior period, instead of a chart. Use it to spotlight a single KPI.

This example reports a single month's `total_sales` as one headline figure, with the change from the previous month.

## Single metric

```shopifyql
FROM sales
  SHOW total_sales
  WITH TOTALS
  SINCE 2026-01-01 UNTIL 2026-02-01
  COMPARE TO previous_period
VISUALIZE total_sales TYPE single_metric
```

![A single metric visualization of sample ShopifyQL query results.](https://shopify.dev/assets/assets/images/shopifyql/examples/single_metric-DMmloclx.png)

***

## Tables and lists

Use tables and lists when exact values and rows matter more than visual shape. Reach for them to show precise figures, rank items, or enumerate the dimension values behind a query.

##### `list`

Presents results as a simple ranked list of values, focused on the metric rather than on chart shape. Use it for compact rankings or feeds.

This example ranks each month of this year by `total_amount_spent`, so you can read total customer spend as a compact ranked list.

##### `list_with_dimension_values`

Lists results alongside their dimension values, keeping the breakdown labels next to each metric. Use it when those labels matter as much as the numbers.

This example lists `sessions` broken down by day of week for the last year, with each day's label beside its value.

##### `table`

Lays results out as rows and columns of exact values, supporting multiple metrics and dimensions. Use it when precise numbers matter more than visual shape.

This example lays out `sessions`, `pageviews`, and `online_store_visitors` for each country and device type over the last year, so you can read the exact figures.

## List

```shopifyql
FROM customers
  SHOW total_amount_spent
  GROUP BY month
  SINCE startOfYear(0y) UNTIL today
  ORDER BY total_amount_spent DESC
  LIMIT 100
VISUALIZE total_amount_spent TYPE list
```

![A list visualization of sample ShopifyQL query results.](https://shopify.dev/assets/assets/images/shopifyql/examples/list-C6Fvrb1Q.png)

## List with dimension values

```shopifyql
FROM sessions
  SHOW sessions
  GROUP BY day_of_week WITH TOTALS
  DURING last_year
  ORDER BY day_of_week ASC
VISUALIZE sessions TYPE list_with_dimension_values
```

![A list with dimension values visualization of sample ShopifyQL query results.](https://shopify.dev/assets/assets/images/shopifyql/examples/list_with_dimension_values-0qPh6STY.png)

## Table

```shopifyql
FROM sessions
  SHOW sessions, pageviews, online_store_visitors
  GROUP BY session_country, session_device_type WITH TOTALS
  DURING last_year
  ORDER BY sessions DESC
  LIMIT 10
VISUALIZE sessions TYPE table
```

![A table visualization of sample ShopifyQL query results.](https://shopify.dev/assets/assets/images/shopifyql/examples/table-DEkhRS-D.png)

***

## Bar and line charts

Use a bar and line chart to compare related metrics with different chart types in the same visualization. Set a `TYPE` on each metric to render the metrics with different chart types in one visualization.

This example plots monthly `gross_sales` as bars and `orders` as a line on the same time axis.

## Bar and line chart

```shopifyql
FROM sales
  SHOW gross_sales, orders
  TIMESERIES month WITH TOTALS
  DURING last_year
  ORDER BY month ASC
  LIMIT 100
VISUALIZE gross_sales TYPE bar, orders TYPE line
```

![A bar and line chart with vertical bars and an overlaid line visualizing sample ShopifyQL query results.](https://shopify.dev/assets/assets/images/shopifyql/examples/combo-DftwpX8-.png)

***

## Modifiers

Modifiers cap the number of data points rendered by `VISUALIZE`.

##### `MAX <number>`

Caps how many data points the chart renders. Pair it with `ORDER BY` to show only the top results, or use it to keep a long time series readable. `MAX` is the preferred modifier in new queries.

This example shows your top five device browsers by `sessions` for the last year. After `ORDER BY sessions DESC` ranks them, `MAX 5` keeps only the top five so the chart stays focused.

## MAX example

```shopifyql
FROM sessions
  SHOW sessions
  GROUP BY session_device_browser
  DURING last_year
  ORDER BY sessions DESC
VISUALIZE sessions TYPE horizontal_bar MAX 5
```

![A horizontal bar chart capped to the top five device browsers by sessions with MAX.](https://shopify.dev/assets/assets/images/shopifyql/examples/max-CXIdniun.png)

***

## ANNOTATE

Use [`ANNOTATE`](https://shopify.dev/docs/api/shopifyql/latest/syntax/annotate) to overlay contextual annotations on a time-based visualization.

***