> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uselayers.com/llms.txt
> Use this file to discover all available pages before exploring further.

# LayersQL: query language for Layers analytics

> Overview of LayersQL, the domain-specific query language for Layers analytics, with syntax, datasets, and how to write queries for sort orders and metrics.

<Note>
  LayersQL is a derivative of ShopifyQL but is deliberately
  narrower in scope. It removes complexity in favor of a small, consistent
  set of clauses and functions that make metrics easy to define, reuse,
  and apply directly in merchandising workflows.
</Note>

## What you can do with LayersQL

Use LayersQL to create metrics and logic that can be reused in:

* **Merchandising rules** -- e.g., sort products by recent sales,
  views, or conversions.
* **Custom scoring** -- combine metrics into weighted scores to power
  advanced sort orders.
* **Performance tracking** -- define the same metrics you use in sort
  orders so they are visible in dashboards.
* **Segmentation** -- break down performance by geography, marketing
  channel, or other dimensions to support localized merchandising.
* **Time-series analysis** -- track metrics over time with automatic backfilling using the TIMESERIES clause.
* **Period comparison** -- compare a metric against the previous period, month, or year using COMPARE TO, and surface percent change with WITH PERCENT\_CHANGE.
* **Totals and running totals** -- add grand totals, group subtotals, or cumulative series with the WITH clause.
* **Data visualization** -- render query results as charts and graphs using the VISUALIZE clause.

## Basic query structure

LayersQL uses a predictable clause structure:

`FROM → SHOW → (GROUP BY / WHERE / SEGMENT BY) → (SINCE [UNTIL] | DURING) → [TIMESERIES] → [SEGMENT BY] → [COMPARE TO] → [WITH ...] → [VISUALIZE]`

* **FROM**: Selects the dataset to build metrics from (products, sales, search\_text, search\_image, search\_similar, collections, or blocks).
* **SHOW**: Defines which metrics or expressions to calculate, including arithmetic expressions (e.g., `SUM(total_sales) + SUM(quantity_purchased)`).
* **GROUP BY**: Groups results by dimensions or identifiers (e.g., `product_id`). Supports TOP N modifiers for limiting results.
* **WHERE** (optional): Filters rows before aggregation using boolean expressions (e.g., `geo_country = 'US' AND marketing_source IS NOT NULL`).
* **SINCE**: Sets the start of the time window for the metric.
* **UNTIL** (optional): Sets the end of the time window. When omitted, queries run up to the current time.
* **DURING** (alternative to SINCE/UNTIL): A single-token shortcut for common ranges such as `last_month`, `year_to_date`, `past_45_days`, or `bfcm2024`.
* **TIMESERIES** (optional): Groups results by time intervals (day, week, month, etc.) with automatic backfilling.
* **SEGMENT BY** (optional): Adds an additional dimension to further break down each group.
* **COMPARE TO** (optional): Repeats the query over a shifted time window (previous period, month, or year) so you can compare two periods.
* **WITH** (optional): Adds calculated rollups such as totals, group subtotals, percent change vs. the comparison window, or running totals.
* **VISUALIZE** (optional): Specifies how to render the results (table, bar, line, donut, etc.).

## Example

This query creates a metric for **7-day product sales segmented by
country**:

```sql theme={null}
FROM products
SHOW SUM(total_sales)
GROUP BY product_id
SINCE -7d
SEGMENT BY geo_country
```

The resulting metric can be:

* displayed directly in the merchandising dashboard, and
* referenced in sort orders to rank products by recent sales.

## Next steps

* Learn the full grammar in [**Syntax**](/platform/layersql/syntax).
* Explore [**Functions**](/platform/layersql/functions) to see available aggregations and
  expressions.
* Review [**Datasets**](/platform/layersql/datasets) to understand which metrics and dimensions you
  can query.