@picked/client 0.0.70-next.5 → 0.0.70

package/dist/docs/pickedql/examples.md

@@ -51,7 +51,9 @@ ORDER BY project_local_date
 
 ## Custom conversion rate definition
 
-Override the default purchase conversion with your own numerator and denominator. Useful when conversion is defined by a form submission, lead capture, or any custom event.
+Override the default conversion, which counts a `purchase` event, with your own
+numerator and denominator. Use this when a form submission, a lead capture, or
+another event of your own defines a conversion.
 
 ```sql
 -- Lead capture conversion: form submissions / lead-capture step entries
@@ -75,7 +77,7 @@ ORDER BY project_local_date
 You can also combine multiple events with `OR` and group with parentheses:
 
 ```sql
--- Either checkout_complete or order_create counts as a conversion
+-- A `checkout_complete` event or an `order_create` event counts as a conversion.
 SELECT
   control_conversion_rate(
     'event_type=checkout_complete OR event_type=order_create'
@@ -87,12 +89,15 @@ FROM events
 WHERE project_id = '{{ your project ID }}'
 ```
 
-## Custom segment with `control_users` / `variant_users`
+## Your own segment with `control_users` and `variant_users`
 
-On `events`, `control_users` / `variant_users` / `control_sessions` / `variant_sessions` accept an optional filter string to count only users/sessions matching the given expression in addition to the implicit `variant_type` filter.
+On `events`, four functions take an optional filter string: `control_users`,
+`variant_users`, `control_sessions`, and `variant_sessions`. The filter counts only a
+user or a session that matches your expression. It applies together with the
+`variant_type` filter that PickedQL adds.
 
 ```sql
--- Control users who fired app_initialize, broken down by step
+-- The control users who fired an `app_initialize` event, by step.
 SELECT
   step_id,
   control_users('event_type=app_initialize')                      AS control_initialized,
@@ -113,10 +118,13 @@ WHERE project_id = '{{ your project ID }}'
 
 ## Conversion rate from nested virtual functions
 
-When numerator and denominator come from different segments — e.g., Control users who fired a custom event divided by **all** users (not just Control) — pass virtual function calls directly as conversion-rate args:
+The numerator and the denominator can come from different segments. An example is the
+control users who fired an event of your own, divided by **all** users and not by the
+control users alone. For that, pass a virtual function call directly as an argument
+of the conversion rate:
 
 ```sql
--- (Control users who fired app_initialize) / (all users, regardless of variant)
+-- The control users who fired `app_initialize`, over all users of every variant.
 SELECT
   control_conversion_rate(
     control_users('event_type=app_initialize'),
@@ -188,9 +196,9 @@ GROUP BY utm_source
 
 | utm_source | users  | purchasers |
 | ---------- | ------ | ---------- |
-| meta       | 12031  | 101        |
-| fb         | 3656   | 31         |
-| an         | 100366 | 299        |
+| `meta`       | 12031  | 101        |
+| `fb`         | 3656   | 31         |
+| `an`         | 100366 | 299        |
 
 ## Step funnel for variant users
 
@@ -211,18 +219,20 @@ ORDER BY variant DESC
 
 | step_id                        | variant |
 | ------------------------------ | ------- |
-| who-are-you-protecting-step    | 1093    |
-| about-yourself-step            | 533     |
-| date-of-birth-step             | 435     |
-| employment-status-step         | 408     |
-| nicotine-usage-step            | 407     |
-| coverage-motivation-step       | 405     |
-| lead-capture-step              | 398     |
+| `who-are-you-protecting-step`    | 1093    |
+| `about-yourself-step`            | 533     |
+| `date-of-birth-step`             | 435     |
+| `employment-status-step`         | 408     |
+| `nicotine-usage-step`            | 407     |
+| `coverage-motivation-step`       | 405     |
+| `lead-capture-step`              | 398     |
 
 
 ## Sankey — overall user journey
 
-Forward window from the starting step. Non-reachers of `targeting_step` still contribute edges up to `num_nodes_after_start`. Mirrors dashboard 1156 card 4129's semantics.
+A forward window from the starting step. A user who never reaches `targeting_step`
+still gives edges, up to `num_nodes_after_start`. This does what card 4129 on
+dashboard 1156 does.
 
 ```sql
 SELECT source, target, users FROM experience_journey
@@ -236,13 +246,15 @@ WHERE project_id            = '{{ your project ID }}'
 
 | source                    | target                    | users |
 | ------------------------- | ------------------------- | ----- |
-| 001. step-start           | 002. step-questionnaire-1 | 182   |
-| 002. step-questionnaire-1 | 003. step-quote           | 144   |
-| 003. step-quote           | 004. step-target          | 121   |
+| `001. step-start`           | `002. step-questionnaire-1` | 182   |
+| `002. step-questionnaire-1` | `003. step-quote`           | 144   |
+| `003. step-quote`           | `004. step-target`          | 121   |
 
-## Sankey — top paths leading to a target step
+## Sankey — the top paths to a target step
 
-Backward window anchored at the target, plus top-N path ranking. Mirrors dashboard 1156 card 3961 / dashboard 991 card 2740 semantics.
+A backward window anchored at the target. It also ranks the paths and keeps the ones
+with the most users. This does what card 3961 on dashboard 1156 and card 2740 on
+dashboard 991 do.
 
 ```sql
 SELECT source, target, users FROM experience_journey
@@ -284,6 +296,6 @@ WHERE project_id = '{{ your project ID }}'
 
 | device_category | user_canonical_id                    |
 | --------------- | ------------------------------------ |
-| Mobile          | 019cc336-5a6a-7c32-b638-cdcc983b3e70 |
-| Mobile          | 019cc336-5a6a-7d8f-994c-69bc28e5f550 |
-| Mobile          | 019cc80f-503c-7181-b2c6-986b1f76d496 |
+| Mobile          | `019cc336-5a6a-7c32-b638-cdcc983b3e70` |
+| Mobile          | `019cc336-5a6a-7d8f-994c-69bc28e5f550` |
+| Mobile          | `019cc80f-503c-7181-b2c6-986b1f76d496` |

package/dist/docs/pickedql/filtering.md

@@ -2,17 +2,19 @@
 layout: docs
 ---
 
-# Filtering
+# Filters
 
-Add `WHERE` clauses as usual. Every query must include a `project_id` filter — PickedQL extracts it and verifies you have permission to access that project. Queries without a `project_id` filter are rejected.
+Add a `WHERE` clause in the usual way. Every query must hold a `project_id` filter.
+PickedQL reads that filter and checks that you have permission for the project.
+PickedQL rejects a query with no `project_id` filter.
 
 ```sql
--- Date range
+-- A range of dates.
 SELECT control_users() FROM metrics
 WHERE project_id = 'your-project-id'
   AND project_local_date BETWEEN '2026-03-01' AND '2026-03-31'
 
--- By experience
+-- By experience.
 SELECT step_enter_users() FROM events
 WHERE project_id = 'your-project-id'
   AND experience_id = 'my-experience'
@@ -30,9 +32,11 @@ WHERE project_id = 'your-project-id'
 Each query can only filter on a single `project_id`. Queries that reference multiple projects will be rejected.
 :::
 
-## Reference tables (per-table tenant filter)
+## Reference tables, each with its own tenant filter
 
-Queries against the reference tables (`steps`, `experiences`, `projects`) require their own tenant filter so you only see rows belonging to a project you have access to:
+A query against a reference table needs its own tenant filter. The reference tables
+are `steps`, `experiences`, and `projects`. The filter makes sure that you see only
+the rows of a project that you can reach:
 
 | Source | Tenant filter |
 |---|---|

package/dist/docs/pickedql/index.md

@@ -4,33 +4,51 @@ layout: docs
 
 # PickedQL
 
-PickedQL is a SQL query language for querying your Picked analytics data. Write simple SQL using virtual tables and functions — PickedQL expands them into optimized queries with automatic joins and A/B test aggregations.
+PickedQL is a SQL query language for your Picked analytics data. Write short SQL with
+a virtual table and a virtual function. PickedQL expands them into a full query, and
+it adds the joins and the A/B test aggregations for you.
 
 ## Quick start
 
 ```sql
--- How many users are in the control vs variant group?
+-- How many users are in the control group, and how many in the variant group?
 SELECT control_users(), variant_users()
 FROM metrics
 WHERE project_id = 'your-project-id'
 ```
 
-PickedQL handles table mapping and dimension joins automatically. You write concise, readable SQL — PickedQL does the rest.
+PickedQL maps each table and adds each dimension join for you. You write short SQL
+that a person can read, and PickedQL does the rest.
 
 ## How PickedQL works
 
-1. **Virtual table expansion**: Table names like `metrics` map to underlying data tables
-2. **Virtual function expansion**: Shorthand functions like `control_users()` expand to full aggregate expressions
-3. **Auto dimension joins**: References to dimension columns (like `device_category` or `country_code`) trigger automatic `LEFT JOIN` clauses — you never write joins yourself
-4. **Tenant isolation**: Every query must include a tenant filter in the `WHERE` clause — usually `project_id`, but `projects` uses `id` (the row's `id` IS the project id). PickedQL extracts the filter and verifies you have permission to access that project
-5. **SQL passthrough**: Standard SQL (including `CASE WHEN`, window functions, and subqueries) works alongside virtual functions
+1. **Virtual table expansion**: a table name such as `metrics` maps to the data
+   tables below it.
+2. **Virtual function expansion**: a short function such as `control_users()` expands
+   to a full aggregate expression.
+3. **Automatic dimension joins**: PickedQL adds a `LEFT JOIN` when you point at a
+   dimension column, such as `device_category` or `country_code`. You write no join.
+4. **Tenant isolation**: every query must hold a tenant filter in the `WHERE` clause.
+   That filter is `project_id` for most tables. The `projects` table uses `id`
+   instead, because the `id` of the row is the project ID. PickedQL reads the filter
+   and checks that you have permission for that project.
+5. **SQL passthrough**: standard SQL works next to a virtual function. This includes
+   `CASE WHEN`, a window function, and a subquery.
 
 ## Best practices
 
-- **Use `metrics` for dashboards**: Pre-aggregated data is significantly faster than raw events for standard reporting
-- **Use `events` for deep dives**: Raw event-level data gives full flexibility for custom breakdowns and funnels
-- **Use `experience_journey` for sankey / funnel charts**: One line of SQL returns `source, target, users` — the 8-CTE scaffold (dedup, top-N path ranking, lagInFrame) is handled internally; pass parameters via `WHERE`
-- **Don't write JOINs**: PickedQL injects them automatically when you reference dimension columns
-- **Group by any dimension**: Add dimension columns to `SELECT` and `GROUP BY` freely — required joins are handled for you
-- **Reference table metadata for free**: Use `step_title`, `experience_title`, `project_name` directly in `events` queries — PickedQL auto-joins the `steps`, `experiences`, and `projects` reference tables
+- **Use `metrics` for a dashboard**: data that PickedQL aggregates first is much
+  faster than raw events for a standard report.
+- **Use `events` to go deeper**: raw event data lets you build any breakdown or
+  funnel that you want.
+- **Use `experience_journey` for a sankey chart or a funnel chart**: one line of SQL
+  returns `source, target, users`. PickedQL builds the eight common table expressions
+  for you. Those remove the duplicates, rank the top paths, and call `lagInFrame`.
+  Pass your parameters in the `WHERE` clause.
+- **Write no JOIN**: PickedQL adds each one when you point at a dimension column.
+- **Group by any dimension**: add a dimension column to `SELECT` and to `GROUP BY`.
+  PickedQL adds the join that it needs.
+- **Read the reference tables for no cost**: use `step_title`, `experience_title`, and
+  `project_name` directly in an `events` query. PickedQL joins the `steps`,
+  `experiences`, and `projects` reference tables for you.
 

package/dist/docs/pickedql/schema.md

@@ -12,23 +12,23 @@ Pre-aggregated daily data. One row per unique combination of dimensions per day.
 
 | Column | Type | Description |
 |---|---|---|
-| `project_id` | String | Project identifier (required in `WHERE`) |
-| `project_local_date` | Date | Date in project timezone |
-| `experience_id` | String | Experience identifier |
-| `step_id` | String | Step identifier |
-| `event_type` | String | Event type (e.g., `page_view`, `click`) |
-| `interaction_type` | String | Interaction type (e.g., `Button Click`) |
-| `variant_type` | String | `Control`, `Variant`, or `Unknown` |
-| `device_category` | String | Device category (e.g., `Desktop`, `Mobile`) |
-| `country_code` | String | ISO country code |
-| `utm_source` | String | UTM source |
-| `utm_medium` | String | UTM medium |
-| `product_name` | String | Product name |
-| `product_category` | String | Product category |
-| `landing_page_url` | String | Landing page URL |
+| `project_id` | `String` | Project identifier (required in `WHERE`) |
+| `project_local_date` | `Date` | Date in project timezone |
+| `experience_id` | `String` | Experience identifier |
+| `step_id` | `String` | Step identifier |
+| `event_type` | `String` | Event type (for example `page_view`, `click`) |
+| `interaction_type` | `String` | Interaction type (for example `Button Click`) |
+| `variant_type` | `String` | `Control`, `Variant`, or `Unknown` |
+| `device_category` | `String` | Device category (for example `Desktop`, `Mobile`) |
+| `country_code` | `String` | ISO country code |
+| `utm_source` | `String` | UTM source |
+| `utm_medium` | `String` | UTM medium |
+| `product_name` | `String` | Product name |
+| `product_category` | `String` | Product category |
+| `landing_page_url` | `String` | Landing page URL |
 
 :::note
-Aggregate columns (`users`, `sessions`, `events`, etc.) are not queried directly — use [virtual functions](./virtual-functions) instead.
+Aggregate columns (`users`, `sessions`, `events`, and so on) are not queried directly — use [virtual functions](./virtual-functions) instead.
 :::
 
 ## `events`
@@ -39,22 +39,22 @@ User-level event data. One row per event per user. Dimension columns are joined
 
 | Column | Type | Description |
 |---|---|---|
-| `project_id` | String | Project identifier (required in `WHERE`) |
-| `event_id` | String | Unique event identifier |
-| `user_canonical_id` | String | Canonical user identifier |
-| `session_id` | String | Session identifier |
-| `experience_id` | String | Experience identifier |
-| `step_id` | String | Step identifier |
-| `event_type` | String | Event type (e.g., `page_view`, `click`) |
-| `interaction_type` | String | Interaction type (e.g., `Button Click`) |
-| `client_local_date` | Date | Date in client timezone |
-| `is_purchase` | UInt8 | `1` if checkout complete event |
-| `is_cart_add` | UInt8 | `1` if cart add event |
-| `is_first_session` | UInt8 | `1` if first session for this user |
-| `landing_page_url` | String | Landing page URL |
+| `project_id` | `String` | Project identifier (required in `WHERE`) |
+| `event_id` | `String` | Unique event identifier |
+| `user_canonical_id` | `String` | Canonical user identifier |
+| `session_id` | `String` | Session identifier |
+| `experience_id` | `String` | Experience identifier |
+| `step_id` | `String` | Step identifier |
+| `event_type` | `String` | Event type (for example `page_view`, `click`) |
+| `interaction_type` | `String` | Interaction type (for example `Button Click`) |
+| `client_local_date` | `Date` | Date in client timezone |
+| `is_purchase` | `UInt8` | `1` if checkout complete event |
+| `is_cart_add` | `UInt8` | `1` if cart add event |
+| `is_first_session` | `UInt8` | `1` if first session for this user |
+| `landing_page_url` | `String` | Landing page URL |
 | `features` | Map(String, String) | Feature flag assignments |
 | `feature_keys` | Map(String, String) | Feature key assignments |
-| `event_meta` | String | Event metadata |
+| `event_meta` | `String` | Event metadata |
 
 ### Dimension columns (auto-joined)
 
@@ -62,37 +62,39 @@ These columns are joined automatically when referenced — no `JOIN` syntax need
 
 | Column | Source | Description |
 |---|---|---|
-| `variant_type` | dim_variant | `Control`, `Variant`, or `Unknown` |
-| `ab_feature_name` | dim_variant | A/B feature name |
-| `ab_feature_value` | dim_variant | A/B feature value |
-| `device_category` | dim_device | Device category |
-| `browser_name` | dim_device | Browser name |
-| `browser_version` | dim_device | Browser version |
-| `os_name` | dim_device | Operating system name |
-| `os_version` | dim_device | Operating system version |
-| `platform` | dim_device | Platform |
-| `country_code` | dim_geo | ISO country code |
-| `country_name` | dim_geo | Country name |
-| `region` | dim_geo | Region |
-| `city` | dim_geo | City |
-| `utm_source` | dim_utm | UTM source |
-| `utm_medium` | dim_utm | UTM medium |
-| `utm_campaign` | dim_utm | UTM campaign |
-| `utm_term` | dim_utm | UTM term |
-| `utm_content` | dim_utm | UTM content |
-| `product_name` | dim_product | Product name |
-| `product_category` | dim_product | Product category |
-| `product_page` | dim_product | Product page |
-| `step_title` | steps | Step title (joined on `project_id` + `experience_id` + `step_id`) |
-| `experience_title` | experiences | Experience title (joined on `project_id` + `experience_id`) |
-| `project_name` | projects | Project name |
-| `project_timezone` | projects | Project timezone |
+| `variant_type` | `dim_variant` | `Control`, `Variant`, or `Unknown` |
+| `ab_feature_name` | `dim_variant` | A/B feature name |
+| `ab_feature_value` | `dim_variant` | A/B feature value |
+| `device_category` | `dim_device` | Device category |
+| `browser_name` | `dim_device` | Browser name |
+| `browser_version` | `dim_device` | Browser version |
+| `os_name` | `dim_device` | The name of the operating system |
+| `os_version` | `dim_device` | The version of the operating system |
+| `platform` | `dim_device` | Platform |
+| `country_code` | `dim_geo` | ISO country code |
+| `country_name` | `dim_geo` | Country name |
+| `region` | `dim_geo` | Region |
+| `city` | `dim_geo` | City |
+| `utm_source` | `dim_utm` | UTM source |
+| `utm_medium` | `dim_utm` | UTM medium |
+| `utm_campaign` | `dim_utm` | UTM campaign |
+| `utm_term` | `dim_utm` | UTM term |
+| `utm_content` | `dim_utm` | UTM content |
+| `product_name` | `dim_product` | Product name |
+| `product_category` | `dim_product` | Product category |
+| `product_page` | `dim_product` | Product page |
+| `step_title` | `steps` | Step title (joined on `project_id` + `experience_id` + `step_id`) |
+| `experience_title` | `experiences` | Experience title (joined on `project_id` + `experience_id`) |
+| `project_name` | `projects` | Project name |
+| `project_timezone` | `projects` | Project timezone |
 
 ## `steps`, `experiences`, `projects`
 
-Reference tables describing your Picked configuration. Auto-joined onto `events` when their analyst-facing columns are referenced; require a per-table tenant filter when queried directly.
+These reference tables hold the options of your Picked project. PickedQL joins them
+onto `events` when you point at one of their analyst-facing columns. Each one needs
+its own tenant filter when you read it directly.
 
-| Source | Real Columns | Analyst Columns (when referenced from `events`) | Tenant filter (when queried directly) |
+| Source | Real columns | Analyst columns, when you point at them from `events` | Tenant filter, when you read the table directly |
 |---|---|---|---|
 | `steps` | `id`, `title`, `experience_id`, `project_id`, `organization_id` | `step_title` | `project_id = '…'` |
 | `experiences` | `id`, `title`, `project_id`, `organization_id` | `experience_title` | `project_id = '…'` |
@@ -116,7 +118,9 @@ GROUP BY experience_title, step_title
 
 ## `features`
 
-The `features` table provides [parameterized virtual functions](./virtual-functions#feature-functions-features--events) for querying feature flag assignments:
+The `features` table gives you
+[parameterized virtual functions](./virtual-functions#feature-functions-on-features-and-on-events).
+Use them to read which visitors each feature flag holds:
 
 | Function | Description |
 |---|---|
@@ -126,31 +130,36 @@ The `features` table provides [parameterized virtual functions](./virtual-functi
 
 ## `experience_journey`
 
-Aggregated step-transition edges for sankey / funnel charts. Parameters are supplied via the outer `WHERE` clause (PickedQL extracts them and substitutes into the underlying scaffold).
+This table gives one edge for each step transition, and PickedQL aggregates them
+first. Use the edges in a sankey chart or a funnel chart. Give each parameter in the
+outer `WHERE` clause. PickedQL reads them and puts them into the query below.
 
 ### Columns
 
 | Column | Type | Description |
 |---|---|---|
-| `source` | String | Edge start, formatted as `NN. <step title>` (e.g., `001. Welcome screen`) |
-| `target` | String | Edge end, formatted as `NN. <step title>`. 
-| `users` | UInt64 | Distinct `user_canonical_id` count that traversed this edge. |
+| `source` | `String` | Edge start, formatted as `NN. <step title>` (for example `001. Welcome screen`) |
+| `target` | `String` | Edge end, formatted as `NN. <step title>`. 
+| `users` | `UInt64` | Distinct `user_canonical_id` count that traversed this edge. |
 
-### Parameters (via `WHERE`)
+### Parameters, in the `WHERE` clause
 
 | Key | Type | Required | Purpose |
 |---|---|---|---|
-| `project_id` | String | ✓ | Tenant filter. |
-| `experience_id` | String |  | Restrict to one `fact_events.experience_id`. |
-| `starting_step` | String |  | Anchor edges at first occurrence of this `step_id`. Defaults to each user's first step. |
-| `targeting_step` | String |  | Trim each user's window at their first occurrence of this `step_id`. Non-reachers still contribute their pre-cut journey. |
-| `num_nodes_after_start` | Integer |  | Forward window from start: keep steps where `seq_pos < start_seq + N` (card 4129 semantics). |
-| `num_nodes_before_target` | Integer |  | Backward window from target: keep steps where `seq_pos >= target_seq - N` (card 2740 semantics). Requires `targeting_step`. |
-| `top_n_path` | Integer |  | Keep only the top-N most-walked paths by user count. Defaults to no limit. |
-| `user_cohort_event` | String |  | Restrict to users who have at least one `fact_events` row with this `event_type`. Implemented as `user_canonical_id IN (SELECT DISTINCT user_canonical_id FROM fact_events WHERE event_type = '…')`. |
-| `client_local_date` | Date |  | Date range filter, pushed into the underlying scan. Supports `=`, `<`, `<=`, `>`, `>=`, `BETWEEN`. |
-| `event_timestamp` | DateTime64 |  | Server-side timestamp filter. Same operators as `client_local_date`. |
-
-When both window params are set, both predicates apply (intersection). Date filters combine via `AND` with the other params.
-
-See [data sources → experience_journey](./data-sources#experience_journey--sankey-ready-step-transitions) for usage examples.
+| `project_id` | `String` | ✓ | The tenant filter. |
+| `experience_id` | `String` |  | Limits the rows to one `fact_events.experience_id`. |
+| `starting_step` | `String` |  | Anchors each edge at the first time that a user reaches this `step_id`. The default is the first step of each user. |
+| `targeting_step` | `String` |  | Trims the window of each user at the first time that the user reaches this `step_id`. A user who never reaches it still gives the journey up to that point. |
+| `num_nodes_after_start` | Integer |  | The forward window from the start. It keeps a step where `seq_pos < start_seq + N`. This is what card 4129 does. |
+| `num_nodes_before_target` | Integer |  | The backward window from the target. It keeps a step where `seq_pos >= target_seq - N`. This is what card 2740 does. It needs `targeting_step`. |
+| `top_n_path` | Integer |  | Keeps the paths that the most users take, and drops the rest. The default is no limit. |
+| `user_cohort_event` | `String` |  | Limits the rows to a user with at least one `fact_events` row of this `event_type`. PickedQL writes it as `user_canonical_id IN (SELECT DISTINCT user_canonical_id FROM fact_events WHERE event_type = '…')`. |
+| `client_local_date` | `Date` |  | A filter on a range of dates. PickedQL puts it into the read below. It takes `=`, `<`, `<=`, `>`, `>=`, and `BETWEEN`. |
+| `event_timestamp` | `DateTime64` |  | A filter on the timestamp from the server. It takes the same operators as `client_local_date`. |
+
+When you set both window parameters, both tests apply, and the result is their
+intersection. A date filter joins the other parameters with `AND`.
+
+See
+[data sources, `experience_journey`](./data-sources#experience_journey--step-transitions-for-a-sankey-chart)
+for examples.