---
title: Syntax
description: >-
  How a ShopifyQL query is built, how result selection works, and where to find
  each clause.
api_version: 2026-07
source_url:
  html: 'https://shopify.dev/docs/api/shopifyql/latest/syntax'
  md: 'https://shopify.dev/docs/api/shopifyql/latest/syntax.md'
api_name: shopifyql
---

# Syntax

Syntax is the set of clauses and parameters you write. Every query needs [`FROM`](https://shopify.dev/docs/api/shopifyql/latest/syntax/from-and-show#from), which chooses a table. A query must also select results with [`SHOW`](https://shopify.dev/docs/api/shopifyql/latest/syntax/from-and-show#show) or [`VISUALIZE`](https://shopify.dev/docs/api/shopifyql/latest/syntax/visualize#visualize). Other clauses filter, group, and shape the result.

Use this reference to explore every clause and understand how to combine them into a query.

## ShopifyQL

```shopifyql
FROM sales
  SHOW gross_sales
  GROUP BY sales_channel WITH TOTALS
  DURING last_month
  ORDER BY gross_sales DESC
  LIMIT 10
VISUALIZE gross_sales TYPE horizontal_bar
```

***

## Anatomy of a query

A query combines a table, result selection, and optional clauses that shape the result. `FROM` with `SHOW` makes a complete tabular query. If you omit `SHOW`, then the query must include `VISUALIZE` to select the metric it renders.

ShopifyQL requires `FROM`, but doesn't require the main clauses to be written in a fixed order. Unlike in SQL, you set a date range with [`SINCE`, `UNTIL`, or `DURING`](https://shopify.dev/docs/api/shopifyql/latest/syntax/since-until-during) instead of [`WHERE`](https://shopify.dev/docs/api/shopifyql/latest/syntax/where).

## ShopifyQL

```shopifyql
FROM sales
  SHOW total_sales
```

### Table (`FROM`)

`FROM` picks the table you want to query, like [`sales`](https://shopify.dev/docs/api/shopifyql/latest/schemas/sales_revenue/sales) or [`customers`](https://shopify.dev/docs/api/shopifyql/latest/schemas/customers/customers). Each table's [schema](https://shopify.dev/docs/api/shopifyql/latest/schemas) lists the metrics and dimensions you can use, and querying a field outside that schema returns a parse error.

### Metrics (`SHOW`)

`SHOW` lists the metrics you want returned as table columns, like `total_sales` or `orders`. [`VISUALIZE`](https://shopify.dev/docs/api/shopifyql/latest/syntax/visualize#visualize) also names a metric, and renders it as a chart.

### Grouping, filters, and time

Group results by dimensions like `sales_channel`, `product_title`, or `month` with [`GROUP BY`](https://shopify.dev/docs/api/shopifyql/latest/syntax/group-by), bucket them over time with [`TIMESERIES`](https://shopify.dev/docs/api/shopifyql/latest/syntax/timeseries), or filter on them with `WHERE`. The dimensions you group by come back alongside your metrics.

Time clauses are optional, but pairing `TIMESERIES` with a date window (`SINCE`, `UNTIL`, or `DURING`) scopes the results to that window. For example, `TIMESERIES day SINCE -30d`.

![The ShopifyQL query FROM sales SHOW total\_sales TIMESERIES day SINCE -30d. FROM is required, SHOW or VISUALIZE selects a result, and optional clauses like TIMESERIES and SINCE shape the result.](https://shopify.dev/assets/assets/images/landing-pages/templated-apis/shopifyql-next/shopifyql-query-anatomy-DKoPST0g.png)

## A query with optional clauses

```shopifyql
FROM sales
  SHOW total_sales
  TIMESERIES day
  WITH TOTALS, PERCENT_CHANGE
  SINCE startOfDay(-30d) UNTIL today
  COMPARE TO previous_period
  ORDER BY day ASC
VISUALIZE total_sales TYPE line
```

***

## Clauses

Every query is a sequence of clauses. Square brackets mark optional parts, a slash or `|` separates alternatives, and `[, ...]` marks a part you can repeat.

Some syntax isn't tied to a single clause. Combine metrics from related tables in one query with a [multi-fact query](https://shopify.dev/docs/api/shopifyql/latest/syntax/from-and-show#multi-fact-queries), or add [comments](https://shopify.dev/docs/api/shopifyql/latest/syntax/comments) to document a longer query.

### Keyword reference

`FROM` is required. A query also needs result selection from `SHOW`, `VISUALIZE`, or both, and you add only the other optional clauses your query needs.

| Clause | Required? | What it does |
| - | - | - |
| [`FROM`](https://shopify.dev/docs/api/shopifyql/latest/syntax/from-and-show#from) | required | Chooses the table, which determines the available metrics and dimensions. |
| [`SHOW`](https://shopify.dev/docs/api/shopifyql/latest/syntax/from-and-show#show) | conditional | Lists the metrics and dimensions to return from the table. Required unless `VISUALIZE` selects a metric. Rename a field with [`AS`](https://shopify.dev/docs/api/shopifyql/latest/syntax/from-and-show#as). |
| [`WHERE`](https://shopify.dev/docs/api/shopifyql/latest/syntax/where) | optional | Filters rows before grouping. |
| [`GROUP BY`](https://shopify.dev/docs/api/shopifyql/latest/syntax/group-by) | optional | Groups results by one or more dimensions. |
| [`TIMESERIES`](https://shopify.dev/docs/api/shopifyql/latest/syntax/timeseries) | optional | Buckets results into a chartable time series. |
| [`WITH`](https://shopify.dev/docs/api/shopifyql/latest/syntax/with) | optional | Applies modifiers like totals, percent change, and attribution. |
| [`HAVING`](https://shopify.dev/docs/api/shopifyql/latest/syntax/having) | optional | Filters grouped results. |
| [`SINCE`, `UNTIL`, `DURING`](https://shopify.dev/docs/api/shopifyql/latest/syntax/since-until-during) | optional | Sets the reporting period. |
| [`COMPARE TO`](https://shopify.dev/docs/api/shopifyql/latest/syntax/compare-to) | optional | Compares the result against another period or target. |
| [`ORDER BY`](https://shopify.dev/docs/api/shopifyql/latest/syntax/order-by) | optional | Sorts results by one or more columns. |
| [`LIMIT`](https://shopify.dev/docs/api/shopifyql/latest/syntax/limit) | optional | Limits the number of rows returned. |
| [`VISUALIZE`](https://shopify.dev/docs/api/shopifyql/latest/syntax/visualize#visualize) | conditional | Renders results as a chart and sets the type. Required when `SHOW` is omitted. |
| [`ANNOTATE`](https://shopify.dev/docs/api/shopifyql/latest/syntax/annotate) | optional | Overlays contextual events on time-based charts. |

## Syntax

```shopifyql
FROM table[, ...]
  [SHOW metric / dimension / expression[, ...]]
  WHERE condition
  GROUP BY dimension[, ...]
  TIMESERIES time_dimension
  WITH modifier[, ...]
  HAVING condition
  SINCE date_parameter [UNTIL date_parameter] | UNTIL date_parameter | DURING named_date_range
  COMPARE TO comparison[, ...]
  ORDER BY column [ASC | DESC][, ...]
  LIMIT count [OFFSET count]
[VISUALIZE metric_or_alias [TYPE visualization_type][, ...] [MAX count] [ANNOTATE annotation]]
```

***

## Terminology

These terms are used throughout the ShopifyQL reference. Some keywords take metrics, some take dimensions, and some take either. If you're not sure whether a field is a metric or a dimension, check the [schema reference](https://shopify.dev/docs/api/shopifyql/latest/schemas) for the table you're querying. Each schema lists its metrics and dimensions separately.

| Term | Definition |
| - | - |
| Keyword | A reserved word that begins a clause, such as `FROM`, `SHOW`, or `GROUP BY`. |
| Clause | A keyword and the parameters that follow it, such as `SHOW total_sales`. A query is a sequence of clauses. |
| Parameter | A value you pass to a clause, such as a table, column, condition, or date range. |
| Operator | A reserved word or symbol used within a condition, such as `>=`, `STARTS WITH`, or `AND`. |
| Metric | A count or calculation that tracks a business indicator. Metrics are the columns you select with `SHOW`. |
| Dimension | An attribute you break metrics down by. Dimensions appear as columns, and their values define the rows. |

***