@graphenedata/cli 0.0.15 → 0.0.17

package/dist/skills/graphene/references/gsql.md

@@ -17,8 +17,8 @@ table orders (
   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
+  amount FLOAT -- Amount paid by customer #units=usd
+  cost FLOAT -- Cost of materials #units=usd
 
   -- Join relationships
 
@@ -30,10 +30,10 @@ table orders (
   
   -- Measures
   
-  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
+  revenue: sum(case when revenue_recognized then amount else 0 end) #units=usd
+  cogs: sum(case when revenue_recognized then cost else 0 end) #units=usd
+  profit: revenue - cogs #units=usd
+  profit_margin: profit / revenue #ratio
 )
 
 table users (
@@ -53,6 +53,16 @@ We can break down a `table` statement into three parts: base columns, join relat
 
 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.
 
+For array columns, GSQL uses `array<T>` as the standard syntax:
+
+```sql
+table events (
+  id BIGINT
+  tags array<string>
+  scores array<int64>
+)
+```
+
 ### 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.
@@ -113,13 +123,33 @@ table orders (
   revenue_recognized: status in ('Processing', 'Shipped', 'Complete')
 
   /* Agg expressions */
-  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
+  revenue: sum(case when revenue_recognized then amount else 0 end) #units=usd
+  cogs: sum(case when revenue_recognized then cost else 0 end) #units=usd
+  profit: revenue - cogs #units=usd -- even though there are no agg functions here, this is still aggregative as it references other aggregative expressions
+  profit_margin: profit / revenue #ratio
 )
 ```
 
+### Metadata annotations
+
+Certain GSQL expressions will create field-level metadata that Graphene uses for better formatting and visualizations defaults. For example, `date_trunc('month', created_at)` will attach `timeGrain=month` metadata to the resulting column, which informs Graphene that the values represent months and not just days that happen to land on the first of every month. Graphene leverages this information to make sure that value formatting and chart axes look good by default.
+
+There isn't always a SQL expression that can tip Graphene to the semantic meaning of a field, however:
+- The field could be a base column that has no source expression
+- There might not be enough information in the expression (eg. what currency a float is tied to)
+
+For this reason, some metadata should be set explicitly in the GSQL model, using annotations. Metadata annotations resemble hashtags (eg. `#ratio`, `#units=usd`) that can be inlined or written above the object they decorate.
+
+#### Recognized metadata
+
+| Key | Inferrable? | Effect |
+|---|---|---|
+| `#ratio` | no | Value is 0–1; rendered as `value × 100%` (e.g. `0.42` → `42%`) |
+| `#pct` | no | Value is already 0–100; rendered as `value%` (e.g. `42` → `42%`) |
+| `#units=<currency>` | no | Adds currency symbol and compacts to K/M/B. Accepted values: `usd`, `eur`, `gbp`, `cad`, `aud`, `jpy` |
+| `#timeGrain=<grain>` | yes (from `date_trunc`, `date_bin`, casts) | Controls time axis label format. Values: `year`, `quarter`, `month`, `week`, `day`, `hour`, `minute`, `second` |
+| `#timeOrdinal=<ordinal>` | yes (from `extract`) | Treats values as ordinal positions on a categorical axis. Values: `hour_of_day`, `day_of_month`, `day_of_year`, `week_of_year`, `month_of_year`, `quarter_of_year`, `dow_0s` (0=Sun), `dow_1s` (1=Sun), `dow_1m` (1=Mon) |
+
 ## `select` statements
 
 `select` in GSQL has been extended to leverage join relationships, dimensions, and measures.
@@ -211,16 +241,16 @@ table orders (
   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
+  amount FLOAT -- Amount paid by customer #units=usd
+  cost FLOAT -- Cost of materials #units=usd
 
   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
+  revenue: sum(case when revenue_recognized then amount else 0 end) #units=usd
+  cogs: sum(case when revenue_recognized then cost else 0 end) #units=usd
+  profit: revenue - cogs #units=usd
+  profit_margin: profit / revenue #ratio
 )
 ```
 
@@ -286,7 +316,7 @@ Another way of thinking about this is that measures are "self-aggregating."
 - `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`.
-- Inline window functions are supported using ANSI-style `OVER (...)` clauses. Query-level named windows (`WINDOW w AS (...)`) and set operations (`union [all]`, `intersect`, `except`) are not supported.
+- Inline window functions are supported using ANSI-style `OVER (...)` clauses. Query-level named windows (`WINDOW w AS (...)`) are not supported.
 - Percentiles can be computed easily using Graphene's special functions `pXX(col)` (e.g., p50, p975, p9999).
 - Graphene supports almost all functions of the connected data warehouse. Check package.json to see which database you're connected to.
 
@@ -300,16 +330,16 @@ table orders (
   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
+  amount FLOAT -- Amount paid by customer #units=usd
+  cost FLOAT -- Cost of materials #units=usd
 
   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
+  revenue: sum(case when revenue_recognized then amount else 0 end) #units=usd
+  cogs: sum(case when revenue_recognized then cost else 0 end) #units=usd
+  profit: revenue - cogs #units=usd
+  profit_margin: profit / revenue #ratio
 )
 
 table users (
@@ -321,7 +351,7 @@ table users (
   join many orders on id = orders.user_id
   join one user_facts on id = user_facts.id
 
-  ltv: user_facts.ltv
+  ltv: user_facts.ltv #units=usd
   lifetime_orders: user_facts.lifetime_orders
 )
 
@@ -358,6 +388,6 @@ We can extend this table to add measures or joins:
 extend regional_orders (
   join one regions on region = regions.name
 
-  avg_order_value: total_revenue / num_orders
+  avg_order_value: total_revenue / num_orders #units=usd
 )
 ```

package/dist/skills/graphene/references/model-gsql.md

@@ -0,0 +1,70 @@
+# Modeling GSQL
+
+Conventions and patterns for writing production-quality `.gsql` semantic models. Make sure you've read `references/gsql.md` before proceeding.
+
+## New table workflow
+
+1. Generate a plain `.gsql` file first: `graphene schema {DB.SCHEMA.TABLE} > tables/{snake_case_table_name}.gsql`
+2. Add table and grain descriptions at the top of the file. If given a dbt project, look up the table's definition, lineage, and related metadata so that you have the full picture.
+3. Add join relationships.
+   - If no join documentation is provided, make an educated guess from PK/FK names.
+   - Use `graphene run <query>` to confirm the join works as expected: keys match, row counts are sane, and there is no fan-out.
+   - Model joins from boths sides (ie. add the join to each respective `table` statement)
+
+4. Add dimensions and measures **ONLY** if a semantic model to migrate from has been provided.
+   - Compile-verify: `npx graphene compile "from TABLE select dimension1, dimension2, measure1, measure2"`
+
+5. Add descriptions to columns, dimensions, and measures via comments.
+   - Do not add a description if it already obvious from the name. For example, skip `is_debooked_opportunity BOOLEAN -- Whether the opportunity has been debooked`.
+   - Use example values for categorical columns: `graphene run "from TABLE select distinct col limit 10"`.
+   - Add synonyms, but only if provided. **DO NOT** guess them.
+   - Descriptions can be inlined or placed as a block comment on the line above.
+
+6. Add GSQL metadata annotations where applicable eg. `#ratio`, `#pct`, `#timeGrain=day`, etc.
+   - Use only annotations that Graphene recognizes (see `references/gsql.md`)
+
+## File structure
+
+Every `.gsql` file follows this section order:
+
+```sql
+-- One-sentence description of what this table contains.
+-- Each row is one <entity> (<primary_or_unique_key_col(s)>).
+table DATABASE.SCHEMA.TABLE_NAME (
+
+  /* Sub-section headers as needed, to group up fields if there are many columns */
+
+  column_name TYPE -- A description and a #annotation
+
+  -- OR, descriptions/metadata for a field/dimension/measure can be on the lines above it
+  -- as long as there is NOT an empty line separating
+  column_name2 TYPE
+
+  /* Join relationships */
+
+  join { one | many } [ database.schema. ]table [ as alias ] on key = table_or_alias_name.key
+
+  /* Dimensions */
+
+  dim_name: expression #annotationWithoutDescription
+
+  /* Measures */
+
+  measure_name: aggregate_expression
+)
+
+/* Example queries */ -- Only if correct query usage patterns are not obvious
+
+-- Description of query
+select ...
+;
+```
+
+Section headers use `/* Header */` style. Section headers need a full newline following them or GSQL will assume the header is a comment decorator for the object on the line below it.
+
+## Compile-verify workflow
+
+Always verify after changes. A parse error in any `.gsql` file prevents all tables from loading. If you see "Unknown table" errors everywhere, check for syntax errors in recently modified files.
+
+You can syntax check the whole project with `graphene check`.
+

package/dist/skills/graphene/references/table.md

@@ -15,7 +15,6 @@ Here's an example:
 | 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 | - |
 | headerColor | Background color of the header row | false | Hex color code, css color name | - |
 | headerFontColor | Font color of the header row | false | Hex color code, css color name | - |
 | totalRow | Show a total row at the bottom of the table, defaults to sum of all numeric columns | false | `true`, `false` | `false` |
@@ -27,16 +26,21 @@ Here's an example:
 | backgroundColor | Background color of the table | false | Hex color code, css color name | - |
 | sortable | Enable sort for each column - click the column title to sort | false | `true`, `false` | `true` |
 | sort | Column to sort by on initial page load. Sort direction is asc if unspecified. Can only sort by one column using this prop. If you need multi-column sort, use the order by clause in your sql in combination with this prop. | false | 'column name + asc/desc' | - |
-| search | Add a search bar to the top of your table | false | `true`, `false` | `false` |
-| downloadable | Enable download data button below the table on hover | false | `true`, `false` | `true` |
 | formatColumnTitles | Enable auto-formatting of column titles. Turn off to show raw SQL column names | false | `true`, `false` | `true` |
 | wrapTitles | Wrap column titles | false | `true`, `false` | `false` |
 | compact | Enable a more compact table view that allows more content vertically and horizontally | false | `true`, `false` | `false` |
 | link | Makes each row of your table a clickable link. Accepts a column or expression containing the link to use for each row in your table | false | column name, stored expression name, GSQL expression | - |
 | showLinkCol | Whether to show the column supplied to the `link` attribute | false | `true`, `false` | `false` |
-| generateMarkdown | Helper for writing Table syntax with many columns. When set to true, markdown for the Table including each `Column` contained within the query will be generated and displayed below the table. | false | `true`, `false` | `false` |
-| 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" |
+| emptyMessage | Text to display when the table has no rows or fails to render | false | string | `"Unable to render table"` |
+
+### Semantic colors
+
+Any color attribute on `<Table>` or `<Column>` (e.g. `headerColor`, `barColor`, `colorScale`) accepts the semantic names `primary`, `positive`, `negative`, and `warning` in addition to hex codes and CSS color names. They resolve to the current theme's colors so they stay consistent if the theme changes.
+
+```markdown
+<Column id=growth contentType=colorscale colorScale=positive />
+<Column id=churn contentType=colorscale colorScale=negative />
+```
 
 ## Groups
 
@@ -45,7 +49,6 @@ Here's an example:
 | groupBy | Column or expression to use to create groups. Note that groups are currently limited to a single group column. | false | column name, stored expression name, GSQL expression | - |
 | groupType | How the groups are shown in the table. Can be accordion (expand/collapse) or section (group column values are merged across rows) | false | `accordion`, `section` | `accordion` |
 | subtotals | Whether to show aggregated totals for the groups | false | `true`, `false` | `false` |
-| subtotalFmt | Specify an override format to use in the subtotal row ([see available formats](#value-formatting)). Custom strings or values are unformatted by default. | false | Excel-style format, built-in format | - |
 | groupsOpen | [groupType=accordion] Whether to show the accordions as open on page load | false | `true`, `false` | `true` |
 | accordionRowColor | [groupType=accordion] Background color for the accordion row | false | Hex color code, css color name | - |
 | subtotalRowColor | [groupType=section] Background color for the subtotal row | false | Hex color code, css color name | - |
@@ -62,8 +65,8 @@ Here's an example:
 <Table data=country_summary>
   <Column id=country />
   <Column id=category />
-  <Column id=value_usd fmt=eur />
-  <Column id=yoy title="Y/Y Growth" fmt=pct3 />
+  <Column id=value_usd />
+  <Column id=yoy title="Y/Y Growth" />
 </Table>
 ```
 
@@ -73,11 +76,7 @@ Here's an example:
 | title | Override title of column | false | string | column name (formatted) |
 | description | Adds an info icon with description tooltip on hover | false | string | - |
 | align | Align column text | false | `left`, `center`, `right` | `left` |
-| fmt | Format the values in the column ([see available formats](#value-formatting)) | false | Excel-style format, built-in format | - |
-| fmtColumn | Column to use to format values in this column. This is used to achieve different value formats by row. The fmtColumn should contain strings of format codes - either Graphene built-in formats or Excel codes. | false | column name | - |
-| totalAgg | Specify an aggregation function to use for the total row. Accepts predefined functions, custom strings or values | false | `sum`, `mean`, `weightedMean`, `median`, `min`, `max`, `count`, `countDistinct`, custom string or value | `sum` |
-| totalFmt | Specify an override format to use in the total row ([see available formats](#value-formatting)). Custom strings or values are unformatted by default. | false | Excel-style format, built-in format | - |
-| weightCol | Column or expression to use as the weight values for weighted mean aggregation. If not specified, a weight of 1 for each value will be used and the result will be the same as the `mean` aggregation. | false | column name, stored expression name, GSQL expression | - |
+| totalAgg | Specify an aggregation function to use for the total row. Accepts predefined functions, custom strings or values | false | `sum`, `mean`, `median`, `min`, `max`, `count`, `countDistinct`, custom string or value | `sum` |
 | wrap | Wrap column text | false | `true`, `false` | `false` |
 | wrapTitle | Wrap column title | false | `true`, `false` | `false` |
 | contentType | Lets you specify how to treat the content within a column. See below for contentType-specific options. | false | `link`, `image`, `delta`, `colorscale`, `html` | - |

package/dist/skills/graphene/references/text-input.md

@@ -17,6 +17,8 @@ from users
 where email ilike concat('%', $name_of_input, '%')
 ```
 
+Text input values also sync into the page URL query string so a reload or shared link preserves the same filter state.
+
 # Attributes
 
 | Attribute | Description | Required | Options | Default |
@@ -24,5 +26,4 @@ where email ilike concat('%', $name_of_input, '%')
 | name | Name of the text input, used to reference the selected value elsewhere as `"$name"` | true | string | - |
 | title | Title displayed above the text input | false | string | - |
 | placeholder | Alternative placeholder text displayed in the text input | false | string | `"Type to search"` |
-| 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 | - |