@thinkingai/ae-cli 6.1.28 → 6.1.29

package/skills/ae-metadata/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ae-metadata
-version: 1.0.4
+version: 1.0.5
 description: "AE metadata capability-gateway CLI: list, inspect, create, update, delete and download metadata data tables; bind an existing dimension table to a property or create and bind a CSV dimension table. Local file upload and event/property discovery are separate prerequisite capabilities."
 ---
 
@@ -14,7 +14,7 @@ Use this skill for gateway-backed data-table and property dimension-table operat
 
 - Responsibilities: data-table management and dimension-table bindings through the commands below.
 - Inputs: verified project, table/property identifiers and operation-specific parameters; local CSV workflows need a valid uploaded input-file identifier and purpose.
-- Outputs: table/binding operation results, resource identifiers, or download run/artifact status. A submitted asynchronous download is not yet a completed file.
+- Outputs: table/binding operation results, resource identifiers, or download run/artifact status. Data-table get can include saved SQL definitions, parameters, and schedule configuration on supported servers; read its reference for availability and execution-value limits. A submitted asynchronous download is not yet a completed file.
 - Boundaries: local input-file upload, event/property detail and discovery, metric CRUD, virtual metadata, batch metadata, project configuration and tracking plans are separate capabilities.
 - Completion: the requested table or binding result is verified, or pending/blocked work and its remaining requirements are reported.
 

package/skills/ae-metadata/references/metadata_data_table_get.md

@@ -9,6 +9,8 @@ ae-cli metadata data-table get --project-id <project_id> --data-table-id <id>
 ae-cli metadata data-table get --project-id <project_id> --data-table-id <id> --include-preview true
 ```
 
+Use this command to inspect a metadata data table's columns, bindings, and saved SQL configuration. It requires the existing metadata view permission for the selected project. Reading a saved SQL definition does not authorize querying its upstream tables.
+
 ## Parameters
 
 | Parameter | Required | Description |
@@ -24,3 +26,36 @@ Each call to this capability's Gateway `execute` endpoint consumes one unit of t
 ```json
 { "project_id": 1, "data_table_id": 42, "include_preview": true }
 ```
+
+## Detail output
+
+Default JSON returns the complete server payload under `data`, including columns and bindings. `--include-preview true` additionally requests preview rows; it is not required to read saved SQL configuration.
+
+On servers that support SQL definition output, SQL tables add the following fields in both default and preview responses. Non-SQL tables omit them.
+
+| Field | Meaning |
+|---|---|
+| `create_qp` | Saved creation QP as a JSON object. |
+| `update_qp` | Saved update QP as a JSON object. |
+| `create_zone_offset` / `update_zone_offset` | Offset in hours used to parse SQL parameters for the corresponding QP. These are not the cron schedule timezone. |
+| `strategy` | Saved update strategy, such as `overwrite` or `insert`. |
+| `update_cron` | Saved update cron expression. Interpret it together with `update_conf_status`. |
+| `update_conf_status` | Schedule switch state: `NOT_SET`, `ENABLE`, or `DISABLE`. This is not task running status or evidence that an execution succeeded. |
+
+The wrapper fields use snake_case. QP objects retain the published model keys: SQL is at `taSqlVo.sql`, SQL parameters at `taSqlVo.sqlVoParams`, and view parameters at `taSqlView.sqlViewParams`. Preserve all nested keys and values, including extensions, when reading or reusing the definition. See [the SQL-write QP contract](metadata_data_table_sql_write.md#qp-contract-sqldatatabledef) before constructing a write.
+
+Parameter definitions and saved values describe configuration. Values containing expressions or placeholders may resolve differently during each execution. This response does not supply the actual resolved values of a specific execution; obtain execution evidence separately when those values are required.
+
+For SQL tables, unavailable configuration values are `null`; missing, invalid, or non-object historical QP values also produce `null` QP fields. Default get returns `null` configuration fields when the SQL definition record is missing. `--include-preview true` retains the server's existing preview behavior; missing definition records may still cause preview to fail on affected servers. A `null` QP does not establish that the SQL has no parameters. An empty parameter array is an explicit empty saved parameter list. Older servers may omit the new fields entirely, so missing fields alone do not prove that configuration is empty or that this server supports definition output. Inspect the selected server capability when availability matters.
+
+## Read the complete definition
+
+Use `--format json` to retain SQL configuration beside columns and bindings. Table format may render only the columns array. CLI `--jq` runs on the payload before envelope wrapping, so paths start at `.create_qp` or `.update_qp`, not `.data`.
+
+```bash
+ae-cli metadata data-table get --project-id <project_id> --data-table-id <id> --format json
+ae-cli metadata data-table get --project-id <project_id> --data-table-id <id> --jq '{create_qp, update_qp, create_zone_offset, update_zone_offset, strategy, update_cron, update_conf_status}'
+ae-cli metadata data-table get --project-id <project_id> --data-table-id <id> --jq '.update_qp.taSqlVo.sqlVoParams'
+```
+
+Choose the full response or a projection containing all required fields in one read. If the response is saved to a local file, inspect that file for additional paths instead of repeating the server request.