@picked/client 0.0.1-dev.1789541668638 → 0.0.1-next.2

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

@@ -1,172 +0,0 @@
----
-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)

package/dist/docs/reference/pickedql/virtual-functions.md

@@ -1,248 +0,0 @@
----
-type: reference
-layout: docs
----
-
-# Virtual functions
-
-A virtual function is a short form of an aggregate expression. Each one is
-**table-aware**. The same function expands one way on `metrics`, where PickedQL
-aggregates the data first. It expands another way on `events`, where there is one row
-for each user.
-
-## A/B test metrics
-
-| Function | Description |
-|---|---|
-| `control_users([condition])` | The different users in the Control group. A condition of your own can narrow them. |
-| `variant_users([condition])` | The different users in the Variant group. A condition of your own can narrow them. |
-| `all_users()` | Every different user |
-| `control_sessions([condition])` | The different sessions in the Control group. A condition of your own can narrow them. |
-| `variant_sessions([condition])` | The different sessions in the Variant group. A condition of your own can narrow them. |
-| `all_sessions()` | Every different session |
-
-### Your own filters on `events`
-
-On the `events` table, each `control_*` function and each `variant_*` function takes
-**one optional filter argument**. The filter counts only a user or a session that
-matches your expression. It applies together with the `variant_type` filter that
-PickedQL adds. Give the argument in the first place, or by the name `filter=`.
-
-The filter uses the same `column=value` syntax as a conversion-rate condition. It
-takes the `AND` and `OR` operators, and parentheses can hold a set of terms.
-
-```sql
--- The default: every Control user.
-SELECT control_users() FROM events
-
--- Your own filter, in the first place.
-SELECT control_users('event_type=app_initialize') FROM events
-SELECT variant_users('event_type=app_initialize AND step_id=xxx') FROM events
-
--- The AND and OR operators, with parentheses.
-SELECT control_users('event_type=app_initialize OR event_type=app_load') FROM events
-SELECT control_users('event_type=form_submit AND (step_id=lead-capture OR step_id=xxx)') FROM events
-
--- Sessions
-SELECT control_sessions('event_type=step_enter') FROM events
-SELECT variant_sessions('event_type=step_enter AND step_id=checkout') FROM events
-
--- Named form
-SELECT control_users(filter='event_type=app_initialize AND step_id=xxx') FROM events
-```
-
-:::note
-A filter of your own is **not supported on `metrics`**, because PickedQL aggregates
-that data first. On `metrics` these functions ignore every argument. They use the
-default Control filter and Variant filter only.
-:::
-
-## Conversion metrics
-
-| Function | Description |
-|---|---|
-| `all_purchase_users()` | Users who completed a purchase |
-| `control_purchase_users()` | Control users who purchased (`metrics` only) |
-| `variant_purchase_users()` | Variant users who purchased (`metrics` only) |
-| `all_purchase_sessions()` | Sessions with a purchase (`metrics` only) |
-| `all_purchase_orders()` | Unique order count (`metrics` only) |
-| `all_cart_add_users()` | Users who added to cart |
-
-## Conversion rates
-
-| Function | Description |
-|---|---|
-| `control_conversion_rate([numerator [, denominator]])` | The conversion rate of the Control group. By default it divides the users with a purchase by all users. |
-| `variant_conversion_rate([numerator [, denominator]])` | The conversion rate of the Variant group. It takes the same arguments. |
-| `conversion_rate_uplift([numerator [, denominator]])` | The gain of the Variant over the Control: `(variant CR - control CR) / control CR`. It takes the same arguments. |
-
-### Your own conditions on `events`
-
-On the `events` table, each conversion-rate function takes up to **two optional
-arguments**. They set the numerator and the denominator. Each argument is either a
-**condition expression string** or a **nested virtual function call**. See below.
-Give the arguments in order, or by the names `numerator=` and `denominator=`.
-
-Each condition expression uses `column=value`, with the `AND` and `OR` operators.
-Parentheses can hold a set of terms.
-
-```sql
--- Default: purchase users / all users
-SELECT control_conversion_rate() FROM events
-
--- Custom numerator, default denominator (all users)
-SELECT control_conversion_rate('event_type=form_submit_success') FROM events
-
--- The AND and OR operators in a condition.
-SELECT control_conversion_rate('event_type=checkout_complete OR event_type=order_create') FROM events
-SELECT control_conversion_rate('step_id=lead-capture AND event_type=form_submit_success') FROM events
-
--- Parentheses hold a set of terms.
-SELECT control_conversion_rate('event_type=form_submit AND (step_id=lead-capture OR step_id=xxx)') FROM events
-
--- Custom numerator AND denominator (positional)
-SELECT control_conversion_rate('event_type=form_submit', 'step_id=lead-capture') FROM events
-
--- Named arguments (explicit, any order)
-SELECT control_conversion_rate(numerator='event_type=form_submit', denominator='step_id=lead-capture') FROM events
-
--- Named: denominator only (numerator defaults to purchase)
-SELECT control_conversion_rate(denominator='step_id=lead-capture') FROM events
-
--- The uplift, with the arguments given by name.
-SELECT conversion_rate_uplift(numerator='event_type=form_submit', denominator='step_id=lead-capture') FROM events
-```
-
-#### A nested virtual function as the numerator or the denominator
-
-You can pass a **virtual function call** as the numerator or the denominator, in
-place of a condition string. PickedQL puts the inner aggregate there directly. It
-adds no `variant_type` filter above it, because the nested function sets its own
-filter.
-
-This form is the most flexible one when the numerator and the denominator come from
-different segments. An example is the Control users who fired one event, over **all**
-users of every variant:
-
-```sql
--- The Control users who fired `app_initialize`, over all users.
-SELECT control_conversion_rate(
-  control_users('event_type=app_initialize'),
-  all_users()
-) FROM events
-
--- Mix string and nested forms
-SELECT control_conversion_rate(
-  'event_type=form_submit',
-  all_users()
-) FROM events
-
--- The uplift, with a nested function in each place.
-SELECT conversion_rate_uplift(
-  control_users('event_type=app_initialize'),
-  all_users()
-) FROM events
-```
-
-:::note
-A condition of your own, and a nested virtual function, are both **not supported on
-`metrics`**, because PickedQL aggregates that data first. On `metrics` these
-functions always divide the users with a purchase by all users.
-:::
-
-## Visitor segmentation (`metrics` only)
-
-| Function | Description |
-|---|---|
-| `new_users()` | First-time visitors |
-| `returning_users()` | Returning visitors |
-| `new_sessions()` | Sessions from new visitors |
-| `returning_sessions()` | Sessions from returning visitors |
-
-## Funnel metrics (`events` only)
-
-:::note
-We add to the funnel metrics all the time. Read this page again for a new function.
-:::
-
-| Function | Description |
-|---|---|
-| `step_enter_users()` | Users who entered a funnel step |
-| `step_enter_sessions()` | Sessions that entered a funnel step |
-
-## Cohort filters (`events` only)
-
-Each of these functions has the shape of a predicate. It writes a
-`user_canonical_id IN (SELECT … FROM events …)` subquery. Put one in a `WHERE` clause
-to limit any analysis to a user with at least one event that matches a condition of
-your own.
-
-| Function | Description |
-|---|---|
-| `user_cohort_filter('<condition>')` | Limits the query to a user with one or more `events` rows that match `<condition>` |
-| `user_cohort_filter(filter='<condition>')` | The same, with the argument given by name |
-
-`<condition>` uses the same short `column=value [AND\|OR …]` form as `control_users`
-and `variant_users`.
-
-```sql
--- Funnel scoped to users who eventually submitted lead capture
-SELECT all_users(), all_purchase_users()
-FROM events
-WHERE project_id = 'proj-abc'
-  AND user_cohort_filter('event_type=lead_capture')
-
--- Multi-condition cohort with OR-grouping
-SELECT all_sessions()
-FROM events
-WHERE project_id = 'proj-abc'
-  AND user_cohort_filter('event_type=signup OR event_type=trial_start')
-```
-
-The outer query MUST hold one `project_id` filter. The function puts that tenant into
-the inner subquery. The read of the cohort therefore covers your project, and not the
-whole warehouse.
-
-## Feature functions, on `features` and on `events`
-
-Parameterized functions that accept the feature name, bucket, and an optional feature key:
-
-| 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 |
-
-The bucket is what the SDK sent to the site of the visitor. A Boolean feature flag gives
-`'true'` or `'false'`. A Text feature flag gives the value of one variant, or `'false'` for
-the control group. The key is the version of the feature flag, such as `'v1'`.
-
-```sql
--- Compare the two buckets of a Boolean feature flag.
-SELECT
-  feature_users('homepage_test', 'false') AS control,
-  feature_users('homepage_test', 'true') AS variant
-FROM features
-
--- Compare the variants of a Text feature flag.
-SELECT
-  feature_users('hero', 'false') AS control,
-  feature_users('hero', 'hero-a') AS hero_a,
-  feature_users('hero', 'hero-b') AS hero_b
-FROM features
-
--- Count one version of the feature flag alone.
-SELECT feature_users('homepage_test', 'false', 'v1') FROM features
-```
-
-## Other (`metrics` only)
-
-| Function | Description |
-|---|---|
-| `event_count()` | Total event count (from pre-aggregation) |
-
-## Related
-
-- [Filters](/reference/pickedql/filtering) — the filter string a function takes.
-- [Analytics queries](/how-to/analytics)
-- [About PickedQL](/explanation/how-pickedql-works)

package/dist/docs/reference/sdk/actions.md

@@ -1,30 +0,0 @@
----
-type: reference
-layout: docs
----
-
-# Actions
-
-Register an action handler on the Picked client. The SDK then invokes the handler
-when an experience flow reaches an action node.
-
-## Outcome and branch
-
-| Handler outcome | Branch the flow takes |
-| --- | --- |
-| Throws, or its promise rejects | `onFail` |
-| Resolves to any value, and that includes `false` | `onSuccess` |
-
-An action node can also carry one plain connection, with no success or failure branch. The
-flow then continues through it on either outcome.
-
-An action does not interrupt your visitor. The current step stays on the screen while an
-async action runs.
-
-## Related
-
-- [How to register an action handler](/how-to/register-an-action-handler) — the handler,
-  and when to throw.
-- [About how Picked works](/explanation/how-picked-works#how-an-action-decides-which-way-to-go)
-  — why a returned `false` is a success.
-- [Actions](/reference/dashboard/actions) — the dashboard options.