@picked/client 0.0.1-dev.1785305085063 → 0.0.1-dev.1785908062293

package/dist/docs/reference/pickedql/data-sources.md

@@ -0,0 +1,174 @@
+---
+type: reference
+layout: docs
+---
+
+# Data sources
+
+PickedQL gives you four virtual tables. Each table is fast for one kind of work. It also gives you three reference tables, and those hold the options of your
+Picked project.
+
+## `metrics` — data that PickedQL aggregates each day
+
+Use it for a dashboard and to study a trend. There is one row for each unique set of
+dimensions on each day. The dimension columns are there directly, and they need no
+join. Examples are `device_category`, `country_code`, and `utm_source`.
+
+```sql
+SELECT device_category, control_users(), variant_users()
+FROM metrics
+WHERE project_id = 'your-project-id'
+GROUP BY device_category
+```
+
+## `events` — one row for each event of each user
+
+Use it for a deep study, for a funnel, and for a breakdown of your own. There is one
+row for each event of each user. PickedQL joins a dimension column, such as
+`device_category` or `country_code`, when you point at it.
+
+```sql
+SELECT user_canonical_id, device_category
+FROM events
+WHERE project_id = 'your-project-id'
+  AND variant_type = 'Control'
+```
+
+## `features` — one row for each feature flag
+
+Use it to count the users, the sessions, and the events for each feature flag and
+bucket. It uses parameterized functions.
+
+```sql
+SELECT feature_users('homepage_test', 'control')
+FROM features
+WHERE project_id = 'your-project-id'
+```
+
+## `experience_journey` — step transitions for a sankey chart
+
+It returns one `source, target, users` row for each edge. You can put those rows
+directly into a sankey chart or a funnel chart. It holds the eight common table
+expressions that a card carried before. Those call `lagInFrame`, remove a duplicate
+between two steps that follow each other, and rank the top paths.
+
+Every filter goes in the **outer `WHERE`** clause. PickedQL reads each one as a
+parameter and puts it into the query below. Only `project_id` is necessary. The rest
+are optional, and each has a sensible default.
+
+| Parameter, as a WHERE key | What it does |
+|---|---|
+| `project_id` | The tenant filter. It is necessary. |
+| `experience_id` | Limits the rows to one `fact_events.experience_id`. |
+| `starting_step` | Anchors each edge at the first time that a user reaches this `step_id`. With no value, it anchors at the first `step_enter` event of that user. |
+| `targeting_step` | 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 a journey, up to `num_nodes_after_start`. |
+| `num_nodes_after_start` | The size of the forward window from the start step. |
+| `num_nodes_before_target` | The size of the backward window from the target step. It needs `targeting_step`. |
+| `top_n_path` | Keeps the paths with the most users, and drops the rest. |
+| `user_cohort_event` | Limits the rows to a user with at least one `fact_events` row of this `event_type`, such as `'lead_capture'`. Use it for the paths of the users who reached a goal. |
+| `client_local_date` | A filter on the date. It takes `=`, `<`, `<=`, `>`, `>=`, and `BETWEEN`. PickedQL puts it into the `fact_events` read below. |
+| `event_timestamp` | A filter on the timestamp from the server. It takes the same operators as `client_local_date`. |
+
+When you set both `num_nodes_after_start` and `num_nodes_before_target`, both tests
+apply. The result is the intersection of the two.
+
+```sql
+-- The "overall user journey" sankey.
+-- It uses a forward window. The target step is optional.
+SELECT source, target, users FROM experience_journey
+WHERE project_id           = 'your-project-id'
+  AND starting_step        = 'step-start'
+  AND targeting_step       = 'step-target'
+  AND num_nodes_after_start = 10
+  AND client_local_date   >= '2026-04-01'    -- An optional range of dates.
+  AND client_local_date   <= '2026-04-30'
+```
+
+```sql
+-- The "paths to a target" sankey.
+-- It uses a backward window and it ranks the top paths.
+SELECT source, target, users FROM experience_journey
+WHERE project_id             = 'your-project-id'
+  AND experience_id          = 'exp-123'
+  AND starting_step          = 'step-start'
+  AND targeting_step         = 'step-target'
+  AND num_nodes_before_target = 5
+  AND top_n_path             = 10
+```
+
+```sql
+-- The "drop-off" sankey. Leave the target step out.
+SELECT source, target, users FROM experience_journey
+WHERE project_id           = 'your-project-id'
+  AND experience_id        = 'exp-123'
+  AND starting_step        = 'step-start'
+  AND num_nodes_after_start = 10
+```
+
+```sql
+-- A cohort sankey. It holds the users who reached the goal only.
+SELECT source, target, users FROM experience_journey
+WHERE project_id           = 'your-project-id'
+  AND starting_step        = 'step-start'
+  AND targeting_step       = 'step-target'
+  AND num_nodes_after_start = 10
+  AND user_cohort_event    = 'lead_capture'   -- Users with one or more of these events.
+```
+
+The columns that it returns:
+
+| Column | Type | Description |
+|---|---|---|
+| `source` | String | The start of the edge, in the form `NN. <step title>`, such as `001. Welcome screen`. PickedQL joins `steps` to find the title. |
+| `target` | String | The end of the edge, in the form `NN. <step title>`. |
+| `users` | `UInt64` | The number of different `user_canonical_id` values that went along this edge. |
+
+:::note
+`experience_journey` returns data that PickedQL aggregates first. It does **not**
+support a dimension filter such as `variant_type`, `device_category`, or
+`country_code`. To use one of those, query
+[`events`](#events--one-row-for-each-event-of-each-user) directly and build the
+transitions yourself.
+:::
+
+## Reference tables — `steps`, `experiences`, `projects`
+
+These reference tables hold the configuration of your Picked project. They have two uses:
+
+- **PickedQL joins them onto `events`** when you point at one of their analyst
+  columns: `step_title`, `experience_title`, `project_name`, or `project_timezone`.
+- **You can read them directly.** Each one then needs its own tenant filter, so that
+  you see only the rows of a project that you can reach.
+
+| Source | The tenant filter that it needs |
+|---|---|
+| `steps` | `WHERE project_id = '<project_id>'` |
+| `experiences` | `WHERE project_id = '<project_id>'` |
+| `projects` | `WHERE id = '<project_id>'` |
+
+```sql
+-- A direct query that reads the experiences of a project.
+SELECT id, title FROM experiences WHERE project_id = 'your-project-id'
+
+-- A direct query that reads the metadata of one project.
+SELECT id, name, timezone FROM projects WHERE id = 'your-project-id'
+```
+
+```sql
+-- Pointed at from events. PickedQL adds each LEFT JOIN for you.
+-- The reference tables need no separate tenant filter, because
+-- the event table already limits the join.
+SELECT experience_title, step_title, count(*)
+FROM events
+WHERE project_id = 'your-project-id'
+GROUP BY experience_title, step_title
+```
+
+See [Schema, reference tables](/reference/pickedql/schema#steps-experiences-projects) for the full
+column list and the join keys.
+
+## Related
+
+- [About PickedQL](/explanation/how-pickedql-works) — what the layer expands for you.
+- [Schema](/reference/pickedql/schema)
+- [Analytics queries](/how-to/analytics)

package/dist/docs/reference/pickedql/dimensions.md

@@ -0,0 +1,87 @@
+---
+type: reference
+layout: docs
+---
+
+# Dimension columns
+
+Every data source has dimension columns. The `metrics` table holds them directly. On
+`events` and on `features`, PickedQL adds the `LEFT JOIN` that it needs when you
+point at one. You write no join.
+
+## The dimensions
+
+| Source | Columns |
+|---|---|
+| `dim_variant` | `variant_type`, `ab_feature_name`, `ab_feature_value` |
+| `dim_device` | `device_category`, `browser_name`, `browser_version`, `os_name`, `os_version`, `platform` |
+| `dim_geo` | `country_code`, `country_name`, `region`, `city` |
+| `dim_utm` | `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content` |
+| `dim_product` | `product_name`, `product_category`, `product_page` |
+| `steps` | `step_title` |
+| `experiences` | `experience_title` |
+| `projects` | `project_name`, `project_timezone` |
+
+The `steps`, `experiences`, and `projects` sources are reference tables, and they come
+from the operational database. PickedQL joins them onto `events` and `fact_events`
+when you point at one of their analyst-facing columns. Each one **also** needs its own
+tenant filter when you query it directly:
+
+| Source | The tenant filter that it needs |
+|---|---|
+| `steps`, `experiences` | `WHERE project_id = '<project_id>'` |
+| `projects` | `WHERE id = '<project_id>'`, because the `id` of the row is the project ID |
+
+PickedQL also puts a tenant equality in the `ON` clause of each join that it adds.
+Examples are `AND st.project_id = '<project_id>'` and `AND pr.id = '<project_id>'`.
+ClickHouse then reads part of the dimension table and not all of it. PickedQL puts
+the test in `ON` and not in `WHERE`, because a test in `WHERE` would change a
+`LEFT JOIN` into an inner join.
+
+Each analyst-facing column name carries a prefix, such as `step_title` and
+`project_name`. The prefix stops a collision between two sources. Both `steps.title`
+and `experiences.title` are there, and you point at them as `step_title` and
+`experience_title`.
+
+```sql
+-- Group the events by experience and by step name.
+-- PickedQL joins both `experiences` and `steps` for you.
+SELECT experience_title, step_title, count(*)
+FROM events
+WHERE project_id = 'your-project-id'
+GROUP BY experience_title, step_title
+```
+
+An automatic join also works inside a subquery and inside a common table expression.
+Point at a dimension column where you need it, and PickedQL adds the `LEFT JOIN` at
+that level:
+
+```sql
+-- Dimension columns inside a common table expression.
+WITH per_step AS (
+  SELECT step_title, count(*) AS n
+  FROM events
+  WHERE project_id = 'your-project-id'
+  GROUP BY step_title
+)
+SELECT * FROM per_step ORDER BY n DESC
+
+-- Dimension columns inside a nested query.
+SELECT step_title, n FROM (
+  SELECT step_title, count(*) AS n FROM events
+  WHERE project_id = 'your-project-id'
+  GROUP BY step_title
+) sub
+```
+
+## Native event columns
+
+These columns are on `events` directly, and they need no join:
+
+`event_type`, `interaction_type`, `experience_id`, `step_id`, `event_id`, `user_canonical_id`, `session_id`, `client_local_date`, `is_purchase`, `is_cart_add`, `event_meta`.
+
+## Related
+
+- [About PickedQL](/explanation/how-pickedql-works) — why you write no join.
+- [Data sources](/reference/pickedql/data-sources)
+- [Analytics queries](/how-to/analytics)

package/dist/docs/{pickedql → reference/pickedql}/filtering.md

@@ -1,18 +1,21 @@
 ---
+type: reference
 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 +33,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 |
 |---|---|
@@ -51,3 +56,9 @@ SELECT id, name, timezone FROM projects WHERE id = 'your-project-id'
 ```
 
 The small lookup tables (`dim_variant`, `dim_device`, `dim_geo`, `dim_utm`, `dim_product`) are still exempt — they contain no tenant data.
+
+## Related
+
+- [Virtual functions](/reference/pickedql/virtual-functions) — the functions that take a
+  filter.
+- [Analytics queries](/how-to/analytics)

package/dist/docs/reference/pickedql/index.md

@@ -0,0 +1,18 @@
+---
+type: reference
+layout: docs
+---
+
+# PickedQL
+
+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.
+
+## Related
+
+- [About PickedQL](/explanation/how-pickedql-works) — what the layer expands, and why a
+  tenant filter is required.
+- [Analytics queries](/how-to/analytics) — worked examples.
+- [Data sources](/reference/pickedql/data-sources) — every table.
+- [Filters](/reference/pickedql/filtering) — the filter string a virtual function takes.

package/dist/docs/reference/pickedql/schema.md

@@ -0,0 +1,172 @@
+---
+type: reference
+layout: docs
+---
+
+# Schema
+
+Column reference for each PickedQL data source.
+
+## `metrics`
+
+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 (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`, and so on) are not queried directly — use [virtual functions](/reference/pickedql/virtual-functions) instead.
+:::
+
+## `events`
+
+User-level event data. One row per event per user. Dimension columns are joined automatically when referenced.
+
+### Native columns
+
+| 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 (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 |
+
+### Dimension columns (auto-joined)
+
+These columns are joined automatically when referenced — no `JOIN` syntax needed.
+
+| 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` | 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`
+
+These reference tables hold the configuration 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 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 = '…'` |
+| `projects` | `id`, `name`, `timezone`, `organization_id` | `project_name`, `project_timezone` | `id = '<project_id>'` |
+
+When queried directly, use the real column names:
+
+```sql
+-- List all experiences for a project
+SELECT id, title FROM experiences WHERE project_id = 'your-project-id'
+```
+
+When referenced from `events`, use the prefixed analyst names — joins are injected automatically:
+
+```sql
+SELECT experience_title, step_title, count(*)
+FROM events
+WHERE project_id = 'your-project-id'
+GROUP BY experience_title, step_title
+```
+
+## `features`
+
+The `features` table gives you
+[parameterized virtual functions](/reference/pickedql/virtual-functions#feature-functions-on-features-and-on-events).
+Use them to read which visitors each feature flag holds:
+
+| Function | Description |
+|---|---|
+| `feature_users('name', 'bucket' [, 'key'])` | Unique users in a feature bucket |
+| `feature_sessions('name', 'bucket' [, 'key'])` | Unique sessions in a feature bucket |
+| `feature_events('name', 'bucket' [, 'key'])` | Unique events in a feature bucket |
+
+## `experience_journey`
+
+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>` (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, in the `WHERE` clause
+
+| Key | Type | Required | Purpose |
+|---|---|---|---|
+| `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`. |
+| `num_nodes_before_target` | Integer |  | The backward window from the target. It keeps a step where `seq_pos >= target_seq - N`. 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`](/reference/pickedql/data-sources#experience_journey--step-transitions-for-a-sankey-chart)
+for examples.
+
+## Related
+
+- [Data sources](/reference/pickedql/data-sources)
+- [Dimensions](/reference/pickedql/dimensions)
+- [About PickedQL](/explanation/how-pickedql-works)