Overview - Stockful

A StockfulQL query is built from clauses. Every query needs two: FROM, which chooses the dataset, and SHOW, which lists the metrics to return. Every other clause is optional and shapes the result.

Anatomy of a query

The smallest useful query is a dataset and a metric:

FROM inventory
  SHOW inventory_value

From there you add clauses to filter, group, set a date range, sort and chart. They always appear in a fixed order, and the report editor writes them in that order for you, so you rarely type a whole query by hand:

FROM sales
  SHOW total_revenue AS "Revenue", units_sold
  WHERE vendor = 'Nike'
  GROUP BY ONLY TOP 5 product_type
  DURING last_month
  COMPARE TO previous_period
  HAVING total_revenue > 500
  ORDER BY total_revenue DESC
  LIMIT 10
  WITH TOTALS
  VISUALIZE total_revenue TYPE bar

Clauses

Clause	Required	What it does
FROM	Yes	Chooses the dataset (or combines two with `+`)
SHOW	Yes	Lists the metrics and computed columns to display
WHERE	Optional	Filters rows before they are grouped
GROUP BY	Optional	Groups rows by one or more dimensions
TIMESERIES	Optional	Buckets the results into day, week or month over time
DURING / SINCE / UNTIL	Optional	Sets the date range (defaults to all your history)
COMPARE TO	Optional	Compares the range against a prior period
HAVING	Optional	Filters groups by their aggregated metrics
ORDER BY	Optional	Sorts the results
LIMIT	Optional	Caps the number of rows returned
WITH	Optional	Adds result modifiers like totals or percent change
VISUALIZE	Optional	Chooses the chart type and the metric it plots
ANNOTATE	Optional	Overlays domain events on a timeseries chart

With no VISUALIZE line the query renders as a table, which is the default. Leaving out the date clause reads all of your history.