@lightdash/cli 2.487.0 → 2.487.1

package/dist/vendor/template/references/custom-sql.md

@@ -0,0 +1,65 @@
+# Custom SQL in data apps
+
+Prefer existing modelled metrics and dimensions with the required business meaning. When custom SQL is necessary, use literal SQL strings and literal `table` and explore names, or simple constants that resolve to those strings. Define fields as plain objects in arrays. Named constants, imported constants, and spreads of literal arrays are supported; definitions do not have to be directly inline.
+
+Lightdash records the exact SQL from each app version to authorize registered viewers who can access the app. The extractor does not execute JavaScript. Do not construct SQL or field definitions through helper factories, `.map()`, string concatenation, or interpolated template literals. Keep SQL fixed and use SDK filters or declared Lightdash parameters for interactive values. Never interpolate user input into SQL.
+
+## Supported example
+
+```ts
+import { query } from '@lightdash/query-sdk';
+
+const EXPLORE = 'orders';
+const EXTRA_METRICS = [{
+    name: 'completed_count',
+    label: 'Completed orders',
+    table: 'orders',
+    type: 'sum',
+    sql: "CASE WHEN ${orders.status} = 'completed' THEN 1 ELSE 0 END",
+}];
+
+query(EXPLORE)
+    .label('Completed orders by status')
+    .dimensions(['status_label'])
+    .metrics(['completed_count'])
+    .additionalMetrics(EXTRA_METRICS)
+    .customDimensions([{
+        id: 'orders_status_label',
+        name: 'Status',
+        table: 'orders',
+        type: 'sql',
+        dimensionType: 'string',
+        sql: 'UPPER(${orders.status})',
+    }])
+    .tableCalculations([{
+        name: 'share',
+        displayName: 'Share of completed orders',
+        sql: '1.0 * ${orders.completed_count} / NULLIF(SUM(${orders.completed_count}) OVER (), 0)',
+    }]);
+```
+
+Here `${orders.status}` is part of a literal SQL string, not JavaScript interpolation. Use the existing modelled completed-order metric instead if one matches; the custom metric above illustrates the fallback only.
+
+Custom dimension IDs must match the SDK's qualified selection: `.dimensions(['status_label'])` on `query('orders')` selects `orders_status_label`, so use that full value for the definition's `id`. The returned row still uses the selected short name, `status_label`.
+
+## Unsupported example — rewrite before completing the build
+
+```ts
+import { query } from '@lightdash/query-sdk';
+
+const EXPLORE = 'orders';
+const METRIC = 'order_count';
+const sumWhen = (name, condition) => ({
+    name, table: EXPLORE, type: 'sum',
+    sql: `CASE WHEN ${condition} THEN 1 ELSE 0 END`,
+});
+
+query(EXPLORE)
+    .additionalMetrics([sumWhen('completed_count', "${orders.status} = 'completed'")])
+    .tableCalculations([{
+        name: 'share', displayName: 'Share',
+        sql: `\${${EXPLORE}.${METRIC}} / SUM(\${${EXPLORE}.${METRIC}}) OVER ()`,
+    }]);
+```
+
+Rewrite these as literal field definitions and SQL strings, preserving their calculation and filter semantics. Do not remove a requested calculation, change its denominator, or move it into client-side JavaScript merely to satisfy extraction. The pipeline provides source locations when it cannot capture custom SQL; fix those definitions in place.

package/dist/vendor/template/skill.md

@@ -69,6 +69,8 @@ Projects range from a handful of models to well over a thousand, so the director
 2. **Read only the model files the app actually needs**, e.g. `Read /tmp/dbt-repo/models/orders.yml`. Each file holds that model's complete dimensions, metrics, joins, parameters, and model-level filters.
 3. **Grep when the index isn't enough.** If you know a field name but not its model, `Grep` the directory for it. A wide model may be split across `<name>.yml`, `<name>.part2.yml`, … — the last line of each part points at the next.
 
+**Prefer modelled fields before defining custom metrics or dimensions.** Check the relevant model and joined-table fields by name, label, description, type, and `ai_hints`. Reuse a field when its business meaning, aggregation, grain, and filters match the request; do not recreate it just to change its label. The model context does not include field SQL, so do not claim SQL equivalence or guess a definition from its name. When no suitable field exists, custom SQL remains supported. Suggest modelling a reusable business definition as an optional follow-up, not a prerequisite for building the app.
+
 **Never read every model file, and never page through a file with `offset`/`limit`** — pick the model from the index and read that one file whole.
 
 ### Reading dbt YAML
@@ -272,7 +274,9 @@ which query produced it. One spread per query block is enough.
 
 ### Table calculations
 
-Table calculations are computed columns evaluated after the warehouse query returns. They can reference dimensions and metrics using `${table.field}` syntax in their SQL expression.
+Table calculations are computed columns evaluated in SQL over the aggregated query results. They can reference dimensions and metrics using `${table.field}` syntax in their SQL expression.
+
+Use client-side arithmetic only when the returned inputs preserve the intended meaning. For a percentage of total, the denominator must cover the intended population: the SDK defaults to 500 rows, so summing a limited or paginated result gives a percentage of those rows, not necessarily the overall total. Use a SQL calculation or a separately queried total with matching filters when needed. Keep calculations in the query when server-side sorting, filtering, or exports depend on them.
 
 ```ts
 query('orders')
@@ -323,6 +327,10 @@ Each additional metric needs:
 - If the metric exists in the dbt YAML → use `.metrics(['metric_name'])`
 - If you need a custom aggregation not in the YAML → define it with `.additionalMetrics()` AND include its name in `.metrics()`
 
+### Custom SQL and viewer access
+
+Before using `.additionalMetrics()`, `.customDimensions()`, or `.tableCalculations()`, read `/app/references/custom-sql.md`. The build pipeline checks that custom SQL can be statically extracted and sends unresolved definitions back for repair. This lets registered viewers run the recorded SQL without granting SQL-authoring permissions; normal data-access checks still apply.
+
 ### Parameters
 
 If the dbt YAML declares a `parameters:` block (under a model's `meta:` / `config.meta:`, or in `lightdash.config.yml`), read `/app/references/parameters.md` before using `.parameters()` — key naming is scope-dependent and a wrong key is silently ignored. Never invent parameters; when none are declared, use `.filters()` instead.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightdash/cli",
-  "version": "2.487.0",
+  "version": "2.487.1",
   "description": "Lightdash CLI tool",
   "license": "MIT",
   "repository": {
@@ -22,8 +22,8 @@
     "@actions/core": "1.11.1",
     "@aws-sdk/credential-providers": "3.995.0",
     "@casl/ability": "6.8.0",
-    "@lightdash/common": "2.487.0",
-    "@lightdash/warehouses": "2.487.0",
+    "@lightdash/common": "2.487.1",
+    "@lightdash/warehouses": "2.487.1",
     "@sidvind/better-ajv-errors": "7.0.0",
     "@types/columnify": "1.5.1",
     "ajv": "8.18.0",