---
title: Comments
description: >-
  Add comments to a ShopifyQL query to document it or stop part of it from
  running.
api_version: 2026-07
source_url:
  html: 'https://shopify.dev/docs/api/shopifyql/latest/syntax/comments'
  md: 'https://shopify.dev/docs/api/shopifyql/latest/syntax/comments.md'
api_name: shopifyql
---

# Comments

Comments are notes that you add to a ShopifyQL query. ShopifyQL ignores them when it runs the query, so they don't change the results. Use them to document what a query does or to stop part of it from running while you test.

## Syntax

```shopifyql
-- line comment


/* block comment */
```

Comments can explain sections of a query or prevent execution of query text.

* **line comment**

  **-- comment**

  Starts with `--` and ends at the end of the line.

* **block comment**

  **/\* comment \*/**

  Starts with `/*`, ends with `*/`, and can span multiple lines.

***

## Line comments

Use a line comment to leave a short note next to a clause, or to disable a single line while you test a query.

Examples

### Examples

* ####

  ##### Description

  Report \[\`gross\_profit\`]\(/docs/api/shopifyql/latest/schemas/sales\_revenue/sales#salesmetric-propertydetail-grossprofit) by day for the current month. This example uses a line comment (\`--\`) to record why the query keeps only sales with a recorded cost.

  ##### ShopifyQL

  ```shopifyql
  FROM sales
    SHOW net_sales_with_cost_recorded, cost_of_goods_sold, gross_profit
    WHERE cost_is_recorded = true -- Drop sales with no recorded cost so margin isn't overstated
    TIMESERIES day
    SINCE startOfMonth(0m) UNTIL today
  VISUALIZE gross_profit TYPE table
  ```

* ####

  ##### Description

  Show \[\`total\_sales\`]\(/docs/api/shopifyql/latest/schemas/sales\_revenue/sales#salesmetric-propertydetail-totalsales) and \`orders\` by day for the current month. This example comments out the \[\`WHERE\`]\(/docs/api/shopifyql/latest/syntax/where) line with \`--\` so the query runs across all customers. Delete the \`--\` to re-apply the new-customer filter.

  ##### ShopifyQL

  ```shopifyql
  FROM sales
    SHOW total_sales, orders
    -- WHERE new_or_returning_customer = 'New'
    TIMESERIES day
    SINCE startOfMonth(0m) UNTIL today
  VISUALIZE total_sales TYPE line
  ```

***

## Block comments

Use a block comment for a longer note, such as what a saved query is for or who maintains it, or to disable several lines at once. A block comment can sit anywhere in a query, not just at the top.

Examples

### Examples

* ####

  ##### Description

  Track new \[\`customers\`]\(/docs/api/shopifyql/latest/schemas/sales\_revenue/sales#salesmetric-propertydetail-customers), orders, and sales day by day over the last 30 days, against the previous 30-day period. This example uses a block comment at the top to record what the query powers and who owns it.

  ##### ShopifyQL

  ```shopifyql
  /*
    Powers the weekly growth review.
    Owned by the analytics team. Check before changing the date range.
  */
  FROM sales
    SHOW customers, orders, total_sales
    WHERE new_or_returning_customer = 'New'
    TIMESERIES day WITH TOTALS, PERCENT_CHANGE
    SINCE startOfDay(-30d) UNTIL today
    COMPARE TO previous_period
    ORDER BY day ASC
    LIMIT 1000
  VISUALIZE customers TYPE line
  ```

* ####

  ##### Description

  Report \[\`gross\_sales\`]\(/docs/api/shopifyql/latest/schemas/sales\_revenue/sales#salesmetric-propertydetail-grosssales), discounts, and net sales by month for the year to date. This example uses a block comment between clauses to disable a filter and explain why.

  ##### ShopifyQL

  ```shopifyql
  FROM sales
    SHOW gross_sales, discounts, net_sales
    /*
      Showing every customer for the summary view.
      Re-enable this filter for the new-customer report.
      WHERE new_or_returning_customer = 'New'
    */
    TIMESERIES month
    SINCE startOfYear(0y) UNTIL today
  VISUALIZE net_sales TYPE line
  ```

***