@graphenedata/cli 0.0.5 → 0.0.7

package/dist/docs/graphene.md

@@ -21,6 +21,10 @@ Graphene also has a CLI that lets you check syntax, run queries, serve data apps
     - [Using stored expressions in queries](#using-stored-expressions-in-queries)
     - [Safe aggregation in fan-outs](#safe-aggregation-in-fan-outs)
   - [`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)
@@ -90,40 +94,30 @@ GSQL is comprised of `table` statements that declare tables and `select` stateme
 
 ```sql
 table orders (
-
-  /* Base columns */
-
-  id BIGINT primary_key,
-  user_id BIGINT,
-  created_at DATETIME,
-  status STRING, -- One of 'Processing', 'Shipped', 'Complete', 'Cancelled', 'Returned'
-  amount FLOAT, -- Amount paid by customer
-  cost FLOAT, -- Cost of materials
-
-  /* Join relationships */
-
-  join_one users on user_id = users.id,
-
-  /* Scalar expressions */
-
-  status in ('Processing', 'Shipped', 'Complete') as revenue_recognized,
-
-  /* Agg expressions */
-
-  sum(case when revenue_recognized then amount else 0 end) as revenue,
-  sum(case when revenue_recognized then cost else 0 end) as cogs,
-  revenue - cogs as profit,
-  profit / revenue as profit_margin
+  id BIGINT primary_key
+  user_id BIGINT
+  created_at DATETIME
+  status STRING -- One of 'Processing', 'Shipped', 'Complete', 'Cancelled', 'Returned'
+  amount FLOAT -- Amount paid by customer
+  cost FLOAT -- Cost of materials
+
+  join one users on user_id = users.id
+
+  revenue_recognized: status in ('Processing', 'Shipped', 'Complete')
+  revenue: sum(case when revenue_recognized then amount else 0 end)
+  cogs: sum(case when revenue_recognized then cost else 0 end)
+  profit: revenue - cogs
+  profit_margin: profit / revenue
 )
 
 table users (
-  id BIGINT primary_key,
-  name VARCHAR,
-  email VARCHAR,
-  age INTEGER,
-  country_code VARCHAR,
+  id BIGINT primary_key
+  name VARCHAR
+  email VARCHAR
+  age INTEGER
+  country_code VARCHAR
 
-  join_many orders on id = orders.user_id
+  join many orders on id = orders.user_id
 )
 ```
 
@@ -154,19 +148,19 @@ Sometimes there are multiple valid ways to join two tables together. You can mod
 ```sql
 table projects (
   ...
-  owner_id BIGINT,
-  viewer_id BIGINT,
+  owner_id BIGINT
+  viewer_id BIGINT
 
-  join_one users as project_owner on owner_id = project_owner.id,
-  join_one users as project_viewer on viewer_id = project_viewer.id
+  join one users as project_owner on owner_id = project_owner.id
+  join one users as project_viewer on viewer_id = project_viewer.id
 )
 
 table users (
   ...
-  id BIGINT,
+  id BIGINT
 
-  join_many projects as projects_as_owner on id = projects_as_owner.owner_id,
-  join_many projects as projects_as_viewer on id = projects_as_viewer.viewer_id
+  join many projects as projects_as_owner on id = projects_as_owner.owner_id
+  join many projects as projects_as_viewer on id = projects_as_viewer.viewer_id
 )
 ```
 
@@ -179,7 +173,7 @@ table users (
 
 **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.
 
-A stored expression must be given a name via `as`. It can then be referenced by name in queries that use the parent table. See [Using stored expressions in queries](#using-stored-expressions-in-queries) below for how to use stored expressions in queries.
+A stored expression must be given a name via `name: expression`. It can then be referenced by name in queries that use the parent table. See [Using stored expressions in queries](#using-stored-expressions-in-queries) below for how to use stored expressions in queries.
 
 Like expressions in regular SQL, expressions in GSQL are either scalar or aggregative. In BI parlance, these would be called dimensions and measures, respectively.
 
@@ -190,15 +184,13 @@ table orders (
   ...
 
   /* Scalar expressions */
-
-  status in ('Processing', 'Shipped', 'Complete') as revenue_recognized,
+  revenue_recognized: status in ('Processing', 'Shipped', 'Complete')
 
   /* Agg expressions */
-
-  sum(case when revenue_recognized then amount else 0 end) as revenue,
-  sum(case when revenue_recognized then cost else 0 end) as cogs,
-  revenue - cogs as profit, -- even though there are no agg functions here, this is still aggregative as it references other aggregative expressions
-  profit / revenue as profit_margin
+  revenue: sum(case when revenue_recognized then amount else 0 end)
+  cogs: sum(case when revenue_recognized then cost else 0 end)
+  profit: revenue - cogs -- even though there are no agg functions here, this is still aggregative as it references other aggregative expressions
+  profit_margin: profit / revenue
 )
 ```
 
@@ -221,7 +213,7 @@ If you recall the model from before:
 table orders (
   ...
   user_id BIGINT,
-  join_one users on user_id = users.id
+  join one users on user_id = users.id
 )
 
 table users (
@@ -253,23 +245,23 @@ Sometimes you need to access columns or stored expressions in a table that is tw
 table orders (
   ...
 
-  join_one users on user_id = users.id
+  join one users on user_id = users.id
 )
 
 table users (
   ...
 
-  join_many orders on id = orders.user_id,
-  join_one country on country_code = countries.code
+  join many orders on id = orders.user_id
+  join one country on country_code = countries.code
 )
 
 table countries (
-  code VARCHAR primary_key,
-  name VARCHAR,
-  currency VARCHAR,
-  free_shipping BOOLEAN,
+  code VARCHAR primary_key
+  name VARCHAR
+  currency VARCHAR
+  free_shipping BOOLEAN
 
-  join_many users on code = users.country_code
+  join many users on code = users.country_code
 )
 ```
 
@@ -294,21 +286,20 @@ Again, using the orders table from before:
 
 ```sql
 table orders (
-  id BIGINT primary_key,
-  user_id BIGINT,
-  created_at DATETIME,
-  status STRING, -- One of 'Processing', 'Shipped', 'Complete', 'Cancelled', 'Returned'
-  amount FLOAT, -- Amount paid by customer
-  cost FLOAT, -- Cost of materials
-
-  join_one users on user_id = users.id,
-
-  status in ('Processing', 'Shipped', 'Complete') as revenue_recognized,
-
-  sum(case when revenue_recognized then amount else 0 end) as revenue,
-  sum(case when revenue_recognized then cost else 0 end) as cogs,
-  revenue - cogs as profit,
-  profit / revenue as profit_margin
+  id BIGINT primary_key
+  user_id BIGINT
+  created_at DATETIME
+  status STRING -- One of 'Processing', 'Shipped', 'Complete', 'Cancelled', 'Returned'
+  amount FLOAT -- Amount paid by customer
+  cost FLOAT -- Cost of materials
+
+  join one users on user_id = users.id
+
+  revenue_recognized: status in ('Processing', 'Shipped', 'Complete')
+  revenue: sum(case when revenue_recognized then amount else 0 end)
+  cogs: sum(case when revenue_recognized then cost else 0 end)
+  profit: revenue - cogs
+  profit_margin: profit / revenue
 )
 ```
 
@@ -330,7 +321,7 @@ select
   status in ('Processing', 'Shipped', 'Complete') as revenue_recognized,
   count(*)
 from orders
-group by 1 
+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.
@@ -371,7 +362,7 @@ GSQL aims to solve this problem. With the additional information provided via `j
 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):
 
 ```sql
-SELECT 
+SELECT
    (CAST((
     (
       SUM(DISTINCT
@@ -388,51 +379,48 @@ FROM `bigquery-public-data.thelook_ecommerce.orders` as base
 
 You don't have to understand this; the point is that GSQL is minimizing the chances that naive users aggregate data incorrectly.
 
+#### Percentile shorthand
+
+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.).
+
 ### `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:
 
 ```sql
 table orders (
-  id BIGINT primary_key,
-  user_id BIGINT,
-  created_at DATETIME,
-  status STRING, -- One of 'Processing', 'Shipped', 'Complete', 'Cancelled', 'Returned'
-  amount FLOAT, -- Amount paid by customer
-  cost FLOAT, -- Cost of materials
-
-  join_one users on user_id = users.id,
-
-  status in ('Processing', 'Shipped', 'Complete') as revenue_recognized,
-
-  sum(case when revenue_recognized then amount else 0 end) as revenue,
-  sum(case when revenue_recognized then cost else 0 end) as cogs,
-  revenue - cogs as profit,
-  profit / revenue as profit_margin
+  id BIGINT primary_key
+  user_id BIGINT
+  created_at DATETIME
+  status STRING -- One of 'Processing', 'Shipped', 'Complete', 'Cancelled', 'Returned'
+  amount FLOAT -- Amount paid by customer
+  cost FLOAT -- Cost of materials
+
+  join one users on user_id = users.id
+
+  revenue_recognized: status in ('Processing', 'Shipped', 'Complete')
+  revenue: sum(case when revenue_recognized then amount else 0 end)
+  cogs: sum(case when revenue_recognized then cost else 0 end)
+  profit: revenue - cogs
+  profit_margin: profit / revenue
 )
 
 table users (
-  id BIGINT primary_key,
-  name VARCHAR,
-  email VARCHAR,
-  age INTEGER,
-
-  join_many orders on id = orders.user_id,
-  join_one user_facts on id = user_facts.id,
+  id BIGINT primary_key
+  name VARCHAR
+  email VARCHAR
+  age INTEGER
 
-  /* Scalar expressions */
+  join many orders on id = orders.user_id
+  join one user_facts on id = user_facts.id
 
-  user_facts.ltv as ltv,
-  user_facts.lifetime_orders as lifetime_orders
+  ltv: user_facts.ltv
+  lifetime_orders: user_facts.lifetime_orders
 )
 
 table user_facts as (
-  select
-    id,
-    orders.revenue as ltv,
-    count(orders.id) as lifetime_orders,
-  from users
-  group by id
+  select id, orders.revenue as ltv, count(orders.id) as lifetime_orders,
+  from users group by id
 )
 ```
 
@@ -440,6 +428,61 @@ table user_facts as (
 - 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.
 - 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 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.
+
+For example, if we have a `table as` statement that creates a daily summary of orders:
+
+```sql
+table daily_orders as (
+  select
+    date_trunc(created_at, day) as day,
+    count(*) as num_orders,
+    sum(amount) as total_revenue
+  from orders
+  group by 1
+)
+```
+
+We can extend this table to add measures or joins:
+
+```sql
+extend daily_orders (
+  join one calendar on day = calendar.date
+
+  avg_order_value: total_revenue / num_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.
@@ -449,6 +492,16 @@ table user_facts as (
 - 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)
 
@@ -493,7 +546,7 @@ Use bar or column charts to compare a metric across categories. Bar charts are b
 Here's an example:
 
 ```markdown
-<BarChart 
+<BarChart
   title="Sales by Category"
   data=orders_by_category_2021
   x=month
@@ -522,10 +575,10 @@ Here's an example:
 |----------|-------------|----------|---------|---------|
 | data | Query name, wrapped in curly braces | 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 | false | column name, stored expression name, GSQL expression, list of any combination of these | 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 | - |
+| 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 | 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 | - |
 | y2SeriesType | Chart type to apply to the series on the y2 axis | false | `bar`, `line`, `scatter` | `bar` |
-| series | Column or expression to use as the series (groups) in a multi-series chart | false | column name, stored expression name, GSQL expression | - |
+| 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 | - |
 | sort | Whether to apply default sort to your data. Default sort is x ascending for number and date x-axes, and y descending for category x-axes | false | `true`, `false` | `true` |
 | type | Grouping method to use for multi-series charts | false | `stacked`, `grouped`, `stacked100` | `stacked` |
 | stackName | Name for an individual stack. If separate Bar components are used with different stackNames, the chart will show multiple stacks | false | string | - |
@@ -608,7 +661,7 @@ Use a pie chart to show part-to-whole relationships across categories. Best for
 Here's an example:
 
 ```markdown
-<PieChart 
+<PieChart
   title="Sales share by category"
   data=orders_by_category_2021
   category=category
@@ -640,12 +693,12 @@ Use line charts to display how one or more metrics vary over time. Line charts a
 Here's an example:
 
 ```markdown
-<LineChart 
+<LineChart
   title="Monthly Sales"
   subtitle="Includes all categories"
   data=orders_by_month
   x=month
-  y=sales_usd0k 
+  y=sales_usd0k
   yAxisTitle="Sales per Month"
 />
 ```
@@ -670,10 +723,10 @@ Here's an example:
 |------|-------------|----------|---------|---------|
 | data | Query name, wrapped in curly braces | 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 | true | column name, stored expression name, GSQL expression, list of any combination of these | - |
-| 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 | - |
+| 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 | - |
+| 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 | - |
 | y2SeriesType | Chart type to apply to the series on the y2 axis | false | `line`, `bar`, `scatter` | `line` |
-| series | Column or expression to use as the series (groups) in a multi-series chart | false | column name, stored expression name, GSQL expression | - |
+| 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 | - |
 | sort | Whether to apply default sort to your data. Default is x ascending for number and date x-axes, and y descending for category x-axes | false | `true`, `false` | `true` |
 | handleMissing | Treatment of missing values in the dataset | false | `gap`, `connect`, `zero` | `gap` |
 | 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` |
@@ -752,7 +805,7 @@ Use area charts to track how a metric with multiple series changes over time, or
 Here's an example:
 
 ```markdown
-<AreaChart 
+<AreaChart
   data=orders_by_month
   x=month
   y=sales
@@ -779,8 +832,8 @@ Here's an example:
 |------|-------------|----------|---------|---------|
 | data | Query name, wrapped in curly braces | 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 | true | column name, stored expression name, GSQL expression, list of any combination of these | Any non-assigned numeric columns |
-| series | Column or expression to use as the series (groups) in a multi-series chart | false | 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 | 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 | - |
 | sort | Whether to apply default sort to your data. Default sort is x ascending for number and date x-axes, and y descending for category x-axes | false | `true`, `false` | `true` |
 | type | Grouping method to use for multi-series charts | false | `stacked`, `stacked100` | `stacked` |
 | handleMissing | Treatment of missing values in the dataset | false | `gap`, `connect`, `zero` | `gap` for single series, `zero` for multi-series |
@@ -851,8 +904,8 @@ Use big values to display a large value standalone, and optionally include a com
 Here's an example:
 
 ```markdown
-<BigValue 
-  data=orders_with_comparisons 
+<BigValue
+  data=orders_with_comparisons
   value=num_orders
   sparkline=month
   comparison=order_growth
@@ -1069,7 +1122,7 @@ The user-inputted text would then be referenced in GSQL via `$name_of_input`. Fo
 ```sql
 select *
 from users
-where email ilike concat('%', $name_of_input, '%') 
+where email ilike concat('%', $name_of_input, '%')
 ```
 
 ##### All text input attributes
@@ -1083,44 +1136,6 @@ where email ilike concat('%', $name_of_input, '%')
 | description | Adds an info icon with description tooltip on hover | false | string | - |
 
 
-#### Date range
-
-Creates a date picker that can be used to filter a query. Includes a set of preset ranges for quick selection of common date ranges (relative to the supplied end date). To see how to filter a query using an input component, see Filters.
-
-Here's an example:
-
-```markdown
-<DateRange
-  name=date_range_name
-  data=orders_by_day
-  dates=day
-/>
-```
-
-The start and end dates for the user-selected range would then be referenced in GSQL as `$date_range_name_start` and `$date_range_name_end` at the end. For example:
-
-```sql
-select *
-from orders
-where created_at > $date_range_name_start and < $date_range_name_end
-```
-
-##### All date range attributes
-
-| Attribute | Description | Required | Options | Default |
-|------|-------------|----------|---------|---------|
-| name | Name of the DateRange, used to reference the selected values elsewhere as `"$name_start"` or `"$name_end"` | true | string | - |
-| data | Query name, wrapped in curly braces | false | query name | - |
-| dates | Column or expression from the query containing date range to span | false | column name, stored expression name, GSQL expression | - |
-| start | A manually specified start date to use for the range | false | string formatted YYYY-MM-DD | - |
-| end | A manually specified end date to use for the range | false | string formatted YYYY-MM-DD | - |
-| title | Title to display in the Date Range component | false | string | - |
-| presetRanges | Customize "Select a Range" drop down, by including preset range options | false | list of values e.g. `"Last 7 Days, Last 30 Days"`. Allowed values: `Last 7 Days`, `Last 30 Days`, `Last 90 Days`, `Last 365 Days`, `Last 3 Months`, `Last 6 Months`, `Last 12 Months`, `Last Month`, `Last Year`, `Month to Date`, `Month to Today`, `Year to Date`, `Year to Today`, `All Time` | - |
-| defaultValue | Accepts preset in string format to apply default value in Date Range picker | false | `"Last 7 Days"`, `"Last 30 Days"`, `"Last 90 Days"`, `"Last 365 Days"`, `"Last 3 Months"`, `"Last 6 Months"`, `"Last 12 Months"`, `"Last Month"`, `"Last Year"`, `"Month to Date"`, `"Month to Today"`, `"Year to Date"`, `"Year to Today"`, `"All Time"` | - |
-| 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 | - |
-
-
 #### 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.
@@ -1132,10 +1147,10 @@ Here's an example:
 select distinct status from orders
 ```
 
-<Dropdown 
-  title="Select Order Status" 
+<Dropdown
+  title="Select Order Status"
   name="status_dropdown"
-  data="statuses" 
+  data="statuses"
   value="status"
   defaultValue="Complete"
 />
@@ -1201,20 +1216,20 @@ The easiest way to format numbers and dates in Graphene is through component att
 For example, you can use the `fmt` attribute to format values inside a BigValue component:
 
 ```markdown
-<BigValue 
-  data=sales_data 
-  value=sales 
-  fmt="$#,##0" 
+<BigValue
+  data=sales_data
+  value=sales
+  fmt="$#,##0"
 />
 ```
 
 Within charts, you can format individual columns using `xFmt` and `yFmt`:
 
 ```markdown
-<LineChart 
-  data=sales_data 
-  x=date 
-  y=sales 
+<LineChart
+  data=sales_data
+  x=date
+  y=sales
   xFmt="m/d"
   yFmt=eur
 />
@@ -1306,8 +1321,6 @@ These are the available commands:
 - `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.
-- `npm run graphene serve` - Starts (or restarts) the dev server, which allows the user to view their Graphene app on localhost.
-- `npm run graphene stop` - Stops the dev server.
 
 # AGENT INSTRUCTIONS
 
@@ -1318,6 +1331,6 @@ Follow these guidelines when working in a Graphene project.
 - 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>`. 
+   - 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.
+      - 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.

package/dist/ui/component-utilities/inputUtils.ts

@@ -23,3 +23,14 @@ export function serializeValue (value: unknown): string {
   let str = String(value)
   return `'${str.replace(/'/g, "''")}'`
 }
+
+// Parse a comma-separated list into an array of trimmed strings.
+// - Strings are split on commas; whitespace trimmed; empty entries removed.
+// - Arrays are normalized by trimming string items and String()-ing non-strings.
+// - null/undefined -> []
+export function parseCommaList (value: unknown): string[] {
+  if (value === undefined || value === null) return []
+  if (Array.isArray(value)) return value.map(v => typeof v === 'string' ? v.trim() : String(v)).filter(v => v.length > 0)
+  if (typeof value === 'string') return value.split(',').map(v => v.trim()).filter(v => v.length > 0)
+  return [String(value).trim()].filter(v => v.length > 0)
+}

package/dist/ui/components/Area.svelte

@@ -10,6 +10,7 @@
     getFormatObjectFromString,
   } from '../component-utilities/formatting.js'
   import {getThemeStores} from '../component-utilities/themeStores'
+  import {parseCommaList} from '../component-utilities/inputUtils.ts'
 
   const {resolveColor} = getThemeStores()
   const props = getContext(propKey)
@@ -72,12 +73,14 @@
   $: xMismatch = $props.xMismatch
   $: columnSummary = $props.columnSummary
   $: series = seriesSet ? series : $props.series
-  $: resolvedY = ySet ? y : $props.y
+  $: resolvedY = ySet ? parseCommaList(y) : $props.y
+  $: seriesOrder = parseCommaList(seriesOrder)
 
   $: {
-    if (!series && typeof resolvedY !== 'object') {
+    if (!series && (!Array.isArray(resolvedY) || resolvedY.length === 1)) {
       stackName = undefined
-      if (columnSummary?.[resolvedY]) name = name ?? formatTitle(resolvedY, columnSummary[resolvedY].title)
+      let col = Array.isArray(resolvedY) ? resolvedY[0] : resolvedY
+      if (columnSummary?.[col]) name = name ?? formatTitle(col, columnSummary[col].title)
     } else {
       stackName = 'area'
       data = getCompletedData(data, x, resolvedY, series, false, xType === 'value')

package/dist/ui/components/AreaChart.svelte

@@ -3,6 +3,7 @@
   import Area from './Area.svelte'
   import QueryLoad from './QueryLoad.svelte'
   import {getThemeStores} from '../component-utilities/themeStores'
+  import {parseCommaList} from '../component-utilities/inputUtils.ts'
 
   const {resolveColor, resolveColorsObject, resolveColorPalette} = getThemeStores()
 
@@ -83,7 +84,7 @@
   export let xLabelWrap = undefined
 </script>
 
-<QueryLoad data={data} fields={{x, y, series}} let:loaded>
+<QueryLoad data={data} fields={{x, y: parseCommaList(y), series}} let:loaded>
   <Chart
     data={loaded}
     chartContext={{data, x, y, series}}