Skip to main content

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 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.

​
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: 
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.
  • Explore Functions to see available aggregations and expressions.
  • Review Datasets to understand which metrics and dimensions you can query.