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

# StockfulQL

> The query language behind every Stockful report, chart and scheduled export

StockfulQL is a query language for your store's inventory. You write a query to ask a question, like "what is my stock worth" or "which products sell fastest," and get back a table you can optionally turn into a chart.

It reads like SQL and runs against your live inventory, sales, purchasing and returns data. You rarely write it by hand (the report editor builds it for you), but it is always there to read, edit and share.

## Getting started

Start with a question about your store and write it as a query. Each example below adds one clause to the one before it, building from a simple total to a full chart.

<AccordionGroup>
  <Accordion title="What is my stock worth?">
    `FROM` picks the **inventory** dataset and `SHOW` picks the **inventory\_value** metric. With no grouping, the result is a single total.

    ```sql theme={null}
    FROM inventory
      SHOW inventory_value
    ```
  </Accordion>

  <Accordion title="Which vendors hold the most value?">
    Add `GROUP BY vendor` to break the total down into one row per vendor.

    ```sql theme={null}
    FROM inventory
      SHOW inventory_value
      GROUP BY vendor
    ```
  </Accordion>

  <Accordion title="What sold best last month?">
    Switch to the **sales** dataset, show revenue and units, group by product, and set the window with `DURING`. `ORDER BY` and `LIMIT` keep the top rows.

    ```sql theme={null}
    FROM sales
      SHOW total_revenue, units_sold
      GROUP BY product
      DURING last_month
      ORDER BY total_revenue DESC
      LIMIT 10
    ```
  </Accordion>

  <Accordion title="How does that compare to the month before?">
    `COMPARE TO previous_period` runs the query again over the prior window and adds the change to each row.

    ```sql theme={null}
    FROM sales
      SHOW total_revenue
      GROUP BY product
      DURING last_month
      COMPARE TO previous_period
      ORDER BY total_revenue DESC
      LIMIT 10
    ```
  </Accordion>

  <Accordion title="Show it as a chart">
    `VISUALIZE` turns the table into a chart. Here the top sellers become a bar chart, each bar carrying its change against the month before.

    ```sql theme={null}
    FROM sales
      SHOW total_revenue
      GROUP BY product
      DURING last_month
      COMPARE TO previous_period
      ORDER BY total_revenue DESC
      LIMIT 10
      VISUALIZE total_revenue TYPE bar
    ```
  </Accordion>
</AccordionGroup>

See [Syntax](/stockfulql/syntax/overview) for every clause, and [Examples](/stockfulql/examples) for more complete queries.

## Running StockfulQL

You write a query once and meet the same query in a few places. The query is identical everywhere; only what surrounds it changes.

| If you want to                            | Use                                                                                                    |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| Build or tweak a report with a live query | The **query editor** on any report page, with autocomplete, highlighting and inline validation         |
| Share an exact report by link             | The report's **`?ql=` URL**, which carries the whole query                                             |
| Reuse a report, or put it on a schedule   | A **saved report** built from a query                                                                  |
| Get a report without writing the query    | Ask the **AI assistant** in plain language and it writes the StockfulQL for you, then opens or runs it |

## Parts of a query

* **[Syntax](/stockfulql/syntax/overview)** is the clause set: `FROM` and `SHOW`, `WHERE`, `GROUP BY`, date ranges, comparison, `TIMESERIES`, sorting, limits and charts.
* **[Datasets](/stockfulql/datasets/overview)** are the data you can query, grouped by area. Each dataset's page lists the metrics, dimensions and filters it exposes.

A query always names one dataset and shows at least one metric. Everything else is optional.