@thinkingai/ae-cli 6.0.18 → 6.0.22

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

@@ -30,6 +30,8 @@ Domain: **Report Management**
 ```bash
 ae-cli analysis +query_report_data --project_id <project_id> --report_ids '[1001]'
 ae-cli analysis +query_report_data --project_id <project_id> --report_ids '[1001]' --filters '{}' --group_by '[]' --request_id mcp_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa --use_cache true --start_date 2026-04-08 --end_date 2026-04-08 --time_granularity day --timeout_minutes 8
+# SQL-model report: override its dynamic parameters (${Selector}/${Time}/${Text}) by paramName
+ae-cli analysis +query_report_data --project_id <project_id> --report_ids '[1001]' --sql_params '[{"paramName":"selector1","paramExpress":"<selectorName>"},{"paramName":"time2","startTime":"2026-01-01 00:00:00","endTime":"2026-06-30 23:59:59"}]'
 ae-cli analysis +query_report_data --dry-run
 ```
 
@@ -40,26 +42,58 @@ ae-cli analysis +query_report_data --dry-run
 | `--report_ids` | Yes | List of report IDs |
 | `--filters` | No | Optional filter JSON. If provided, MUST follow `+get_filter_schema`, and referenced fields must come from `analysis_meta +list_properties` in the same `project_id`. |
 | `--group_by` | No | Optional group-by JSON array. If provided, MUST follow `+get_groupby_schema`, and referenced fields must come from `analysis_meta +list_properties` in the same `project_id`. |
-| `--request_id` | No | Optional unique request ID used for tracking and cancellation. If provided, it must use `mcp_<32 lowercase hex UUID>`, for example `mcp_0123456789abcdef0123456789abcdef`. For long-running or cancelable queries, provide this before starting the query so it can be cancelled later with `+cancel_query --request_id <same value>`, even if the caller stops waiting before the tool returns. If `fetch failed`, HTTP timeout, or caller timeout happens, the backend query may still be running. The auto-generated requestId is not available when the HTTP request fails before a response, so preset `requestId` is required for proactive cleanup. Generated automatically if omitted. The response `metadata.requestId` can also be passed to `cancel_query` when the query is no longer needed. |
+| `--request_id` | Yes | Required unique request ID used for tracking and cancellation. Generate it before starting the query. It must use `mcp_<32 lowercase hex UUID>`, for example `mcp_0123456789abcdef0123456789abcdef`. Provide this before starting the query so it can be cancelled later with `+cancel_query --request_id <same value>`, even if the caller stops waiting before the tool returns. If `fetch failed`, HTTP timeout, or caller timeout happens, the backend query may still be running. `requestId` is not auto-generated for MCP query tools because the caller must know it before the response for proactive cleanup. If omitted or blank, the backend returns `REQUEST_ID_REQUIRED`; invalid format returns `INVALID_REQUEST_ID`. The response `metadata.requestId` echoes the supplied requestId and can also be passed to `cancel_query(requestId)` when the query is no longer needed. |
 | `--use_cache` | No | Whether to use cache. Default: true |
 | `--start_date` | No | Optional start date in yyyy-MM-dd format |
 | `--end_date` | No | Optional end date in yyyy-MM-dd format |
 | `--time_granularity` | No | Optional time granularity used to override the report default. Supported values: minute, minute5, minute10, hour, day, week, month, quarter, year, total. |
 | `--timeout_minutes` | No | Query timeout in minutes. If the query exceeds this time, it will be cancelled automatically. 30 minutes if omitted. |
+| `--sql_params` | No | Optional override for a SQL-model report's dynamic parameters (the `${...}` placeholders embedded in the report SQL). JSON array of params matched by `paramName`. Only listed params are overridden; omitted params keep the report's saved defaults. Ignored for non-SQL reports. Different from `--filters`: see the SQL report dynamic parameters section below. |
+
+## SQL report dynamic parameters (`--sql_params`)
+- Applies ONLY to SQL-model reports (`reportModel: sql` in `+get_report_definition`). Such reports may embed `${...}` placeholders of 6 paramTypes — `Variable`, `PartDate`, `Time`, `Number`, `Text`, `Selector` — whose default values are saved in the report's `eventView.sqlViewParams`.
+- `--sql_params` overrides those values by `paramName`; the backend merges them into the report's `sqlViewParams` before running the SQL. Omitting `--sql_params` keeps the report defaults (backward compatible).
+- `--sql_params` is NOT the same as `--filters`: `--filters` adds a post-query WHERE filter on the SQL result columns (using real field names), while `--sql_params` changes the report's own dynamic parameters before the SQL runs. To adjust a report's selectors/time parameters, use `--sql_params`, not `--filters`.
+- Workflow: `+get_report_definition` -> read `events.sqlVoParams` (each param's `paramName`, `paramType`, and for Selector the allowed `selectorItems` names) -> build the override array -> `+query_report_data --sql_params '[...]'`.
+- Override shape by `paramType` (read each param's current `quota`/`paramExpress`/`startTime`/`endTime` and the VO's `variableType`/`selectorItems` from `+get_report_definition`):
+  - `Selector` — `{"paramName":"selector1","paramExpress":"<selectorName>"}`; `<selectorName>` must be one of the VO's `selectorItems`. No `quota`.
+  - `Variable` — no `quota`; override `paramExpress` only. Quoting depends on the VO's `variableType`: a custom (`Normal`) variable is substituted verbatim, so include the quotes exactly as shown in the definition (e.g. `"paramExpress":"'2025-12-31'"`); a `TimeSelect` variable takes a bare value (the backend quotes it). `variableType` itself is a report-design property in `events.sqlVoParams` and is NOT changed by `--sql_params` (only the value is); the resulting SQL is the same regardless of `variableType` as long as the value is supplied with the right quoting.
+  - `Text` — `quota` (operator) + `paramExpress`; supports all 12 operators in the table below. Setting only `paramExpress` while leaving the no-value default `quota` (e.g. `C04`) does NOT filter.
+  - `Number` — `quota` (operator) + `paramExpress`; 9 numeric operators: `C00` IN / `C01` NOT IN / `C06` BETWEEN (array); `C02` < / `C03` > / `C020` <= / `C030` >= (single, numeric string); `C04` IS NOT NULL / `C05` IS NULL (no value). No LIKE/CONTAIN for numbers. E.g. `{"paramName":"num1","quota":"C06","paramExpress":["10","20"]}`.
+  - `Time` — `quota` (operator) + time fields (NOT recentDay): `C020` <= (uses `endTime`) / `C030` >= (uses `startTime`) / `C06` BETWEEN by datetime (`startTime`+`endTime`) / `C060` BETWEEN by date (`startTime`+`endTime`) / `C04` IS NOT NULL / `C05` IS NULL (no value). To only change the range keep the report's range `quota` and set `startTime`+`endTime`; to change the operator also set `quota`.
+  - `PartDate` — a date range; set `startTime`+`endTime`: `{"paramName":"date1","startTime":"yyyy-MM-dd HH:mm:ss","endTime":"yyyy-MM-dd HH:mm:ss"}`.
+
+  `quota` operators (Text = all; Number = the non-LIKE subset; Time = comparison/range/null subset using time fields):
+
+  | quota | operator | value |
+  |---|---|---|
+  | `C00` | IN | array `paramExpress` |
+  | `C01` | NOT IN | array `paramExpress` |
+  | `C06` | BETWEEN / 区间 | array `[min,max]` (Time: `startTime`+`endTime`) |
+  | `C060` | BETWEEN by date / 日期区间 (Time only) | `startTime`+`endTime` |
+  | `C02` / `C03` | `<` / `>` | single `paramExpress` |
+  | `C020` / `C030` | `<=` / `>=` | single `paramExpress` (Time: `endTime` / `startTime`) |
+  | `C30` / `C31` | LIKE / NOT LIKE (Text only) | single `paramExpress` |
+  | `C300` | CONTAIN (`LIKE '%v%'`, Text only) | single `paramExpress` |
+  | `C04` / `C05` | IS NOT NULL / IS NULL | no value (`C04` empty default = no filter) |
+
+- An unknown `paramName` (not present in the report) or malformed JSON returns an error.
 
 ## Decision Rules
 - `filters` / `group_by` cannot be written by hand based on experience alone: they must satisfy both the schema structure and the project's real metadata.
 - `list_events` / `list_properties` must be learned from the corresponding reference docs before calling them.
-- For the first run, it is recommended to pass only the required parameters (`--project_id`, `--report_ids`) and add optional parameters after confirming the chain works.
+- For the first run, include all required parameters (`--project_id`, `--report_ids`, `--request_id`) and add optional parameters after confirming the chain works.
+- Generate and pass `--request_id` before starting any cancelable query; it is required. If `fetch failed`, HTTP timeout, or caller timeout happens, the backend query may still be running; call `+cancel_query --request_id <same value>` with the preset ID. The value must use `mcp_<32 lowercase hex UUID>`, for example `mcp_0123456789abcdef0123456789abcdef`. Omitted or blank IDs return `REQUEST_ID_REQUIRED`; invalid format returns `INVALID_REQUEST_ID`.
 - Wrap JSON parameters in single quotes (for example `--report_ids '{}'`, `--filters '{}'`) to avoid shell escaping issues.
 - When dates/time ranges are involved, validate with a short range first and then expand gradually.
 - For cross-project troubleshooting, first confirm whether `--project_id` matches the current permissions and target environment.
 
 ## Next Step After Failure
-- If required parameters are missing, fall back to the smallest runnable command and fill them in (focus on `--project_id`, `--report_ids`).
+- If required parameters are missing, fall back to the smallest runnable command and fill them in (focus on `--project_id`, `--report_ids`, `--request_id`).
 - If `Invalid JSON` appears, first check the required schema fields, then verify that the event name/property name comes from metadata queried in the same `project_id`.
 - If the query times out or the result is abnormal, first reduce the time range/grouping dimensions, then split the query to locate the issue.
 
 ## Recommended Chaining
 - +get_filter_schema -> +get_groupby_schema -> analysis_meta +list_events -> analysis_meta +list_properties -> +query_report_data
+- (SQL-model report, override dynamic params) +get_report_definition -> +query_report_data --sql_params '[...]'
 - +list_reports -> +get_report_definition -> +query_report_data

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

@@ -0,0 +1,36 @@
+# analysis_audience +update_id_cluster (Update ID Cluster)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Cluster Management**
+
+## Use Cases
+- Update an existing ID cluster by re-uploading CSV file content as plain text.
+- The cluster is identified by `cluster_name`. The operation is asynchronous.
+
+## Commands
+```bash
+ae-cli analysis_audience +update_id_cluster --project_id <project_id> --cluster_name my_id_cluster --file_content "user_001
+user_002"
+ae-cli analysis_audience +update_id_cluster --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--cluster_name` | Yes | Cluster name to update |
+| `--file_content` | Yes | New CSV file content as plain text. No header row, UTF-8 encoding. Each row contains one user ID. Max 100MB. |
+| `--display_name` | No | Optional new display name |
+| `--remarks` | No | Optional new remarks (max 200 characters) |
+| `--main_column_name` | No | Optional new main column name for ID matching |
+
+## Return Value
+Returns `clusterId`, `uploadNum`, `userNum`, `unmatchedNum`, and `clusterName`.
+
+## Decision Rules
+- Use `+list_clusters` to confirm the cluster name before updating.
+- If file size exceeds 100MB, inform the user to upload directly via the web interface.
+
+## Recommended Chain
+- `+list_clusters` -> `+update_id_cluster`

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

@@ -0,0 +1,37 @@
+# analysis_audience +update_id_tag (Update ID Tag)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Tag Management**
+
+## Use Cases
+- Update an existing ID tag by re-uploading CSV file content as plain text.
+- The tag is identified by `tag_name`. The operation is asynchronous.
+
+## Commands
+```bash
+ae-cli analysis_audience +update_id_tag --project_id <project_id> --tag_name vip_tag --file_content "user_001,gold
+user_002,silver"
+ae-cli analysis_audience +update_id_tag --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--tag_name` | Yes | Tag name to update |
+| `--file_content` | Yes | New CSV file content as plain text. No header row, UTF-8 encoding. Column 1: user ID. Column 2: tag value (optional). Example: user_001,gold_member. Max 100MB. |
+| `--display_name` | No | Optional new display name |
+| `--remarks` | No | Optional new remarks (max 200 characters) |
+| `--entity_id` | No | Entity ID to associate the tag with |
+| `--main_column_name` | No | Optional new main column name for ID matching |
+
+## Return Value
+Returns `clusterId`, `uploadNum`, `userNum`, `unmatchedNum`, and `clusterName` (tag name).
+
+## Decision Rules
+- Use `+list_tags` to confirm the tag name before updating.
+- If file size exceeds 100MB, inform the user to upload directly via the web interface.
+
+## Recommended Chain
+- `+list_tags` -> `+update_id_tag`

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

@@ -0,0 +1,35 @@
+# analysis +update_report (Update Report)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Report Management**
+
+## Use Cases
+- Update an existing report's name, description, or QP (query parameter JSON).
+- At least one of `--report_name`, `--report_desc`, or `--qp` must be provided.
+- When updating `--qp`, also provide `--report_model` for QP validation.
+
+## Commands
+```bash
+ae-cli analysis +update_report --project_id <project_id> --report_id <report_id> --version <version> --report_name "New Name"
+ae-cli analysis +update_report --project_id <project_id> --report_id <report_id> --version <version> --qp '<qp_json>' --report_model 1
+ae-cli analysis +update_report --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--report_id` | Yes | Report ID to update |
+| `--version` | Yes | Current report version number. Retrieve via `+get_report_definition`. |
+| `--report_name` | No | New report name. Omit to keep existing. |
+| `--report_desc` | No | New report description. Omit to keep existing. |
+| `--qp` | No | New QP JSON string. Omit to keep existing. When provided, also supply `--report_model`. |
+| `--report_model` | No | Analysis model type integer (e.g. 1=event, 2=retention). Required when `--qp` is provided. |
+
+## Decision Rules
+- Always call `+get_report_definition` first to retrieve the current `version` number before updating.
+- Omitting all of `report_name`, `report_desc`, and `qp` will cause an error.
+
+## Recommended Chain
+- `+list_reports` -> `+get_report_definition` (to get version) -> `+update_report`

package/skills/ae-analysis-intent/SKILL.md

@@ -71,7 +71,7 @@ ae-cli <service> +<command> [options]
 - Event list: `ae-cli analysis_meta +list_events -p <project_id>`
 - Property list: `ae-cli analysis_meta +list_properties -p <project_id>`
 - Metric list: `ae-cli analysis_meta +list_metrics -p <project_id>`
-- Table columns: `ae-cli analysis +get_table_columns -p <project_id> --catalog hive --schema ta --table <table>`
+- Table columns: `ae-cli analysis +get_table_columns -p <project_id> --table_ref <hive.schema.table|schema.table|table>`
 
 ### Report/dashboard queries