@clickzetta/cz-cli-darwin-arm64 0.5.15 → 0.5.17

package/bin/skills/lakehouse-doc-en/references/open-api-safe-question-poll.md

@@ -0,0 +1,201 @@
+# SafeQuestionPoll - Poll for Question Results
+
+Poll to query the analysis execution status and results for a specified question.
+
+## Interface Description
+
+After submitting a question via [Text2InsightQuery](open-api-text2insight-query), the client must call this interface in a loop to retrieve the analysis progress and final results. Each call returns all `responses` messages produced so far.
+
+### Polling Strategy
+
+| Parameter | Recommended Value |
+|-----------|-------------------|
+| Polling interval | 2 seconds |
+| Single request timeout | 60 seconds |
+| Total timeout | 360 seconds |
+
+### Termination Condition
+
+On each poll, check the `dataType` of the last message in the `responses` array. Stop polling when the value is one of the following:
+
+- `finish` — Analysis completed normally
+- `finish_stop` — User actively stopped the analysis
+- `error` — Execution error occurred
+
+## Request Method
+
+```
+POST /open/safe_question_poll?tenantId={tenantId}&userId={userId}&loginToken={loginToken}
+```
+
+> 💡 **Note**: `tenantId`, `userId`, and `loginToken` must appear **both** in the URL query parameters and in the request body. Missing query parameters will cause the request to fail.
+
+## Request Parameters
+
+| Parameter | Location | Type | Required | Description |
+|-----------|----------|------|----------|-------------|
+| tenantId | Query + Body | Integer | Yes | Tenant ID |
+| userId | Query + Body | Integer | Yes | User ID |
+| domainId | Body | Integer | Yes | Data domain ID |
+| questionId | Body | Integer | Yes | Question ID, obtained via Text2InsightQuery |
+| loginToken | Query + Body | String | Yes | Authentication Token |
+
+## Response Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| success | Boolean | Whether the request was successful |
+| data.responses | Array | Message list containing all messages produced during the analysis |
+| data.responses[].id | String | Message ID |
+| data.responses[].dataType | String | Message type, see description below |
+| data.responses[].message | String | Message text content |
+| data.responses[].modelRes | Object | Raw structure returned by the model |
+| data.responses[].modelRes.code | Integer | Model response code |
+| data.responses[].modelRes.data | Object | Business data returned by the model |
+
+## Message Type Description (dataType)
+
+| Type | Description | Key Fields |
+|------|-------------|------------|
+| message | General message; may contain knowledge details or execution logs | message, knowledgeData |
+| notify | Progress notification (e.g., "Thinking") | message |
+| summary | Analysis summary containing the final answer | summaryData |
+| metric | Metric calculation result | message, metricDsl, physicalMetricDsl |
+| echarts_plus | Chart data | message, chartType, columns, calculateSql |
+| code | Code block (e.g., generated SQL) | message, codeType, code |
+| finish | Analysis ended normally | message |
+| finish_stop | User actively stopped | message |
+| error | Execution error | message |
+
+## Field Read Priority
+
+Business fields in each `responses` message may appear at different levels. Read in the following priority order:
+
+1. Top level: `response[fieldName]`
+2. modelRes: `response.modelRes.data[fieldName]`
+3. rawRes: parse `response.rawRes` (JSON string) and retrieve `data[fieldName]`
+
+## Request Example
+
+```http
+POST /open/safe_question_poll
+Content-Type: application/json
+
+{
+  "tenantId": 10,
+  "userId": 1,
+  "domainId": 106,
+  "questionId": 34339,
+  "loginToken": "eyJhbGciOiJIUzI1NiJ9..."
+}
+```
+
+## Response Examples
+
+### Analysis In Progress
+
+```json
+{
+  "success": true,
+  "data": {
+    "responses": [
+      {
+        "id": "745601",
+        "dataType": "notify",
+        "message": "Thinking next step"
+      }
+    ]
+  }
+}
+```
+
+### Analysis Complete (with metric results)
+
+```json
+{
+  "success": true,
+  "data": {
+    "responses": [
+      {
+        "id": "745618",
+        "dataType": "message",
+        "message": "Viewed knowledge details: Beijing Second-hand Housing 10-year Transaction Data",
+        "modelRes": {
+          "code": 200,
+          "data": {
+            "dataType": "message",
+            "message": "Viewed knowledge details: Beijing Second-hand Housing 10-year Transaction Data",
+            "knowledgeData": {
+              "detailItems": [
+                {
+                  "id": 51,
+                  "keys": "Beijing Second-hand Housing 10-year Transaction Data",
+                  "value": "{\"desc\": \"If no time is explicitly specified in the question, use yesterday\", \"type\": \"time_range_func\"}",
+                  "type": "TEXT"
+                }
+              ]
+            }
+          }
+        }
+      },
+      {
+        "id": "745620",
+        "dataType": "metric",
+        "message": "Metric: Total Transaction Amount by District in the Past 6 Years",
+        "modelRes": {
+          "code": 200,
+          "data": {
+            "dataType": "metric",
+            "message": "Metric: Total Transaction Amount by District in the Past 6 Years",
+            "metricDsl": "{\"useDefaultLimit\":true,\"metricId\":{\"metricType\":\"SQL_SIMPLE\",\"id\":631},\"name\":\"Total Transaction Amount by District in the Past 6 Years\"}",
+            "physicalMetricDsl": "{\"useDefaultLimit\":true,\"metricId\":{\"metricType\":\"SQL_SIMPLE\",\"id\":631}}"
+          }
+        }
+      },
+      {
+        "id": "745625",
+        "dataType": "echarts_plus",
+        "message": "Beijing Second-hand Housing Total Transaction Amount by District in the Past 6 Years (2015-2021)",
+        "modelRes": {
+          "code": 200,
+          "data": {
+            "dataType": "echarts_plus",
+            "chartType": "ECHARTS",
+            "columns": "District (STRING), Total Transaction Amount (10K CNY) (LONG)",
+            "calculateSql": "SELECT region AS district, SUM(transaction_price) AS total_transaction_amount FROM ... GROUP BY region"
+          }
+        }
+      },
+      {
+        "id": "745630",
+        "dataType": "summary",
+        "message": "Analysis complete",
+        "modelRes": {
+          "code": 200,
+          "data": {
+            "dataType": "summary",
+            "summaryData": "**Beijing Second-hand Housing Total Transaction Amount by District in the Past 6 Years:**\n- Chaoyang District: CNY 103.49 billion\n- Haidian District: CNY 58.50 billion\n..."
+          }
+        }
+      },
+      {
+        "id": "745631",
+        "dataType": "finish",
+        "message": "Analysis complete"
+      }
+    ]
+  }
+}
+```
+
+## Error Codes
+
+| Error Code | Description |
+|------------|-------------|
+| success=false | Token is invalid, questionId does not exist, or insufficient permissions |
+
+## Related Documentation
+
+- [Text2InsightQuery](open-api-text2insight-query) — Previous step: submit a data analysis request
+- [Understanding Response Results](open-api-response-guide) — Meaning and reading method for each message type in responses
+- [Quick Start](open-api-quick-start) — Complete end-to-end example

package/bin/skills/lakehouse-doc-en/references/open-api-text2insight-query.md

@@ -0,0 +1,99 @@
+# Text2InsightQuery - Submit a Data Analysis Request
+
+Submit a natural language question to Analytics Agent to initiate a data analysis task.
+
+## Interface Description
+
+This interface is asynchronous. Upon a successful call, it returns a `questionId` and an initial status of `running`, indicating that the analysis task has started. The client must poll for analysis results via the [SafeQuestionPoll](open-api-safe-question-poll) interface.
+
+### Usage Notes
+
+- Questions are described in natural language; the Agent will automatically understand and perform the analysis.
+- Supports specifying the model to use via `modelSettings`.
+- Multiple questions can be submitted consecutively within the same Session, and the Agent retains conversational context.
+
+### Usage Recommendations
+
+- Make question descriptions as clear and specific as possible, including key information such as time ranges and dimensions.
+- If you need the knowledge base to assist with the analysis, you can prompt the Agent in the question to consult the knowledge base.
+
+## Request Method
+
+```
+POST /open/text2insight/query?tenantId={tenantId}&userId={userId}&loginToken={loginToken}
+```
+
+> 💡 **Note**: `tenantId`, `userId`, and `loginToken` must appear **both** in the URL query parameters and in the request body. Missing query parameters will cause the request to fail.
+
+## Request Parameters
+
+| Parameter | Location | Type | Required | Description |
+|-----------|----------|------|----------|-------------|
+| tenantId | Query + Body | Integer | Yes | Tenant ID |
+| userId | Query + Body | Integer | Yes | User ID |
+| domainId | Body | Integer | Yes | Data domain ID |
+| sessionId | Body | Integer | Yes | Conversation session ID, obtained via CreateSession or reusing an existing value |
+| msg | Body | String | Yes | Question content, an analysis request described in natural language |
+| loginToken | Query + Body | String | Yes | Authentication Token |
+| modelSettings | Body | Object | No | Model configuration |
+| modelSettings.model_name | Body | String | No | Specify the model name to use |
+
+## Response Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| success | Boolean | Whether the request was successful |
+| data.questionId | Integer | Question ID, used for subsequent polling and stop operations |
+| data.sessionId | Integer | Session ID |
+| data.status | String | Current status; initial value is `running` |
+
+## Request Example
+
+```http
+POST /open/text2insight/query
+Content-Type: application/json
+
+{
+  "tenantId": 10,
+  "userId": 1,
+  "domainId": 106,
+  "sessionId": 4729,
+  "msg": "Show me the second-hand housing sales in Beijing over the past 6 years, broken down by district",
+  "loginToken": "eyJhbGciOiJIUzI1NiJ9...",
+  "modelSettings": {
+    "model_name": "qwen/qwen3.6-plus"
+  }
+}
+```
+
+## Response Example
+
+Successful response:
+
+```json
+{
+  "success": true,
+  "data": {
+    "questionId": 34339,
+    "sessionId": 4729,
+    "status": "running"
+  }
+}
+```
+
+## Next Steps
+
+After a successful request, use the returned `questionId` to call [SafeQuestionPoll](open-api-safe-question-poll) and poll until the analysis is complete.
+
+## Error Codes
+
+| Error Code | Description |
+|------------|-------------|
+| success=false | Token is invalid, Session does not exist, parameters are missing, or model is unavailable |
+
+## Related Documentation
+
+- [CreateSession](open-api-create-session) — Previous step: create a conversation session
+- [SafeQuestionPoll](open-api-safe-question-poll) — Next step: poll for analysis results
+- [Understanding Response Results](open-api-response-guide) — Message type descriptions and display recommendations
+- [Quick Start](open-api-quick-start) — Complete end-to-end example

package/bin/skills/lakehouse-doc-en/references/open-api-text2insight-stop.md

@@ -0,0 +1,74 @@
+# Text2InsightStop - Stop a Question
+
+Stop a data analysis task that is currently running.
+
+## Interface Description
+
+When an analysis task is taking too long or the user wants to interrupt the current analysis, this interface can be called to stop the execution of a specified question. After stopping, the `dataType` of the last message in the polling results will become `finish_stop`.
+
+### Usage Notes
+
+- Only effective for questions with a status of `running`.
+- The stop operation cannot be undone.
+- Intermediate results already produced are still available via the polling interface.
+
+## Request Method
+
+```
+POST /open/text2insight/stop?tenantId={tenantId}&userId={userId}&loginToken={loginToken}
+```
+
+> 💡 **Note**: `tenantId`, `userId`, and `loginToken` must appear **both** in the URL query parameters and in the request body. Missing query parameters will cause the request to fail.
+
+## Request Parameters
+
+| Parameter | Location | Type | Required | Description |
+|-----------|----------|------|----------|-------------|
+| tenantId | Query + Body | Integer | Yes | Tenant ID |
+| userId | Query + Body | Integer | Yes | User ID |
+| sessionId | Body | Integer | Yes | Conversation session ID |
+| questionId | Body | Integer | Yes | ID of the question to stop |
+| loginToken | Query + Body | String | Yes | Authentication Token |
+
+## Response Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| success | Boolean | Whether the request was successful |
+
+## Request Example
+
+```http
+POST /open/text2insight/stop
+Content-Type: application/json
+
+{
+  "tenantId": 10,
+  "userId": 1,
+  "sessionId": 4729,
+  "questionId": 34339,
+  "loginToken": "eyJhbGciOiJIUzI1NiJ9..."
+}
+```
+
+## Response Example
+
+Successful response:
+
+```json
+{
+  "success": true
+}
+```
+
+## Error Codes
+
+| Error Code | Description |
+|------------|-------------|
+| success=false | Token is invalid, question does not exist, question has already completed, or insufficient permissions |
+
+## Related Documentation
+
+- [Text2InsightQuery](open-api-text2insight-query) — Submit an analysis request to obtain a questionId
+- [SafeQuestionPoll](open-api-safe-question-poll) — After stopping, polling can continue; the last message dataType will be finish_stop
+- [Quick Start](open-api-quick-start) — Complete end-to-end example

package/bin/skills/lakehouse-doc-en/references/overview.md

@@ -13,7 +13,7 @@ Supports seven global clouds, already live in multiple Asia-Pacific regions, and
 <td style="width:25%; vertical-align:top; overflow-wrap:break-word;"><strong>Lake Acceleration (existing data lake)</strong><br>
 <small><a href="lakehouse-acceleration-guide.md">In-Place Lake Acceleration Guide</a> · <a href="external-catalog-summary.md">External Catalog Federation</a> · <a href="external-table-guide.md">External Tables</a> · <a href="external_volume.md">Object Storage Mount</a> · <a href="benchmark_guide.md">Performance Testing</a></small></td>
 <td style="width:25%; vertical-align:top; overflow-wrap:break-word;"><strong>AI Data Infrastructure</strong><br>
-<small><a href="LakehouseAI-overview.md">Lakehouse AI Overview</a> · <a href="server-data-for-ai.md">AI Data Readiness</a> · <a href="vector_search_ai.md">Vector Search</a> · <a href="AIGateway.md">AI Gateway</a> · <a href="datagpt_introduction.md">Data Analytics Agent</a></small></td>
+<small><a href="LakehouseAI-overview.md">Lakehouse AI Overview</a> · <a href="server-data-for-ai.md">AI Data Readiness</a> · <a href="vector_search_ai.md">Vector Search</a> · <a href="AIGateway.md">AI Gateway</a> · <a href="datagpt_introduction.md">Data Analytics Agent</a> · <a href="dataagent.md">Data Engineering Agent</a></small></td>
 <td style="width:25%; vertical-align:top; overflow-wrap:break-word;"><strong>Cloud Platforms and Deployment</strong><br>
 <small><a href="Supported-Cloud-Platforms.md">Supported Cloud Platforms and Regions</a> · <a href="pricing.md">Pricing and Billing</a></small></td>
 </tr>
@@ -63,7 +63,7 @@ Dedicated paths for data engineers, analysts, AI engineers, and administrators<b
 <td style="width:22%; vertical-align:top; overflow-wrap:break-word;"><strong>Data Engineer</strong><br><small>Build data pipelines, ETL processing, manage data warehouse layers</small></td>
 <td style="vertical-align:top; overflow-wrap:break-word;">
 
-[Dynamic Table Incremental Computation](incremental-computing.md) · [Dynamic Table Overview](dynamic_table_summary.md) · [Real-time Data Pipeline](streaming_data_pipeline_overview.md) · [Studio Task Development and Scheduling](task-develop.md) · [Task Parameters](task_param.md) · [CREATE TABLE Syntax Reference](create-table-ddl.md) · [SQL Syntax Reference](sql-reference.md) · [COPY INTO](copy-into-table.md) · [cz-cli Command-Line Tool](setup_cz_cli.md) · [TPC-DS Performance Testing](tpcds-benchmark.md)
+[Dynamic Table Incremental Computation](incremental-computing.md) · [Dynamic Table Overview](dynamic_table_summary.md) · [Real-time Data Pipeline](streaming_data_pipeline_overview.md) · [Studio Task Development and Scheduling](task-develop.md) · [Task Parameters](task_param.md) · [CREATE TABLE Syntax Reference](create-table-ddl.md) · [SQL Syntax Reference](sql-reference.md) · [COPY INTO](copy-into-table.md) · [cz-cli Command-Line Tool](setup_cz_cli.md) · [Data Engineering Agent](dataagent.md) · [TPC-DS Performance Testing](tpcds-benchmark.md)
 
 </td>
 </tr>
@@ -95,7 +95,7 @@ Dedicated paths for data engineers, analysts, AI engineers, and administrators<b
 <td style="width:22%; vertical-align:top; overflow-wrap:break-word;"><strong>AI Agent / Automation</strong><br><small>Deterministic interface calls, semantic layer queries, automated data pipelines</small></td>
 <td style="vertical-align:top; overflow-wrap:break-word;">
 
-[cz-cli Command-Line Tool](setup_cz_cli.md) (deterministic interface, ideal for Agent calls) · [Semantic View](semantic-view-overview.md) (business semantic layer, natural-language friendly) · [Python SDK (SQL interface)](python_reference/connector.md) · [ZettaPark (DataFrame API)](lakehousepython-zettapark.md) · [Data Analytics Agent](datagpt_introduction.md)
+[cz-cli Command-Line Tool](setup_cz_cli.md) (deterministic interface, ideal for Agent calls) · [Semantic View](semantic-view-overview.md) (business semantic layer, natural-language friendly) · [Python SDK (SQL interface)](python_reference/connector.md) · [ZettaPark (DataFrame API)](lakehousepython-zettapark.md) · [Data Analytics Agent](datagpt_introduction.md) · [Data Engineering Agent](dataagent.md) · [Singclaw](https://www.singclaw.ai/)
 
 </td>
 </tr>
@@ -142,7 +142,7 @@ Define transformation logic with standard SQL. Dynamic Table automatically detec
 
 Vectorized execution engine. Leading industry performance on TPC-DS / TPC-H / SSB benchmarks. Supports OLAP multi-dimensional analysis and ad-hoc queries — up to 10× faster than traditional Spark architectures.
 
-[Performance Testing](benchmark_guide.md) · [SQL Usage Guide](considerations-for-using-sql.md) · [TPC-H Sample Experience](get-started-with-sample-data.md)
+[Performance Testing](benchmark_guide.md) · [SQL Usage Guide](considerations-for-using-sql.md)
 
 </td>
 </tr>
@@ -151,9 +151,9 @@ Vectorized execution engine. Leading industry performance on TPC-DS / TPC-H / SS
 
 **AI-Native**
 
-Vector indexes, full-text search, AI Functions (AI\_COMPLETE / AI\_EMBEDDING), and Semantic Views are built into the data platform. Build RAG knowledge bases and AI-enhanced analytics without external services. Data Analytics Agent supports natural language conversational data queries.
+Vector indexes, full-text search, AI Functions (AI\_COMPLETE / AI\_EMBEDDING), and Semantic Views are built into the data platform. Build RAG knowledge bases and AI-enhanced analytics without external services. Data Analytics Agent supports natural language conversational data queries; Data Engineering Agent supports natural language ETL development, task management, and operations diagnostics.
 
-[Lakehouse AI Overview](lakehouseai-overview.md) · [Vector Search](vector_search_ai.md) · [AI Functions](ai_function_in_sql.md) · [Semantic View](semantic-view-overview.md) · [Data Analytics Agent](datagpt_introduction.md)
+[Lakehouse AI Overview](lakehouseai-overview.md) · [Vector Search](vector_search_ai.md) · [AI Functions](ai_function_in_sql.md) · [Semantic View](semantic-view-overview.md) · [Data Analytics Agent](datagpt_introduction.md) · [Data Engineering Agent](dataagent.md) · [Singclaw](https://www.singclaw.ai/)
 
 </td>
 <td style="width:50%; vertical-align:top; padding:0 0 0 16px; overflow-wrap:break-word;">
@@ -183,5 +183,4 @@ Built-in IDE, task scheduling, data integration, data quality, and operations mo
 | [Before You Begin](setup.md) | Ways to access Lakehouse: Studio, CLI, drivers and connectors |
 | [Account Signup and Setup](logging-in.md) | Register an account, activate a service instance, complete initialization |
 | [Supported Cloud Platforms](supported-cloud-platforms.md) | Supported cloud providers and available regions |
-| [Pricing and Billing](pricing.md) | Billing model and cost breakdown |
 | [Trial Account Quotas and Limits](trial-account-quotas-and-limits.md) | Resource quota limits during the trial period |

package/bin/skills/lakehouse-doc-en/references/permission-application.md

@@ -17,9 +17,9 @@ If you need to use data resources developed by others, you must apply for permis
 Follow the entry points above, select the target object, and click **Apply for Permission** to open the data object permission application dialog.
 
 \:-:
-![](.topwrite/assets/image_1734438890426.png =501)
 
-1) Application Information
+
+1. Application Information
 
 * Object Permission: The permission points available to apply for on the current object. Different resource object levels provide different permission type options. Available access permissions include three options: All, Read, and Write.
 
@@ -36,8 +36,8 @@ Follow the entry points above, select the target object, and click **Apply for P
 
 * Application Reason: A detailed explanation of why you are applying for resource permissions.
 
-2) You can click **Add Application** to add another resource request. In the additional resource request, you need to re-enter the object permission, grant target, grant duration, and application reason.
+2. You can click **Add Application** to add another resource request. In the additional resource request, you need to re-enter the object permission, grant target, grant duration, and application reason.
 
-3) After applying for permissions, you can view all your submitted work orders under **Approval Center > Applications**, including application content, application status, etc. You can also withdraw or send reminder actions for a work order.
+3. After applying for permissions, you can view all your submitted work orders under **Approval Center > Applications**, including application content, application status, etc. You can also withdraw or send reminder actions for a work order.
 
-![](.topwrite/assets/image_1734438910731.png =344)
+^

package/bin/skills/lakehouse-doc-en/references/pipe-introduction.md

@@ -91,6 +91,7 @@ DESC PIPE my_pipe;
 
 ## Related Documents
 
+- [Real-Time Data Pipeline Selection Guide](realtime-pipeline-selection-guide.md): Comparison of Pipe, Table Stream, and Dynamic Table
 - [Pipe Introduction](pipe-summary.md)
 - [Kafka Pipe](pipe-kafka.md)
 - [Object Storage Pipe](pipe-storage-object.md)