@lightdash/cli 1.39.2 → 1.40.0

package/dist/vendor/template/skill.md

@@ -56,7 +56,7 @@ The available data models are defined in dbt YAML files at **`/tmp/dbt-repo/mode
 Projects range from a handful of models to well over a thousand, so the directory is indexed rather than inlined:
 
 1. **Read `/tmp/dbt-repo/models/_index.md` first.** It lists every model, most-queried first, with its file name, dimension/metric counts, joined tables, and description.
-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, and parameters.
+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.
 
 **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.
@@ -141,6 +141,16 @@ query('orders')
 
 Each entry under `meta.joins` may carry a `relationship` (`one-to-many`, `many-to-one`, `one-to-one`, `many-to-many`) and a `sql_on` condition — either can be absent. When a `relationship` is present, use it to reason about grain and fan-out: joining a `one-to-many` table multiplies base rows, so aggregating a base metric across that join can double-count — prefer a metric defined on the "many" side, or aggregate before joining.
 
+### Model-level filters — check before querying
+
+Some models declare filters in their `meta:` block (the index marks them with `filters=…`). They change what every query against that model returns, so account for them when writing queries:
+
+- **`required_filters`** — the backend force-ANDs each of these onto every query against the model, **unless your query has its own filter on the same field** (another time interval of the same date field also counts: filtering `order_date_month` overrides a required filter on `order_date`). If the user asks for a range that conflicts with a required filter (e.g. "last 90 days" but the model requires the last 4 weeks), you MUST add your own filter on that field — without one, the backend's filter silently caps your results.
+- **`default_filters`** — NOT enforced by the backend, but Lightdash's own Explore UI pre-applies them. Apply them in your queries by default so the app's numbers match what users see in Lightdash; drop or replace one only when the user's request conflicts with it.
+- **`sql_filter`** — a raw SQL condition ANDed onto every query against the model. It cannot be overridden or removed. Factor it into naming and copy — a model filtered to `status = 'completed'` must not be labelled "all orders" — and consider it when results look narrower than expected.
+
+Entries under `required_filters` / `default_filters` use the SDK `Filter` shape (`field`, `operator`, `value`, `unit`) — pass them to `.filters([...])` as-is.
+
 ### Understanding data grain
 
 When designing queries, consider the model's grain — what combination of dimensions produces one unique row. If the grain includes dimensions you aren't selecting, you may need filters to avoid duplicates. Estimate row counts from the grain to set appropriate `.limit()` values.
@@ -228,6 +238,8 @@ const bySegment = base.label('Revenue by Segment').dimensions(['customer_segment
 const byRegion = base.label('Revenue by Region').dimensions(['region']);
 ```
 
+**Sharing the explore-name constant:** define it in the component that uses it, or in its own module (e.g. `src/lib/constants.js`). Never export it from a component file that imports its consumers — that circular import evaluates the consumer first, the constant is `undefined` when a module-scope `query(...)` runs, and the app crashes on load.
+
 KPI cards — metrics without dimensions gives a single aggregated row:
 ```ts
 query('orders').label('KPI Summary').metrics(['total_revenue', 'order_count']).limit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightdash/cli",
-  "version": "1.39.2",
+  "version": "1.40.0",
   "description": "Lightdash CLI tool",
   "license": "MIT",
   "repository": {
@@ -41,8 +41,8 @@
     "unique-names-generator": "4.7.1",
     "uuid": "11.1.1",
     "yaml": "2.8.3",
-    "@lightdash/common": "1.39.2",
-    "@lightdash/warehouses": "1.39.2"
+    "@lightdash/common": "1.40.0",
+    "@lightdash/warehouses": "1.40.0"
   },
   "devDependencies": {
     "@types/inquirer": "8.2.4",