@graphenedata/cli 0.0.10 → 0.0.12

package/dist/docs/graphene.md

@@ -8,6 +8,7 @@ Graphene also has a CLI that lets you check syntax, run queries, serve data apps
 
 **Table of Contents**
 
+- [Graphene CLI](#graphene-cli)
 - [Graphene SQL (GSQL)](#graphene-sql-gsql)
   - [`table` statements](#table-statements)
     - [Base columns (required)](#base-columns-required)
@@ -18,14 +19,19 @@ Graphene also has a CLI that lets you check syntax, run queries, serve data apps
   - [`select` statements](#select-statements)
     - [Using join relationships in queries](#using-join-relationships-in-queries)
       - [Multi-hop joins](#multi-hop-joins)
-    - [Using stored expressions in queries](#using-stored-expressions-in-queries)
+    - [Using scalar stored expressions (dimensions) in queries](#using-scalar-stored-expressions-dimensions-in-queries)
+    - [Using aggregative stored expressions (measures) in queries](#using-aggregative-stored-expressions-measures-in-queries)
     - [Safe aggregation in fan-outs](#safe-aggregation-in-fan-outs)
+    - [Available functions](#available-functions)
+      - [Aggregate functions](#aggregate-functions)
+      - [Date and time functions](#date-and-time-functions)
+      - [Conditional Functions](#conditional-functions)
+      - [Math Functions](#math-functions)
+      - [Type Conversion](#type-conversion)
+    - [Subqueries, CTEs, and chaining queries](#subqueries-ctes-and-chaining-queries)
+    - [Other miscellaneous details](#other-miscellaneous-details)
   - [`table as` statements](#table-as-statements)
   - [`extend` statements](#extend-statements)
-  - [Working with dates, timestamps, and intervals](#working-with-dates-timestamps-and-intervals)
-    - [Date and timestamp literals](#date-and-timestamp-literals)
-    - [Interval literals](#interval-literals)
-  - [Other miscellaneous details about GSQL](#other-miscellaneous-details-about-gsql)
 - [Graphene data apps (dashboards)](#graphene-data-apps-dashboards)
   - [Visualization components](#visualization-components)
     - [Bar chart](#bar-chart)
@@ -68,8 +74,6 @@ Graphene also has a CLI that lets you check syntax, run queries, serve data apps
   - [Input components](#input-components)
     - [Text input](#text-input)
       - [All text input attributes](#all-text-input-attributes)
-    - [Date range](#date-range)
-      - [All date range attributes](#all-date-range-attributes)
     - [Dropdown](#dropdown)
       - [All dropdown attributes](#all-dropdown-attributes)
         - [DropdownOption](#dropdownoption)
@@ -81,16 +85,27 @@ Graphene also has a CLI that lets you check syntax, run queries, serve data apps
       - [Currencies](#currencies)
       - [Numbers](#numbers)
       - [Percentages](#percentages)
-- [Graphene CLI](#graphene-cli)
-- [AGENT INSTRUCTIONS](#agent-instructions)
 
-## Graphene SQL (GSQL)
+# Graphene CLI
+
+These are the available commands:
+- `npm run graphene check` - Checks the syntax (GSQL and Markdown) for the entire Graphene project.
+- `npm run graphene check [mdPath]` - Checks the syntax for a specified Graphene markdown file. Will also do a runtime check if the dev server is running, and if successful, take a full page screenshot to a temp directory for the agent to view.
+- `npm run graphene check [mdPath] -c [chartTitle]` - Same as above, except if the runtime check is successful, only takes a screenshot of the specified chart. `[chartTitle]` must match (case sensitive) the `title` attribute on the chart component.
+- `npm run graphene compile [GSQL | gsqlPath]` - Shows how GSQL is translated into the underlying database SQL.
+- `npm run graphene run [GSQL | gsqlPath]` - Runs a GSQL query. The tables and semantics defined in all .gsql files in the project are available for the query to use.
+
+# Graphene SQL (GSQL)
 
-GSQL is comprised of `table` statements that declare tables and `select` statements that query them.
+GSQL is comprised of four primary statements:
+1. `table` statements that declare existing tables and semantic metadata
+2. `select` statements that query tables
+3. `table as` statements that create new tables using `select`
+4. `extend` statements that attach semantic metadata to tables
 
-### `table` statements
+## `table` statements
 
-`table` statements manifest tables that already exist in your database. Here's an example of two tables, `orders` and `users`, in GSQL.
+`table` statements declare tables that already exist in your database. Here's an example of two tables, `orders` and `users`, in GSQL.
 
 ```sql
 table orders (
@@ -123,25 +138,25 @@ table users (
 
 We can break down a table statement into three parts: [base columns](#base-columns-required), [join relationships](#join-relationships), and [stored expressions](#stored-expressions) (aka dimensions and measures).
 
-#### Base columns (required)
+### Base columns (required)
 
 The base column set is simply a reflection of the underlying database table's schema. Similar to `create table` statements in regular SQL DDL, you list each column's name and data type. One column must be designated as the primary key.
 
-#### Join relationships
+### Join relationships
 
 Join relationships in a `table` statement declare joins that can be used when querying them. This makes query writing easier and more foolproof. See [Using join relationships in queries](#using-join-relationships-in-queries) below for how to use modeled joins in queries.
 
 The other main difference about joins in GSQL vs. regular SQL is that you have to explain if there are many rows in the left table for each row in the right table, or vice versa. This additional bit of information allows Graphene to prevent incorrect aggregation as a result of row duplication (aka fan-out) through joins. See [Safe aggregation in fan-outs](#safe-aggregation-in-fan-outs) for more details.
 
-This information is provided with the two supported join types, `join_one` and `join_many`:
-- `join_one` is used if there are many rows in the **left** table for each row in the **right** table.
-- `join_many` is used if there are many rows in the **right** table for each row in the **left** table.
+This information is provided with the two supported join types, `join one` and `join many`:
+- `join one` is used if there are many rows in the **left** table for each row in the **right** table.
+- `join many` is used if there are many rows in the **right** table for each row in the **left** table.
 
 In the example above with `orders` and `users`, the joins confirm that there are many orders per user, and only one user per order.
 
 Note that all joins in GSQL are left outer joins. There is no inner, right, or cross join.
 
-##### Multiple join relationships between the same two tables
+#### Multiple join relationships between the same two tables
 
 Sometimes there are multiple valid ways to join two tables together. You can model this in Graphene by aliasing the various joins with `as`, just as you would in normal SQL. For example:
 
@@ -164,12 +179,12 @@ table users (
 )
 ```
 
-##### Best practices for modeling join relationships
+#### Best practices for modeling join relationships
 
 - For a given `table` statement, only model joins that are directly on that table. Multi-hop join paths do not need to be written explicitly in order for queries to traverse them.
 - A join between two tables should be modeled in both the respective `table` statements. This may seem redundant but it offers more flexibility for queries to choose which table to set in the `from` (remember that direction matters in queries since all joins are left joins).
 
-#### Stored expressions
+### Stored expressions
 
 **Stored expressions** are GSQL expressions (ie. any arbitrary combination of functions, operators, and column references) that you want to make reusable to queries. Stored expressions are great for canonizing metrics, segments, and other important business definitions.
 
@@ -194,8 +209,7 @@ table orders (
 )
 ```
 
-
-### `select` statements
+## `select` statements
 
 `select` is how you write queries in Graphene SQL. It behaves similarly to regular SQL except in the following ways:
 - It can invoke join relationships and stored expressions from `table` statements.
@@ -203,7 +217,7 @@ table orders (
 
 These differences are described in the sections below.
 
-#### Using join relationships in queries
+### Using join relationships in queries
 
 If a `table` has join relationships declared in it, a `select` query on that table can leverage that join without needing to write its own join statement. This is helpful for query writers who have not memorized all the correct join keys.
 
@@ -237,7 +251,7 @@ order by 2 desc
 limit 10
 ```
 
-##### Multi-hop joins
+#### Multi-hop joins
 
 Sometimes you need to access columns or stored expressions in a table that is two or more joins away from the `from` table. To do this, simply use more dot operators to trace the desired join path. For example, say there is another table added to our project, `countries`:
 
@@ -278,7 +292,7 @@ order by 2 desc
 limit 10
 ```
 
-#### Using stored expressions in queries
+### Using scalar stored expressions (dimensions) in queries
 
 A stored expression can be invoked in a query by simply referencing it by name.
 
@@ -326,7 +340,9 @@ group by 1
 
 You can see that invoking a stored expression is like using a macro: the definition for the stored expression is effectively expanded in-line by Graphene when it runs the query.
 
-This is an important concept to understand when invoking stored expressions that are **aggregative** (ie. contain agg functions). Here's an example.
+### Using aggregative stored expressions (measures) in queries
+
+The macro concept is important to understand when invoking stored expressions that are **aggregative** (ie. contain agg functions), which can also be called "measures." Here's an example.
 
 ```sql
 -- Profit by month
@@ -349,41 +365,219 @@ group by 1
 order by 1 asc
 ```
 
-For this reason, in a query you would never wrap an aggregative stored expression in a `sum()` or `avg()` or any other agg function for the same reason you would never write `sum(sum(foo))` in SQL. That would throw an error!
+[CRITICAL!] This means:
+- You would NEVER wrap a measure in an agg function like `sum(my_measure)`, for the same reason that you cannot do `SUM(SUM(foo))` in regular SQL.
+- You would NEVER group by a measure like `group by my_measure`, for the same reason that you cannot do `GROUP BY SUM(foo)` in regular SQL.
+- You CAN wrap a measure in a scalar function like `floor(my_measure)`, for the same reason that can do `FLOOR(SUM(foo))` in regular SQL.
+- You CAN compose measures together in expressions like `my_measure + my_other_measure`, for the same reason that you can do `SUM(foo) + SUM(bar)` in regular SQL.
+
+Another way of thinking about this is that measures are "self-aggregating."
+
+### Safe aggregation in fan-outs
+
+Aggregations in GSQL are fan-out safe. In the event of a join, Graphene knows which values are duplicated ("fanned out") and will discard the duplicates when calculating aggregates.
+
+To do this, Graphene assumes that the column or expression you're aggregating is only dependent on one table. The grain of this table establishes the "correct" grain to compute the aggregate over. 
+
+>NOTE: Graphene does not support aggregating over expressions that depend on multiple tables (e.g. `sum(table1.col - table2.col)`). To work around this, you can consolidate the expression into a dimension e.g. `my_dim: col - table2.col` and then aggregate over that dimension.
+
+Here's an example of a fan-out:
+
+```sql
+table orders (
+  id BIGINT primary_key
+  customer_name VARCHAR
+  amt_with_shipping FLOAT
+
+  join many order_items on id = order_items.order_id
+)
+
+table order_items (
+  id BIGINT primary_key
+  order_id BIGINT
+  product VARCHAR
+  price FLOAT
+
+  join one orders on order_id = orders.id
+)
+```
+
+With the following data:
+
+**orders**
+
+| id | customer_name | amt_with_shipping |
+|----|---------------|-------------------|
+| 1  | Alice         | 110.00            |
+| 2  | Bob           | 85.00             |
+
+**order_items**
+
+| id | order_id | product | price |
+|----|----------|---------|-------|
+| 1  | 1        | Widget  | 60.00 |
+| 2  | 1        | Gadget  | 40.00 |
+| 3  | 2        | Widget  | 60.00 |
+| 4  | 2        | Thingamajig | 15.00 |
 
-#### Safe aggregation in fan-outs
+When joining orders to order_items, the result looks like:
 
-A common and dangerous user error in regular SQL is aggregating data incorrectly after joining tables. This can happen when rows of one table match multiple rows of another, and effectively get duplicated for each match.
+**orders joined to order_items**
+
+| orders.id | customer_name | amt_with_shipping | order_items.id | product | price |
+|-----------|---------------|-------------------|----------------|---------|-------|
+| 1         | Alice         | 110.00            | 1              | Widget  | 60.00 |
+| 1         | Alice         | 110.00            | 2              | Gadget  | 40.00 |
+| 2         | Bob           | 85.00             | 3              | Widget  | 60.00 |
+| 2         | Bob           | 85.00             | 4              | Thingamajig | 15.00 |
+
+Notice that both orders appear twice because they each contain two items. In regular SQL, if you naively computed `sum(amt_with_shipping)` over this joined result, you'd get 390.00 instead of the correct 195.00. In GSQL, because `amt_with_shipping` belongs to the `orders` table, Graphene knows to compute the sum at the `orders` grain, yielding 195.00.
+
+Here's how you can use this to simplify your queries. Say you want to see total order value and total item count by customer. In GSQL, you can write this directly:
+
+```sql
+select
+  customer_name,
+  sum(orders.amt_with_shipping) as total_spent,
+  count(order_items.id) as items_purchased
+from orders
+group by customer_name
+```
 
-For example, after joining `users` to `orders`, your joined result will have some users repeated multiple times if they've made multiple purchases. If you wanted to find the average age of customers over this joined result, simply using an `avg(users.age)` would be _incorrect_, because you would be weighting the average towards users with multiple purchases, rather than taking the true average.
+This returns:
 
-GSQL aims to solve this problem. With the additional information provided via `join_one` and `join_many`, Graphene knows under which scenarios when row dupliation occurs, and will rewrite aggregative expressions in a way that ignores the duplicate rows.
+| customer_name | total_spent | items_purchased |
+|---------------|-------------|-----------------|
+| Alice         | 110.00      | 2               |
+| Bob           | 85.00       | 2               |
 
-The query `select avg(users.age) from orders` will be rewritten to the following SQL when Graphene queries the underlying database (this is for BigQuery, specifically):
+In regular SQL, you'd need a subquery or CTE to avoid the fan-out problem:
 
 ```sql
+WITH order_totals AS (
+  SELECT customer_name, SUM(amt_with_shipping) as total_spent
+  FROM orders
+  GROUP BY customer_name
+),
+item_counts AS (
+  SELECT o.customer_name, COUNT(oi.id) as items_purchased
+  FROM orders o
+  JOIN order_items oi ON o.id = oi.order_id
+  GROUP BY o.customer_name
+)
 SELECT
-   (CAST((
-    (
-      SUM(DISTINCT
-        (CAST(ROUND(COALESCE(users_0.`age`,0)*(1*1.0), 9) AS NUMERIC) +
-        (cast(cast(concat('0x', substr(to_hex(md5(CAST(users_0.`id` AS STRING))), 1, 15)) as int64) as numeric) * 4294967296 + cast(cast(concat('0x', substr(to_hex(md5(CAST(users_0.`id` AS STRING))), 16, 8)) as int64) as numeric)) * 0.000000001
-      ))
-      -
-       SUM(DISTINCT (cast(cast(concat('0x', substr(to_hex(md5(CAST(users_0.`id` AS STRING))), 1, 15)) as int64) as numeric) * 4294967296 + cast(cast(concat('0x', substr(to_hex(md5(CAST(users_0.`id` AS STRING))), 16, 8)) as int64) as numeric)) * 0.000000001)
-    )/(1*1.0)) AS FLOAT64))/NULLIF(COUNT(DISTINCT CASE WHEN users_0.`age` IS NOT NULL THEN users_0.`id` END),0) as `col_0`
-FROM `bigquery-public-data.thelook_ecommerce.orders` as base
- LEFT JOIN `bigquery-public-data.thelook_ecommerce.users` AS users_0
-  ON users_0.`id`=base.`user_id`
+  ot.customer_name,
+  ot.total_spent,
+  ic.items_purchased
+FROM order_totals ot
+JOIN item_counts ic ON ot.customer_name = ic.customer_name
 ```
 
-You don't have to understand this; the point is that GSQL is minimizing the chances that naive users aggregate data incorrectly.
+### Available functions
+
+Function availability varies depending on the connected database, noted in the tables below. Check your package.json to see what database you are connected to.
+
+#### Aggregate functions
+
+| Function | Description | Parameters | Return Type | DuckDB | BigQuery | Snowflake |
+| - | - | - | - | - | - | - |
+| count(), count(*) | Counts the number of rows. | - | Number | x | x | x |
+| count(column) | Counts the number of non-null values in a column. | `column` - Any column/expression | Number | x | x | x |
+| count(distinct column) | Counts the number of distinct non-null values in a column. | `column` - Any column/expression | Number | x | x | x |
+| sum(column) | Calculates the sum of numeric values. | `column` - Numeric column/expression | Number | x | x | x |
+| avg(column) | Calculates the average (mean) of numeric values. | `column` - Numeric column/expression | Number | x | x | x |
+| min(column) | Returns the minimum value. | `column` - Any comparable column/expression | Same as input | x | x | x |
+| max(column) | Returns the maximum value. | `column` - Any comparable column/expression | Same as input | x | x | x |
+| string_agg(column) | Concatenates string values. | `column` - String column/expression | String | x | x | x |
+| stddev(column) | Calculates the standard deviation. | `column` - Numeric column/expression | Number | x | x | x |
+| pXX(column) | Returns the XXth percentile (e.g., p50, p975, p9999). | `column` - Numeric column/expression | Number | x | x (≤p99) | x |
+
+#### Date and time functions
+
+| Function | Description | Parameters | Return Type | DuckDB | BigQuery | Snowflake |
+| - | - | - | - | - | - | - |
+| current_date() | Returns the current date. | - | Date | x | x | x |
+| current_time() | Returns the current time. | - | Timestamp | x | x | x |
+| current_timestamp() | Returns the current timestamp. | - | Timestamp | x | x | x |
+| local_timestamp() | Returns the local timestamp. | - | Timestamp | x | x | x |
+| current_datetime() | Returns the current datetime (BigQuery only). | - | Timestamp | | x | |
+| date_trunc(unit, date) | Truncates date/timestamp to unit (DuckDB). | `unit` - Quoted date part ('year', 'quarter', 'month', 'week', 'day', 'hour', 'minute', 'second') ; `date` - Timestamp | Date or timestamp | x | | |
+| date_trunc(date, unit) | Truncates date/timestamp to unit (BigQuery). | `date` - Date or timestamp ; `unit` - Unquoted date part (year, quarter, month, week, day, hour, minute, second) | Date or timestamp | | x | |
+| extract(unit from timestamp) | Extracts a date part from timestamp. | `unit` - Date part (year, quarter, month, week, day, hour, minute, second, day_of_week, day_of_year) ; `timestamp` - Timestamp/date | Number | x | x | x |
+| timestamp_diff(start, end, unit) | Calculates difference between timestamps (BigQuery). | `start` - Timestamp ; `end` - Timestamp ; `unit` - Keyword (year, quarter, month, week, day, hour, minute, second) | Number | | x | |
+
+#### Conditional Functions
+
+| Function | Description | Parameters | Return Type | DuckDB | BigQuery | Snowflake |
+| - | - | - | - | - | - | - |
+| if(condition, trueValue, falseValue) | Returns one of two values based on condition. | `condition` - Boolean ; `trueValue` - Any type ; `falseValue` - Same type as trueValue | Same as value args | x | x | |
+| case when ... then ... else ... end | Evaluates conditions and returns values. | Multiple when/then clauses | Varies | x | x | x |
+| coalesce(value1, value2, ...) | Returns first non-null value. | `value1, value2, ...` - Same type | Same as input | x | x | x |
+
+#### Math Functions
+
+| Function | Description | Parameters | Return Type | DuckDB | BigQuery | Snowflake |
+| - | - | - | - | - | - | - |
+| floor(number) | Rounds down to nearest integer. | `number` - Numeric value | Number | x | x | x |
+| ceil(number) | Rounds up to nearest integer. | `number` - Numeric value | Number | x | x | x |
+| greatest(value1, value2, ...) | Returns the greatest value. | `value1, value2, ...` - Same type | Same as input | x | x | x |
+| least(value1, value2, ...) | Returns the smallest value. | `value1, value2, ...` - Same type | Same as input | x | x | x |
+| safe_divide(numerator, denominator) | Divides, returning null on division by zero (BigQuery). | `numerator` - Number ; `denominator` - Number | Number | | x | |
 
-#### Percentile shorthand
+#### Type Conversion
 
-Graphene provides percentile helpers so you rarely have to remember the SQL form for each warehouse. Anywhere you can call an aggregate, you can also write `pXX(column)` where `XX` is a whole number between 0 and 100. If you need precision finer than a whole percentile, append extra digits—everything after the first two digits is treated as decimals. Examples: `p975` → 97.5th percentile, `p9999` → 99.99th percentile. Graphene rewrites these shorthands to the dialect’s native function (`quantile_cont` on DuckDB, `approx_quantiles` on BigQuery, `PERCENTILE_CONT` on Snowflake) and ensures they behave like other aggregates (automatic grouping, structPath handling, etc.).
+| Function | Description | Parameters | Return Type | DuckDB | BigQuery | Snowflake |
+| - | - | - | - | - | - | - |
+| cast(value as type) | Converts value to specified type. | `value` - Any value ; `type` - Target type (int, int64, integer, bigint, smallint, tinyint, byteint, float, float64, double, decimal, numeric, bigdecimal, number, text, string, varchar, variant, bool, boolean, date, datetime, time, timestamp, timestamp_ntz, geography) | Specified type | x | x | x |
+| value::type | Alternative cast syntax. | `value` - Any value ; `type` - Target type | Specified type | x | x | x |
 
-### `table as` statements
+### Subqueries, CTEs, and chaining queries
+
+Queries can be chained together for more complex, multi-stage query logic. Instead of using subqueries or CTEs (`WITH`), in GSQL this is done by using the `table as` statement, or in Markdown, by simply chaining queries.
+
+Using `table as`:
+
+```sql
+table sales_per_store as (
+  select
+    store_id,
+    sum(amount) as total_sales
+  from orders
+  group by store_id
+)
+
+-- average store sales
+select avg(total_sales)
+from sales_per_store
+```
+
+In a Markdown file:
+
+````md
+```sql sales_per_store
+  select
+    store_id,
+    sum(amount) as total_sales
+  from orders
+  group by store_id
+```
+
+```sql average_store_sales
+select avg(total_sales)
+from sales_per_store
+```
+````
+
+### Other miscellaneous details
+
+- The clauses in a `select` statement (`select`, `from`, `join`, `group by`, etc.) can be written in any order. They cannot be repeated, however.
+- `group by all` is implied if aggregative and scalar expressions are both present in the `select` clause. This means that `group by` can be omitted and the query will still effectively execute the `group by all`.
+- Expressions in `group by` are implicitly selected, so `from orders select avg(amount) group by user_id` will return two columns.
+- `count` is a reserved word. Do not alias your columns as `count`.
+- Window functions and set operations (`union [all]`, `intersect`, `except`) are not supported.
+- Date and timestamp literals can be written with explicit keywords (`date '2024-01-01'` or `timestamp '2024-01-01 12:00:00'`), but these keywords are optional when the expected type is known from context (e.g., when comparing against a date or timestamp column). Interval literals always require the `interval` keyword.
+
+## `table as` statements
 
 You can turn the output of any `select` statement into a table with `table foo as (select ...)`. Here's an example of an additional table `user_facts` added to the two tables from earlier:
 
@@ -424,11 +618,11 @@ table user_facts as (
 )
 ```
 
-`table as` statements are conceptually the same as view tables in regular SQL. A few things to note:
-- You cannot yet declare join relationships or stored expressions directly in a `table as` statement. Other tables can declare join relationships to it, though, as shown above.
+`table as` statements are conceptually the same as view tables and CTEs in regular SQL. A few things to note:
+- You cannot declare join relationships or stored expressions directly in a `table as` statement. Use an `extend` statement.
 - In the example above, the `ltv` and `lifetime_orders` columns from `user_facts` are "hoisted" back into `users` so that they appear as if they are columns from `users`. This is simply a design choice which allows query writers to never need to know about `user_facts`.
 
-### `extend` statements
+## `extend` statements
 
 `extend` statements allow you to add join relationships or stored expressions to an existing table. This is especially useful for tables created via `table as` statements, which do not support defining these properties directly.
 
@@ -457,53 +651,7 @@ extend daily_orders (
 
 Note that you cannot add new base columns with `extend`; you can only add joins and stored expressions.
 
-### Working with dates, timestamps, and intervals
-
-Graphene understands a handful of common literal formats so you rarely need explicit casts when filtering or doing time math.
-
-**Date and timestamp literals**
-
-- `YYYY`, `YYYY-MM`, and `YYYY-MM-DD` strings are treated as dates. Leading/trailing spaces are ignored.
-- `YYYY-MM-DD HH[:MM[:SS]]` (with either a space or `T` between the date and time) is treated as a timestamp. Missing minutes or seconds default to `00`.
-
-```sql
-from users select id
-where created_at >= '2024-01-01' and created_at <= '2024-02-01'
-```
-
-**Interval literals**
-
-To add or subtract time, provide a quantity followed by a unit inside a string literal. Supported units include `second`, `minute`, `hour`, `day`, `week`, `month`, `quarter`, and `year` (plural forms or shorthands like `secs`, `mins`, `hrs` also work).
-
-```sql
-from users select
-  created_at + '5 minutes' as first_seen_plus_5,
-  created_at - '2 days' as first_seen_minus_2
-```
-
-Interval literals accept decimals (`'1.5 hours'`) and negative values (`'-7 days'`). Invalid strings produce a diagnostic such as “Could not parse interval literal: "many moons"”.
-
-### Other miscellaneous details about GSQL
-
-- Trailing commas in `table` statements are optional.
-- Trailing semicolons after `table` and `table as` statements are optional.
-- The clauses in a `select` statement (`select`, `from`, `join`, `group by`, etc.) can be written in any order. They cannot be repeated, however.
-- `group by all` is implied if aggregative and scalar expressions are both present in the `select` clause. This means that `group by` can be omitted and the query will still effectively execute the `group by all`.
-- Expressions in `group by` are implicitly selected, so `from orders select avg(amount) group by user_id` will return two columns.
-- `count` is a reserved word. Do not alias your columns as `count`.
-- Window functions and set operations are not supported.
-- Subqueries are not supported. However, you can accomplish the same functionality by chaining queries:
-  ````md
-   ```sql my_subquery
-   select ...
-   ```
-   
-   ```sql my_query
-   select ... from my_subquery
-   ```
-  ```` 
-
-## Graphene data apps (dashboards)
+# Graphene data apps (dashboards)
 
 Graphene data apps are written in Markdown with the addition of special Graphene HTML components. Markdown files can contain named GSQL queries in code fences that components can then refer to. Those queries can use any tables defined in .gsql files.
 
@@ -537,9 +685,9 @@ Best practices
 - If you have multiple time series charts, align their x-axes to have the same range and granularity.
 - Use the same color for a given metric if it is used in multiple charts.
 
-### Visualization components
+## Visualization components
 
-#### Bar chart
+### Bar chart
 
 Use bar or column charts to compare a metric across categories. Bar charts are best with a small number of categories and series, and should generally start at 0.
 
@@ -555,9 +703,9 @@ Here's an example:
 />
 ```
 
-##### All bar chart attributes
+#### All bar chart attributes
 
-###### General
+##### General
 
 | Attribute | Description | Options | Default |
 |----------|-------------|---------|---------|
@@ -569,11 +717,11 @@ Here's an example:
 | downloadableData | Whether to show the download button to allow users to download the data | `true`, `false` | `true` |
 | downloadableImage | Whether to show the button to allow users to save the chart as an image | `true`, `false` | `true` |
 
-###### Data
+##### Data
 
 | Attribute | Description | Required | Options | Default |
 |----------|-------------|----------|---------|---------|
-| data | Query name, wrapped in curly braces | true | query name | - |
+| data | GSQL query or table name | true | query name | - |
 | x | Column or expression to use for the x-axis of the chart | false | column name, stored expression name, GSQL expression | First column |
 | y | Column(s) or expression(s) to use for the y-axis of the chart. Each will create its own series. Consider a split axis with `y2` if there is a difference of scale or unit of measure between the series. | false | column name, stored expression name, GSQL expression, list of any combination of these e.g. `"col1, my_expr"` | Any non-assigned numeric columns |
 | y2 | Column(s) or expression(s) to include on a secondary y-axis. | false | column name, stored expression name, GSQL expression, list of any combination of these e.g. `"col1, my_expr"` | - |
@@ -585,7 +733,7 @@ Here's an example:
 | emptySet | Sets behaviour for empty datasets. Can throw an error, a warning, or allow empty. When set to 'error', empty datasets will block builds in `build:strict`. Note this only applies to initial page load - empty datasets caused by input component changes (dropdowns, etc.) are allowed. | false | `error`, `warn`, `pass` | `error` |
 | emptyMessage | Text to display when an empty dataset is received - only applies when `emptySet` is 'warn' or 'pass', or when the empty dataset is a result of an input component change (dropdowns, etc.). | false | string | No records |
 
-###### Formatting & Styling
+##### Formatting & Styling
 
 | Attribute | Description | Options | Default |
 |----------|-------------|---------|---------|
@@ -603,7 +751,7 @@ Here's an example:
 | rightPadding | Number representing the padding (whitespace) on the left side of the chart. Useful to avoid labels getting cut off | number | - |
 | xLabelWrap | Whether to wrap x-axis labels when there is not enough space. Default behaviour is to truncate the labels. | `true`, `false` | `false` |
 
-###### Value Labels
+##### Value Labels
 
 | Attribute | Description | Options | Default |
 |----------|-------------|---------|---------|
@@ -618,7 +766,7 @@ Here's an example:
 | y2LabelFmt | Format to use for value labels for series on the y2 axis. Overrides any other formats ([see available formats](#value-formatting)) | Excel-style format, built-in format name | - |
 | showAllLabels | Allow all labels to appear on chart, including overlapping labels | `true`, `false` | `false` |
 
-###### Axes
+##### Axes
 
 | Attribute | Description | Options | Default |
 |----------|-------------|---------|---------|
@@ -648,13 +796,13 @@ Here's an example:
 | y2Scale | Whether to scale the y-axis to fit your data. `y2Min` and `y2Max` take precedence over `y2Scale` | `true`, `false` | `false` |
 | yAxisColor | Turns on/off color on the y-axis (turned on by default when secondary y-axis is used). Can also be used to set a specific color | `true`, `false`, color string (CSS name, hexademical, RGB, HSL) | `true` when y2 used; `false` otherwise |
 
-###### Interactivity
+##### Interactivity
 
 | Attribute | Description | Options |
 |----------|-------------|---------|
 | connectGroup | Group name to connect this chart to other charts for synchronized tooltip hovering. Charts with the same `connectGroup` name will become connected | string |
 
-#### Pie chart
+### Pie chart
 
 Use a pie chart to show part-to-whole relationships across categories. Best for a small number of categories where proportions are easy to compare.
 
@@ -669,24 +817,24 @@ Here's an example:
 />
 ```
 
-##### All pie chart attributes
+#### All pie chart attributes
 
-###### General
+##### General
 
 | Attribute | Description | Options | Default |
 |----------|-------------|---------|---------|
 | title | Chart title. Appears at top left of chart. | string | - |
 | subtitle | Chart subtitle. Appears just under title. | string | - |
 
-###### Data
+##### Data
 
 | Attribute | Description | Required | Options | Default |
 |------|-------------|----------|---------|---------|
-| data | Query name, wrapped in curly braces | true | query name | - |
+| data | GSQL query or table name | true | query name | - |
 | category | Column or expression to use for slice names | true | column name, stored expression name, GSQL expression | - |
 | value | Column or expression to use for slice values | true | column name, stored expression name, GSQL expression | - |
 
-#### Line chart
+### Line chart
 
 Use line charts to display how one or more metrics vary over time. Line charts are suitable for plotting a large number of data points on the same chart.
 
@@ -703,9 +851,9 @@ Here's an example:
 />
 ```
 
-##### All line chart attributes
+#### All line chart attributes
 
-###### General
+##### General
 
 | Attribute | Description | Required | Options | Default |
 |------|-------------|----------|---------|---------|
@@ -717,11 +865,11 @@ Here's an example:
 | downloadableData | Whether to show the download button to allow users to download the data | false | `true`, `false` | `true` |
 | downloadableImage | Whether to show the button to allow users to save the chart as an image | false | `true`, `false` | `true` |
 
-###### Data
+##### Data
 
 | Attribute | Description | Required | Options | Default |
 |------|-------------|----------|---------|---------|
-| data | Query name, wrapped in curly braces | true | query name | - |
+| data | GSQL query or table name | true | query name | - |
 | x | Column or expression to use for the x-axis of the chart | true | column name, stored expression name, GSQL expression | - |
 | y | Column(s) or expression(s) to use for the y-axis of the chart. Each will create its own series. Consider a split axis with `y2` if there is a difference of scale or unit of measure between the series. | true | column name, stored expression name, GSQL expression, list of any combination of these e.g. `"col1, my_expr"` | - |
 | y2 | Column(s) or expression(s) to include on a secondary y-axis. | false | column name, stored expression name, GSQL expression, list of any combination of these e.g. `"col1, my_expr"` | - |
@@ -732,7 +880,7 @@ Here's an example:
 | emptySet | Sets behaviour for empty datasets. Can throw an error, a warning, or allow empty. When set to 'error', empty datasets will block builds in `build:strict`. Note this only applies to initial page load - empty datasets caused by input component changes (dropdowns, etc.) are allowed. | false | `error`, `warn`, `pass` | `error` |
 | emptyMessage | Text to display when an empty dataset is received - only applies when `emptySet` is 'warn' or 'pass', or when the empty dataset is a result of an input component change (dropdowns, etc.). | false | string | - |
 
-###### Formatting & Styling
+##### Formatting & Styling
 
 | Attribute | Description | Required | Options | Default |
 |------|-------------|----------|---------|---------|
@@ -763,7 +911,7 @@ Here's an example:
 | rightPadding | Number representing the padding (whitespace) on the left side of the chart. Useful to avoid labels getting cut off | false | number | - |
 | xLabelWrap | Whether to wrap x-axis labels when there is not enough space. Default behaviour is to truncate the labels. | false | `true`, `false` | `false` |
 
-###### Axes
+##### Axes
 
 | Attribute | Description | Required | Options | Default |
 |------|-------------|----------|---------|---------|
@@ -791,14 +939,14 @@ Here's an example:
 | y2Max | Maximum value for the y2-axis | false | number | - |
 | y2Scale | Whether to scale the y-axis to fit your data. `y2Min` and `y2Max` take precedence over `y2Scale` | false | `true`, `false` | `false` |
 
-###### Interactivity
+##### Interactivity
 
 | Attribute | Description | Required | Options | Default |
 |------|-------------|----------|---------|---------|
 | connectGroup | Group name to connect this chart to other charts for synchronized tooltip hovering. Charts with the same `connectGroup` name will become connected | false | - | - |
 
 
-#### Area chart
+### Area chart
 
 Use area charts to track how a metric with multiple series changes over time, or a continuous range. Area charts emphasize changes in the sum of series over the individual series.
 
@@ -812,9 +960,9 @@ Here's an example:
 />
 ```
 
-##### All area chart attributes
+#### All area chart attributes
 
-###### General
+##### General
 
 | Attribute | Description | Required | Options | Default |
 |------|-------------|----------|---------|---------|
@@ -826,11 +974,11 @@ Here's an example:
 | downloadableData | Whether to show the download button to allow users to download the data | false | `true`, `false` | `true` |
 | downloadableImage | Whether to show the button to allow users to save the chart as an image | false | `true`, `false` | `true` |
 
-###### Data
+##### Data
 
 | Attribute | Description | Required | Options | Default |
 |------|-------------|----------|---------|---------|
-| data | Query name, wrapped in curly braces | true | query name | - |
+| data | GSQL query or table name | true | query name | - |
 | x | Column or expression to use for the x-axis of the chart | true | column name, stored expression name, GSQL expression | First column |
 | y | Column(s) or expression(s) to use for the y-axis of the chart. Each will create its own series. Consider a split axis with `y2` if there is a difference of scale or unit of measure between the series. | true | column name, stored expression name, GSQL expression, list of any combination of these e.g. `"col1, my_expr"` | Any non-assigned numeric columns |
 | series | Column or expression to use to define the series (groups) in a multi-series chart. Use when values of a particular column dictate the multiple series to plot, eg. `country` would create a series for every distinct country in the column. | false | column name, stored expression name, GSQL expression | - |
@@ -840,7 +988,7 @@ Here's an example:
 | emptySet | Sets behaviour for empty datasets. Can throw an error, a warning, or allow empty. When set to 'error', empty datasets will block builds in `build:strict`. Note this only applies to initial page load - empty datasets caused by input component changes (dropdowns, etc.) are allowed. | false | `error`, `warn`, `pass` | `error` |
 | emptyMessage | Text to display when an empty dataset is received - only applies when `emptySet` is 'warn' or 'pass', or when the empty dataset is a result of an input component change (dropdowns, etc.). | false | string | "No records" |
 
-###### Formatting & Styling
+##### Formatting & Styling
 
 | Attribute | Description | Required | Options | Default |
 |------|-------------|----------|---------|---------|
@@ -859,7 +1007,7 @@ Here's an example:
 | rightPadding | Number representing the padding (whitespace) on the left side of the chart. Useful to avoid labels getting cut off | false | number | - |
 | xLabelWrap | Whether to wrap x-axis labels when there is not enough space. Default behaviour is to truncate the labels. | false | `true`, `false` | `false` |
 
-###### Value Labels
+##### Value Labels
 
 | Attribute | Description | Required | Options | Default |
 |------|-------------|----------|---------|---------|
@@ -870,7 +1018,7 @@ Here's an example:
 | labelFmt | Format to use for value labels ([see available formats](#value-formatting)) | false | Excel-style format, built-in format name | same as y column |
 | showAllLabels | Allow all labels to appear on chart, including overlapping labels | false | `true`, `false` | `false` |
 
-###### Axes
+##### Axes
 
 | Attribute | Description | Required | Options | Default |
 |------|-------------|----------|---------|---------|
@@ -890,14 +1038,14 @@ Here's an example:
 | yMax | Maximum value for the y-axis | false | number | - |
 | yScale | Whether to scale the y-axis to fit your data. `yMin` and `yMax` take precedence over `yScale` | false | `true`, `false` | `false` |
 
-###### Interactivity
+##### Interactivity
 
 | Attribute | Description | Required | Options | Default |
 |------|-------------|----------|---------|---------|
 | connectGroup | Group name to connect this chart to other charts for synchronized tooltip hovering. Charts with the same `connectGroup` name will become connected | false | - | - |
 
 
-#### Big value
+### Big value
 
 Use big values to display a large value standalone, and optionally include a comparison and a sparkline.
 
@@ -914,13 +1062,13 @@ Here's an example:
 />
 ```
 
-##### All big value attributes
+#### All big value attributes
 
-###### Data
+##### Data
 
 | Attribute | Description | Required | Options | Default |
 |------|-------------|----------|---------|---------|
-| data | Query name, wrapped in curly braces | true | query name | - |
+| data | GSQL query or table name | true | query name | - |
 | value | Column or expression to pull the main value from. | true | column name, stored expression name, GSQL expression | - |
 | title | Title of the card. | false | string | Title of the value column. |
 | minWidth | Overrides min-width of component | false | % or px value | `"18%"` |
@@ -930,7 +1078,7 @@ Here's an example:
 | emptyMessage | Text to display when an empty dataset is received - only applies when `emptySet` is 'warn' or 'pass', or when the empty dataset is a result of an input component change (dropdowns, etc.). | false | string | `"No records"` |
 | link | Used to navigate to other pages. Can be a full external link like `"https://google.com"` or an internal link like `"/sales/performance"` | false | - | - |
 
-###### Comparison
+##### Comparison
 
 | Attribute | Description | Required | Options | Default |
 |------|-------------|----------|---------|---------|
@@ -942,7 +1090,7 @@ Here's an example:
 | neutralMax | Sets the top of the range for 'neutral' values - neutral values appear in grey rather than red or green | false | number | `0` |
 | comparisonFmt | Sets format for the comparison ([see available formats](#value-formatting)) | false | Excel-style format, built-in format | - |
 
-###### Sparkline
+##### Sparkline
 
 | Attribute | Description | Required | Options | Default |
 |------|-------------|----------|---------|---------|
@@ -955,7 +1103,7 @@ Here's an example:
 | connectGroup | Group name to connect this sparkline to other charts for synchronized tooltip hovering. Charts with the same `connectGroup` name will become connected | false | string | - |
 | description | Adds an info icon with description tooltip on hover | false | string | - |
 
-#### Table
+### Table
 
 Use a Table component to display a richly formatted table of data from a query. Tables are powerful default choice for data display that allow high information density, and are easy to read.
 
@@ -965,13 +1113,13 @@ Here's an example:
 <Table data=orders_summary />
 ```
 
-##### All table attributes
+#### All table attributes
 
-###### Table
+##### Table
 
 | Attribute | Description | Required | Options | Default |
 |------|-------------|----------|---------|---------|
-| data | Query name, wrapped in curly braces | true | query name | - |
+| data | GSQL query or table name | true | query name | - |
 | rows | Number of rows to show in the table before paginating results. Use `"rows=all"` to show all rows in the table. | false | number, `all` | `10` |
 | title | Title for the table | false | string | - |
 | subtitle | Subtitle - appears under the title | false | string | - |
@@ -997,7 +1145,7 @@ Here's an example:
 | emptySet | Sets behaviour for empty datasets. Can throw an error, a warning, or allow empty. When set to 'error', empty datasets will block builds in `build:strict`. Note this only applies to initial page load - empty datasets caused by input component changes (dropdowns, etc.) are allowed. | false | `error`, `warn`, `pass` | `error` |
 | emptyMessage | Text to display when an empty dataset is received - only applies when `emptySet` is 'warn' or 'pass', or when the empty dataset is a result of an input component change (dropdowns, etc.). | false | string | "No records" |
 
-###### Groups
+##### Groups
 
 | Attribute | Description | Required | Options | Default |
 |------|-------------|----------|---------|---------|
@@ -1011,7 +1159,7 @@ Here's an example:
 | subtotalFontColor | [groupType=section] Font color for the subtotal row | false | Hex color code, css color name | - |
 | groupNamePosition | [groupType=section] Where the group label will appear in its cell | false | `top`, `middle`, `bottom` | `middle` |
 
-###### Column
+##### Column
 
 Use the Column sub-component to choose specific columns to display in your table, and to apply options to specific columns. If you don't supply any columns to the table, it will display all columns from your query result.
 
@@ -1102,11 +1250,11 @@ Conditional formatting (`contentType=colorscale`)
 | colorBreakpoints | List of numbers to use as breakpoints for each color in your color scale. Should line up with the colors you provide in `colorScale` | false | list of numbers | - |
 | scaleColumn | Column or expression to use to define the color scale range. Values in this column will have their cell color determined by the value in the scaleColumn | false | column name, stored expression name, GSQL expression | - |
 
-### Input components
+## Input components
 
-#### Text input
+### Text input
 
-Creates a text input that can be used to filter or search. To see how to filter a query using a text input, see Filters.
+Creates a text input that can be used to filter or search.
 
 Here's an example:
 
@@ -1125,7 +1273,7 @@ from users
 where email ilike concat('%', $name_of_input, '%')
 ```
 
-##### All text input attributes
+#### All text input attributes
 
 | Attribute | Description | Required | Options | Default |
 |------|-------------|----------|---------|---------|
@@ -1136,9 +1284,9 @@ where email ilike concat('%', $name_of_input, '%')
 | description | Adds an info icon with description tooltip on hover | false | string | - |
 
 
-#### Dropdown
+### Dropdown
 
-Creates a dropdown menu with a list of options that can be selected. The selected option can be used to filter queries or in markdown. To see how to filter a query using a dropdown, see Filters.
+Creates a dropdown menu with a list of options that can be selected. The selected option can be used to filter queries or in markdown.
 
 Here's an example:
 
@@ -1164,12 +1312,12 @@ from orders
 where status = $status_dropdown
 ```
 
-##### All dropdown attributes
+#### All dropdown attributes
 
 | Attribute | Description | Required | Options | Default |
 |------|-------------|----------|---------|---------|
 | name | Name of the dropdown, used to reference the selected value elsewhere as `"$name"` | true | - | - |
-| data | Query name, wrapped in curly braces | false | query name | - |
+| data | GSQL query or table name | false | query name | - |
 | value | Column name from the query containing values to pick from | false | column name | - |
 | multiple | Enables multi-select which returns a list | false | `true`, `false` | `false` |
 | defaultValue | Value to use when the dropdown is first loaded. Must be one of the options in the dropdown. Lists supported for multi-select. | false | value from dropdown, list of values e.g. `"Value 1, Value 2"` | - |
@@ -1183,7 +1331,7 @@ where status = $status_dropdown
 | hideDuringPrint | Hide the component when the report is printed | false | `true`, `false` | `true` |
 | description | Adds an info icon with description tooltip on hover | false | string | - |
 
-###### DropdownOption
+##### DropdownOption
 
 The `DropdownOption` sub-component can be used to manually add options to a dropdown. This is useful to add a default option, or to add options that are not in a query.
 
@@ -1202,11 +1350,11 @@ Here's an example:
 | value | Value to use when the option is selected | true | - | - |
 | valueLabel | Label to display for the option in the dropdown | false | - | Uses the value |
 
-### Other components
+## Other components
 
 `<Row></Row>` - Evenly distributes components inside along the same row.
 
-### Value formatting
+## Value formatting
 
 The easiest way to format numbers and dates in Graphene is through component attributes. You can pass in either of the following:
 
@@ -1241,11 +1389,11 @@ In the example above, `xFmt` is passing in an Excel-style code to format the dat
 
 Formatting does not apply to the date axis of a chart. For example, if you set `xFmt` to `"m/d/yy"`, you will only see that formatting reflected in your chart tooltips and annotations. This is to ensure that the chart axis labels have the correct spacing.
 
-#### Built-in Formats
+### Built-in Formats
 
 Graphene supports a variety of date/time, number, percentage, and currency formats.
 
-##### Auto-Formatting
+#### Auto-Formatting
 
 Wherever you see `auto` listed beside a format, that means Graphene will automatically format your value based on the context it is in.
 
@@ -1253,7 +1401,7 @@ For example, Graphene automatically formats large numbers into shortened version
 
 You can choose to handle these numbers differently by choosing a specific format code. For example, if Graphene is formatting a column as millions, but you want to see all numbers in thousands, you could use the `num0k` format, which will show all numbers in the column in thousands with 0 decimal places.
 
-##### Dates
+#### Dates
 
 Graphene supports the following date formats:
 
@@ -1269,7 +1417,7 @@ Graphene supports the following date formats:
 * `dmy` - Day/month/year (e.g., 9/1/22)
 * `hms` - Time format (e.g., 11:45:03 AM)
 
-##### Currencies
+#### Currencies
 
 Supported currencies include USD, AUD, BRL, CAD, CNY, EUR, GBP, JPY, INR, KRW, NGN, RUB, and SEK.
 
@@ -1288,7 +1436,7 @@ For example, the available tags for USD are:
 
 Similar patterns apply to other supported currencies.
 
-##### Numbers
+#### Numbers
 
 The default number format (when no `fmt` is specified) automatically handles decimal places and summary units (in the same way that `usd` does for currency).
 
@@ -1303,7 +1451,7 @@ Available number formats:
 * `mult`, `mult0`, `mult1`, `mult2` - Multiplier format (e.g., 5.32x)
 * `sci` - Scientific notation
 
-##### Percentages
+#### Percentages
 
 Available percentage formats:
 
@@ -1312,25 +1460,3 @@ Available percentage formats:
 * `pct1` - Percentage with 1 decimal place (e.g., 73.1%)
 * `pct2` - Percentage with 2 decimal places (e.g., 73.10%)
 * `pct3` - Percentage with 3 decimal places (e.g., 73.100%)
-
-## Graphene CLI
-
-These are the available commands:
-- `npm run graphene check` - Checks the syntax (GSQL and Markdown) for the entire Graphene project.
-- `npm run graphene check <mdPath>` - Checks the syntax for a specified Graphene markdown file. Will also do a runtime check if the dev server is running, and if successful, take a full page screenshot to a temp directory for the agent to view.
-- `npm run graphene check <mdPath> --chart "<chartTitle>"` - Same as above, except if the runtime check is successful, only takes a screenshot of the specified chart. `<chartTitle>` must match (case sensitive) the `title` attribute on the chart component. `-c` can be used as shorthand for `--chart`.
-- `npm run graphene compile "<GSQL>"` - Shows how GSQL is translated into the underlying database SQL.
-- `npm run graphene run "<GSQL>"` - Runs a GSQL query. The tables and semantics defined in all .gsql files in the project are available for the query to use.
-
-# AGENT INSTRUCTIONS
-
-Follow these guidelines when working in a Graphene project.
-- When formulating GSQL queries:
-   - First check all available stored expressions to see if there are any you can use. DO NOT redefine important business definitions like `profit` if they've already been modeled!
-   - Run your GSQL queries in the CLI first, _before_ you write them to a file. This way you can reason about the results to make sure they make sense.
-- Do not try to search the web for Graphene-specific info; you will not find anything. All the documentation is here in graphene.md.
-- When writing to a .gsql file, check your code with `npm run graphene check`.
-- When writing to a Graphene .md file:
-   - Always check your code with `npm run graphene check <mdPath>`. Run the command with full permissions because the screenshot may not work in a sandbox.
-   - Then do a visual check by either a) looking at the screenshot that `npm run graphene check <mdPath>` creates, or b) using your browser tool to open the .md file at `localhost:<port>/mdPath` (without the .md extension; default port 4000).
-      - Critique what you see: Are all the data values formatted in a way that is easy to read? Does the shape of the visualized data require an adjustment to scale, axis min/max, etc.? Are any visualizations missing data altogether? Is that visualization type really the best way to paint the picture? Etc.