@thinkingai/ae-cli 6.1.23 → 6.1.25

package/skills/ae-analysis/references/user_cluster_models.md

@@ -16,6 +16,12 @@ If a SQL cluster reads an event table, include a predicate on the quoted `"$part
 SQL clusters support only `${PartDate:name}` dynamic placeholders. Each placeholder requires a matching `params` item with `type=part_date` and either `recent_day` or `start_time` plus `end_time`. General SQL parameter types (`text`, `number`, `variable`, `time`, and `selector`) are rejected for SQL clusters.
 For `recent_day`, `0-7` means 最近7天 and includes today; `1-7` means 过去7天 and excludes today.
 
+`${base_date}` is a separate built-in computation-date macro, not a user-configurable dynamic placeholder. SQL clusters may use `${base_date}`, a formatted value such as `${base_date:yyyy-MM-dd}`, or a server-supported offset such as `${base_date:yyyy-MM-dd-1*day}`. Keep the macro in `sql` and do not add it to `params`; it is expanded when the cluster is calculated. Expansion produces plain text, so quote the macro when the SQL expression expects a string or date literal:
+
+```json
+{"type":"sql","sql":"SELECT \"#user_id\" FROM v_event_1 WHERE \"$part_date\"='${base_date:yyyy-MM-dd}'"}
+```
+
 Discover tables with `analysis sql-table list --project-id <project_id> --usage tag_cluster`, then inspect columns with the same `--usage tag_cluster`. This table set is server-authorized specifically for SQL tags/clusters and differs from the default analysis SQL set.
 
 Optional `include_filter` and `exclude_filter` use the shared filter-group shape.
@@ -87,3 +93,5 @@ Required: `type=behavior_sequence`, `completed`, `steps`. Each step requires `ev
   ]}
 }
 ```
+
+For space tables, use the returned `sql_reference` when writing SQL and loading columns. `source_type=gaia` identifies a space table; keep `--usage tag_cluster` for both discovery commands.

package/skills/ae-analysis/references/user_tag_create.md

@@ -10,7 +10,7 @@ Flags: `--project-id`, `--tag-name`, `--display-name`, `--definition-request` re
 
 `tag_name` is a machine identifier: 1-80 characters, starts with a letter, and contains only letters, digits, or underscores. `display_name` is 1-80 characters. The CLI rejects violations before dispatch.
 
-Read `user_tag_models.md` before constructing `--definition-request`. Dynamic first/last ranges use semantic `time_range` values such as `{"mode":"recent","unit":"month","value":1}` for this month or `{"mode":"start_to_today","start_time":"2026-07-01"}` for a fixed start date through today. Create does not accept `--remark`; set it later with `user-tag update` when needed.
+Read `user_tag_models.md` before constructing `--definition-request`. Every metric tag requires `metric.time_range`; never omit it. Dynamic first/last ranges use semantic `time_range` values such as `{"mode":"recent","unit":"month","value":1}` for this month or `{"mode":"start_to_today","start_time":"2026-07-01"}` for a fixed start date through today. Create does not accept `--remark`; set it later with `user-tag update` when needed.
 
 The backend validates and compiles the definition inside the create operation; if metadata is ambiguous or missing, creation fails without creating the tag.
 
@@ -18,6 +18,12 @@ The backend validates and compiles the definition inside the create operation; i
 ae-cli analysis user-tag create --project-id <project_id> --tag-name high_value --display-name "High Value" --definition-request '{"type":"condition","condition_values":[{"value":"high","events":[{"event":"pay","operator":"gte","value":3,"aggregation":"count","time_range":{"mode":"recent","unit":"day","value":30}}]}]}'
 ```
 
+Median metric tag for the previous 30 days:
+
+```bash
+ae-cli analysis user-tag create --project-id <project_id> --tag-name median_payment --display-name "Median Payment" --definition-request '{"type":"metric","metric":{"event":"pay","aggregation":"median","property":"amount","time_range":{"mode":"previous","unit":"day","value":30}}}'
+```
+
 First/last tag for this month:
 
 ```bash

package/skills/ae-analysis/references/user_tag_get.md

@@ -4,7 +4,7 @@ Get exact user tag details after discovery.
 
 Do not use it for fuzzy discovery, member data, or history statistics. Output contains saved tag metadata/definition for the requested names.
 
-After `user-tag create` or an update containing `--definition-request`, use this command to observe the automatically started computation; do not trigger `user-tag refresh`. For create, wait until `progress=100` and `refresh_time` is present. For a definition update, record the previous `refresh_time` first and wait until `progress=100` and `refresh_time` advances. Until then, `users_num` and member queries may still reflect the previous successful computation; treat that as stale data, not as evidence that the new definition was compiled or calculated incorrectly.
+After `user-tag create` or an update reporting `computation.triggered_automatically=true`, use this command to observe the automatically started computation; do not trigger `user-tag refresh`. For create, wait until `progress=100` and `refresh_time` is present. For a changed definition, record the previous `refresh_time` first and wait until `progress=100` and `refresh_time` advances. Until then, `users_num` and member queries may still reflect the previous successful computation; treat that as stale data, not as evidence that the new definition was compiled or calculated incorrectly. An identical definition is not recomputed; when update returns `not_triggered` and `next_action=none`, do not wait for a new refresh timestamp.
 
 The raw backend value is returned under `result`. The response also provides aggregate and per-tag `computation`, `result_freshness`, and `next_action`. `poll_get` includes an exact capability/input pair; `none` means the latest result is usable. `potentially_stale` with `is_stale=null` means `refresh_time` predates `update_time`, but the update may have changed metadata only; inspect the latest update instead of refreshing automatically.
 

package/skills/ae-analysis/references/user_tag_models.md

@@ -24,7 +24,9 @@ Top-level `type` is exactly one of `condition`, `metric`, `first_last`, or `sql`
 
 ## Metric tag
 
-Required: `event`, `aggregation`. `property`, `percentile`, `time_range`, and `filters` are optional. Filters support only event properties and user properties. A string `field` is an event property; use `{name,type:"user_property"}` for a user property.
+Required: `event`, `aggregation`, and `time_range`. `property`, `percentile`, and `filters` are optional. Filters support only event properties and user properties. A string `field` is an event property; use `{name,type:"user_property"}` for a user property. Use the semantic time mappings in [`audience_models.md`](audience_models.md); never omit `time_range` from a metric tag.
+
+Supported aggregations are `count`, `active_days`, `sum`, `avg`, `max`, `min`, `median`, and `percentile`. `median` is a dedicated aggregation for a numeric event `property`; do not represent it as `percentile=50`.
 
 Use `aggregation=percentile` with a numeric event `property` and pass `percentile`. Supported percentile values match the page controls: `5`, `10`, `20`, `25`, `30`, `40`, `60`, `70`, `75`, `80`, `90`, `95`, and `99`. The `percentile` field is required for percentile aggregation and is rejected for every other aggregation.
 
@@ -32,10 +34,16 @@ Use `aggregation=percentile` with a numeric event `property` and pass `percentil
 {"type":"metric","metric":{"event":"pay","aggregation":"sum","property":"amount","time_range":{"mode":"previous","unit":"day","value":30},"filters":{"relation":"and","items":[{"field":"channel","operator":"eq","values":["app"]},{"field":{"name":"country","type":"user_property"},"operator":"eq","values":["US"]}]}}}
 ```
 
+Median example:
+
+```json
+{"type":"metric","metric":{"event":"pay","aggregation":"median","property":"amount","time_range":{"mode":"previous","unit":"day","value":30}}}
+```
+
 Percentile example:
 
 ```json
-{"type":"metric","metric":{"event":"pay","aggregation":"percentile","property":"amount","percentile":90}}
+{"type":"metric","metric":{"event":"pay","aggregation":"percentile","property":"amount","percentile":90,"time_range":{"mode":"previous","unit":"day","value":30}}}
 ```
 
 ## First/last tag
@@ -61,8 +69,16 @@ From a fixed date through today:
 SQL tags support only `${PartDate:name}` dynamic placeholders. Every placeholder requires one `params` item with `type=part_date` and either `recent_day` or `start_time` plus `end_time`. `Text`, `Number`, `Variable`, `Time`, and `Selector` parameters are valid for general SQL analysis but are not valid for SQL tags.
 For `recent_day`, `0-7` means 最近7天 and includes today; `1-7` means 过去7天 and excludes today.
 
+`${base_date}` is a separate built-in computation-date macro, not a user-configurable dynamic placeholder. SQL tags may use `${base_date}`, a formatted value such as `${base_date:yyyy-MM-dd}`, or a server-supported offset such as `${base_date:yyyy-MM-dd-1*day}`. Keep the macro in `sql` and do not add it to `params`; it is expanded when the tag is calculated. Expansion produces plain text, so quote the macro when the SQL expression expects a string or date literal:
+
+```json
+{"type":"sql","sql":"SELECT \"#user_id\", 'payer' AS tag_value FROM hive.ta.v_event_1 WHERE \"$part_date\"='${base_date:yyyy-MM-dd}' AND \"$part_event\"='pay'"}
+```
+
 Before writing a SQL tag, use `analysis sql-table list --project-id <project_id> --usage tag_cluster`, then call `analysis sql-table columns --project-id <project_id> --table-ref <table_ref> --usage tag_cluster`. The `tag_cluster` authorized table set is intentionally different from the general analysis SQL table set; do not reuse a table discovered with the default `usage=analysis`.
 
 `#user_id`, `$part_event`, and any other Trino identifier containing `#`, `$`, `@`, spaces, or punctuation must be delimited with double quotes. Single quotes are only for values.
 
 When the SQL reads an event table, it must also filter the quoted `"$part_date"` date-partition column; the backend rejects event-table SQL without that predicate.
+
+For space tables, use the returned `sql_reference` when writing SQL and loading columns. `source_type=gaia` identifies a space table; keep `--usage tag_cluster` for both discovery commands.

package/skills/ae-analysis/references/user_tag_refresh.md

@@ -2,7 +2,7 @@
 
 Explicitly recompute an existing user tag by exact `tag_name` without changing its definition.
 
-Use this only when an unchanged definition must be run again, such as an explicit retry or a recomputation against changed source data. Do not call it after `user-tag create` or an update containing `--definition-request`; those commands already start computation automatically. Do not use it to refresh one history snapshot. Output means recomputation was submitted, not completed. Poll `user-tag get` and verify the new computation before using `users_num` or querying members.
+Use this only when an unchanged definition must be run again, such as an explicit retry or a recomputation against changed source data. Do not call it after `user-tag create` or an update reporting `computation.triggered_automatically=true`; those commands already start computation. An identical definition update does not trigger computation and does not by itself authorize a separate refresh. Do not use this command to refresh one history snapshot. Output means recomputation was submitted, not completed. Poll `user-tag get` and verify the new computation before using `users_num` or querying members.
 
 The response marks this as an explicit trigger: `computation.triggered_by_command=true`, `computation.triggered_automatically=false`, `computation.status=submitted`, and `result_freshness.is_stale=true`. Follow the returned `next_action`, `next_capability_id`, and `next_input` to poll.
 

package/skills/ae-analysis/references/user_tag_update.md

@@ -2,9 +2,9 @@
 
 Update a user tag. Discover the exact `tag_name` first.
 
-Do not use it for ID-file value replacement or to create a missing tag. Supplying `--definition-request` automatically starts recomputation after the definition is updated; do not call `user-tag refresh` afterward. Updating only `--display-name` or `--remark` does not recompute. A schedule-only update changes periodic refresh without starting immediate recomputation. `--auto-refresh-cron` or `--auto-refresh-schedule` can enable periodic refresh directly, including on a previously disabled tag. A successful update means the definition was saved, not that the new result is complete. Record the current `refresh_time` before updating, then poll `user-tag get` until `progress=100` and `refresh_time` advances before using `users_num` or querying members.
+Do not use it for ID-file value replacement or to create a missing tag. A changed `--definition-request` automatically starts recomputation; the native service skips recomputation when the normalized definition and timezone are unchanged. Follow the returned `computation.triggered_automatically` and `next_action`; do not call `user-tag refresh` afterward. Updating only `--display-name` or `--remark` does not recompute. A schedule-only update changes periodic refresh without starting immediate recomputation. `--auto-refresh-cron` or `--auto-refresh-schedule` can enable periodic refresh directly, including on a previously disabled tag. A successful update means the definition was saved, not that a triggered computation is complete. When computation was triggered, poll `user-tag get` until `progress=100` and `refresh_time` advances from the value recorded before the update. An unchanged definition returns `not_triggered` and `next_action=none`; do not wait for its refresh timestamp to change.
 
-The response distinguishes both paths. A definition update returns `computation.triggered_automatically=true`, `result_freshness.is_stale=true`, and normally `next_action=poll_get` with an exact capability/input pair. A display-name/remark-only update returns `computation.status=not_triggered`, `result_freshness.status=fresh`, and `next_action=none`.
+The response distinguishes both paths. An update that triggers recomputation returns `computation.triggered_automatically=true`, `result_freshness.is_stale=true`, and `next_action=poll_get` with an exact capability/input pair. An unchanged definition or display-name/remark-only update returns `computation.status=not_triggered`, `result_freshness.status=fresh`, and `next_action=none`.
 
 Flags: `--project-id`, `--tag-name` required. Optional: `--display-name`, `--definition-request`, `--authenticated-only`, `--remark`, `--zone-offset`, `--enable-auto-refresh`, `--auto-refresh-schedule`, `--auto-refresh-cron`. The tag type comes from `definition_request.type` when the definition changes.