@clickzetta/cz-cli-darwin-x64 0.5.16 → 0.5.17

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

@@ -41,24 +41,24 @@ The source database requires certain parameter settings and permission grants to
 
 Note: Modifying the following parameters requires restarting the PostgreSQL server to take effect.
 
-|                            |                                                                                                                                                                                                                                                                                                 |                      |
-| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
-| Configuration              | Description                                                                                                                                                                                                                                                                                     | Default Value (Unit) |
-| wal\_level                 | WAL level. `logical` is required for real-time sync. `replica` supports WAL archiving and replication. `minimal` keeps only what is needed to recover from a crash.                                                                                                                             | replica              |
-| max\_replication\_slots    | Maximum number of replication slots allowed on the server.                                                                                                                                                                                                                                      | 10                   |
-| max\_wal\_senders          | Maximum number of WAL sender processes that can run simultaneously, corresponding to the number of concurrent real-time sync tasks.                                                                                                                                                              | 10                   |
-| max\_slot\_wal\_keep\_size | Size of WAL retained per slot. `-1` means unlimited.                                                                                                                                                                                                                                           | -1 (MB)              |
-| wal\_sender\_timeout       | Replication connections idle longer than this value will be terminated.                                                                                                                                                                                                                         | 60000 (ms)           |
+|                            |                                                                                                                                                                     |                      |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| Configuration              | Description                                                                                                                                                         | Default Value (Unit) |
+| wal\_level                 | WAL level. `logical` is required for real-time sync. `replica` supports WAL archiving and replication. `minimal` keeps only what is needed to recover from a crash. | replica              |
+| max\_replication\_slots    | Maximum number of replication slots allowed on the server.                                                                                                          | 10                   |
+| max\_wal\_senders          | Maximum number of WAL sender processes that can run simultaneously, corresponding to the number of concurrent real-time sync tasks.                                 | 10                   |
+| max\_slot\_wal\_keep\_size | Size of WAL retained per slot. `-1` means unlimited.                                                                                                                | -1 (MB)              |
+| wal\_sender\_timeout       | Replication connections idle longer than this value will be terminated.                                                                                             | 60000 (ms)           |
 
 **MySQL**
 
-|                               |                                                                                                                                                                                                                                                                                                                                                                                                                                            |                                                                           |                                                  |
-| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- | ------------------------------------------------ |
-| Attribute                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                | Required Setting                                                          | Query Method                                     |
-| log\_bin                      | Whether binlog is enabled.                                                                                                                                                                                                                                                                                                                                                                                                                 | ON                                                                        | SHOW GLOBAL VARIABLES LIKE 'log\_bin'            |
-| binlog\_format                | Binlog format. `statement` records SQL (compact but can cause sync errors with non-deterministic functions). `row` records full before/after row images (accurate but higher volume). `mixed` lets MySQL choose automatically.                                                                                                                                                                                                              | ROW                                                                       | SHOW GLOBAL VARIABLES LIKE 'binlog\_format'      |
-| binlog\_row\_image            | Whether full before/after row images are recorded.                                                                                                                                                                                                                                                                                                                                                                                         | FULL (record all fields in both images)                                   | SHOW GLOBAL VARIABLES LIKE 'binlog\_row\_image'  |
-| binlog\_expire\_logs\_seconds | Binlog automatic cleanup interval.                                                                                                                                                                                                                                                                                                                                                                                                         | Configure based on business needs; 86400 seconds (1 day) or more recommended. |                                              |
+|                               |                                                                                                                                                                                                                                |                                                                               |                                                 |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | ----------------------------------------------- |
+| Attribute                     | Description                                                                                                                                                                                                                    | Required Setting                                                              | Query Method                                    |
+| log\_bin                      | Whether binlog is enabled.                                                                                                                                                                                                     | ON                                                                            | SHOW GLOBAL VARIABLES LIKE 'log\_bin'           |
+| binlog\_format                | Binlog format. `statement` records SQL (compact but can cause sync errors with non-deterministic functions). `row` records full before/after row images (accurate but higher volume). `mixed` lets MySQL choose automatically. | ROW                                                                           | SHOW GLOBAL VARIABLES LIKE 'binlog\_format'     |
+| binlog\_row\_image            | Whether full before/after row images are recorded.                                                                                                                                                                             | FULL (record all fields in both images)                                       | SHOW GLOBAL VARIABLES LIKE 'binlog\_row\_image' |
+| binlog\_expire\_logs\_seconds | Binlog automatic cleanup interval.                                                                                                                                                                                             | Configure based on business needs; 86400 seconds (1 day) or more recommended. |                                                 |
 
 #### Database Permission Configuration
 
@@ -68,11 +68,11 @@ Appropriate permissions must be configured on each source database to ensure cha
 
 When executing grant SQL statements, ensure the executing account itself has the ability to grant those permissions — using an administrator account is recommended. Execute the grants for all scenarios listed below to ensure the task runs smoothly.
 
-**Scenario: Task configuration (fetching metadata: schema list, table list, field list)**
+**Scenario: Task configuration (fetching metadata: schema list, table list, field list**)
 
 Required permissions:
 
-> SELECT (on information_schema and the tables to be inspected)
+> SELECT (on information\_schema and the tables to be inspected)
 
 Grant statements:
 
@@ -100,7 +100,7 @@ Grant statements:
 CREATE ROLE <name> REPLICATION LOGIN;
 ```
 
-**Scenario: Sync historical full data (optional)**
+**Scenario: Sync historical full data (optional**)
 
 * Required permissions:
 
@@ -138,7 +138,7 @@ Grant statement:
 
 When executing grant SQL statements, ensure the executing account has the GRANT OPTION privilege — using a superuser such as root is recommended. Execute the grants for all scenarios listed below.
 
-**Scenario: Task configuration (fetching metadata: database list, table list, field list)**
+**Scenario: Task configuration (fetching metadata: database list, table list, field list**)
 
 Required permissions:
 
@@ -210,13 +210,13 @@ Follow these steps in order:
 
 * Extended fields currently support: source server name, database name, schema name, and table name.
 
-  ![](.topwrite/assets/image_1740314767939.png =680)
+  ^
 
 ### General: If the same primary key exists in different sharded source tables, how do I avoid write conflicts in the target table?
 
 * Enable the extended fields feature in the task configuration, and include those extended fields in the composite primary key of the target table.
 
-  ![](.topwrite/assets/image_1740314789823.png =680)
+  ^
 
 ### General: If the sharded source tables have mostly — but not exactly — the same field structure, how do I configure the sync task?
 
@@ -314,7 +314,7 @@ There are several options:
 
   * `step1.taskmanager.memory.task.off-heap.size` — for example, set to `500M` (default: `256M`)
 
-    ![](.topwrite/assets/image_1740314863947.png =680)
+    ^
 
 ### Emergency Maintenance: The task has failed and I cannot resolve it on my own — how do I get help from Singdata?
 
@@ -334,31 +334,31 @@ There are several options:
 
 After a task starts, it goes through three phases: initialization, full sync, and incremental sync. You can view the status of these phases in the instance monitoring area.
 
-![](.topwrite/assets/image_1740314893402.png =600)
+^
 
 #### Metric Monitoring
 
-|                    |                                                                                                                                                                          |
-| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Metric             | Description                                                                                                                                                              |
-| Data read          | Number of records read from the source during the measurement period.                                                                                                    |
-| Data written       | Number of records written to the target during the measurement period.                                                                                                   |
-| Avg. read rate     | Average read rate during the measurement period (total records read / period duration).                                                                                  |
-| Avg. write rate    | Average write rate during the measurement period (total records written / period duration).                                                                              |
-| Failover count     | Number of failovers during the measurement period. This reflects the operational stability of the sync service itself.                                                   |
+|                 |                                                                                                                        |
+| --------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| Metric          | Description                                                                                                            |
+| Data read       | Number of records read from the source during the measurement period.                                                  |
+| Data written    | Number of records written to the target during the measurement period.                                                 |
+| Avg. read rate  | Average read rate during the measurement period (total records read / period duration).                                |
+| Avg. write rate | Average write rate during the measurement period (total records written / period duration).                            |
+| Failover count  | Number of failovers during the measurement period. This reflects the operational stability of the sync service itself. |
 
-![](.topwrite/assets/image_1740314904374.png =600)
+^
 
 #### Per-Table Sync Progress
 
-|                      |                                                                                                                                           |
-| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| Metric               | Description                                                                                                                               |
-| Latest read position | The write time of the most recent record written to the target table, used as a proxy for the current read position.                      |
-| Latest update time   | The last time a record was written to the target table.                                                                                   |
-| Data latency         | The time between a transaction committing on the source and the data becoming visible on the target.                                      |
+|                      |                                                                                                                      |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| Metric               | Description                                                                                                          |
+| Latest read position | The write time of the most recent record written to the target table, used as a proxy for the current read position. |
+| Latest update time   | The last time a record was written to the target table.                                                              |
+| Data latency         | The time between a transaction committing on the source and the data becoming visible on the target.                 |
 
-![](.topwrite/assets/image_1740314933658.png =600)
+^
 
 ### Configuring Task Monitoring and Alerts
 
@@ -381,25 +381,25 @@ In the monitoring and alerting module, you can configure monitoring rules to tra
 
 3. Add a new webhook configuration in the product — select Lark or WeCom as the channel and enter the bot's webhook URL.
 
-   ![](.topwrite/assets/image_1740315003712.png =680)
+   ^
 
 4. Enable the webhook in the notification policy.
 
-   ![](.topwrite/assets/image_1740315034077.png =680)
+   ^
 
 5. In the monitoring rule, select the notification policy with the webhook enabled, then choose the webhook configuration you just created.
 
-   ![](.topwrite/assets/image_1740315043022.png =680)
+   ^
 
 #### Configuring Exception Monitoring for Real-Time Data Integration Tasks
 
 1. **Task failover alert**: create a new monitoring rule and select "Multi-table real-time sync job failover" as the monitoring event. You can add filter attributes such as workspace or task name. If no filter is added, all multi-table real-time sync tasks in the instance are monitored by default.
 
-   ![](.topwrite/assets/image_1740315064690.png =680)
+   ^
 
 2. **Task stop alert**: create a new monitoring rule and select "Multi-table real-time sync task run failure" as the monitoring event. You can add filter attributes such as workspace or task name. If no filter is added, all multi-table real-time sync tasks in the instance are monitored by default.
 
-   ![](.topwrite/assets/image_1740315072098.png =460)
+   ^
 
 #### Configuring In-Task Exception Monitoring
 
@@ -409,21 +409,21 @@ In the monitoring and alerting module, you can configure monitoring rules to tra
 
    * You can configure an alert for when a table is added to the blacklist, covering two scenarios: Schema Evolution failure and a single field value exceeding the 10 MB size limit.
 
-     ![](.topwrite/assets/image_1740315081002.png =460)
+     ^
 
    * Schema Evolution failure alert: create a new monitoring rule and select "Multi-table real-time sync target table change failure."
 
-     ![](.topwrite/assets/image_1740315087204.png =460)
+     ^
 
 #### Configuring Maximum Latency Monitoring for Real-Time Data Integration Tasks
 
 1. **End-to-end sync latency**: create a new monitoring rule and select "Multi-table real-time sync latency." You can add filter attributes such as workspace or task name. If no filter is added, all multi-table real-time sync tasks in the instance are monitored by default.
 
-   ![](.topwrite/assets/image_1740315096380.png =680)
+   ^
 
 2. **Read checkpoint latency**: create a new monitoring rule and select "Multi-table real-time sync read checkpoint latency." You can add filter attributes such as workspace or task name. If no filter is added, all multi-table real-time sync tasks in the instance are monitored by default.
 
-   ![](.topwrite/assets/image_1740315103745.png =680)
+   ^
 
 ## Common Error Troubleshooting
 
@@ -443,11 +443,11 @@ In the monitoring and alerting module, you can configure monitoring rules to tra
 
   * Query the current binlog file and position with `SHOW MASTER STATUS`:
 
-    ![](.topwrite/assets/image_1740315126085.png =460)
+    ^
 
   * Restart the sync task using the file and position from the result.
 
-    ![](.topwrite/assets/image_1740315139248.png =460)
+    ^
 
   * If you need to recover the data that was missed, resync the affected tables.
 
@@ -507,7 +507,7 @@ In the monitoring and alerting module, you can configure monitoring rules to tra
 * Cause
 
   * The total encoded length of the primary key fields in the source table exceeds the default limit of 128 bytes.
-  * In a merge scenario, multiple extended fields (e.g., server_id, database, schema, table) are included in the composite primary key to prevent conflicts across sharded tables — and the total encoded key length exceeds 128 bytes.
+  * In a merge scenario, multiple extended fields (e.g., server\_id, database, schema, table) are included in the composite primary key to prevent conflicts across sharded tables — and the total encoded key length exceeds 128 bytes.
 
 * Resolution
 
@@ -567,7 +567,7 @@ In the monitoring and alerting module, you can configure monitoring rules to tra
 
 * Problem
 
-  *   A table's status automatically changes to "sync stopped." The tooltip on the table object shows errors such as `pk column different`, `pk column type mismatch`, or `invalid modify column`.
+  * A table's status automatically changes to "sync stopped." The tooltip on the table object shows errors such as `pk column different`, `pk column type mismatch`, or `invalid modify column`.
 
 * Cause
 
@@ -586,3 +586,5 @@ In the monitoring and alerting module, you can configure monitoring rules to tra
 * To prevent write conflicts on the target, only source tables with primary key (PK) fields are supported. Tables without a primary key cannot be synced.
 * The sync task will automatically create target tables. To ensure stable task execution and data correctness, avoid manually creating, modifying, or deleting target tables unless absolutely necessary.
 * Schema Evolution supports adding and removing columns on the source. Changing column types and automatically adding new tables are not currently supported.
+
+^

package/bin/skills/lakehouse-doc-en/references/navicat-mysql.md

@@ -1,3 +1,5 @@
+# Navicat Connection Guide
+
 Navicat (full name Navicat Premium) is a powerful database management tool widely used for database development, management, and maintenance. This article describes how to use Navicat to connect to Lakehouse via the MySQL protocol.
 
 # Prerequisites

package/bin/skills/lakehouse-doc-en/references/om-dynamic-table.md

@@ -8,26 +8,26 @@ Think of a Dynamic Table as an "automatically running data processing pipeline"
 
 ## Comparison with Other Table Types
 
-| Aspect | Dynamic Table | Materialized View | View | Table |
-|--------|--------|----------|----------|--------|
-| Definition | Efficient tool focused on data processing | Special view that pre-computes and stores query results | Stores no data; only saves the query definition | General-purpose storage object |
-| Data Storage | Yes | Yes | No | Yes |
-| Data Freshness | Adjustable; emphasizes processing flexibility | Requires near-real-time updates (ensures accurate rewriting) | Always latest data on each query | Determined by write timing |
-| Update Mechanism | Incremental computation; only processes changed data | Periodic full/incremental refresh | Real-time computation on each query | Manual DML |
-| Query Optimization | Does not rely on optimizer auto-rewriting | **Optimizer automatically identifies and uses pre-stored results** | Recomputed on every query | — |
-| DML Support | No | No | No | Yes |
-| Primary Use | Data processing pipelines (ODS → DWD → DWS) | Query acceleration, result reuse | Logic encapsulation for simple queries | Raw data storage |
-| Operations | Supports adding columns, version rollback | No complex operations | No complex operations | Flexible |
+| Aspect             | Dynamic Table                                        | Materialized View                                                  | View                                            | Table                          |
+| ------------------ | ---------------------------------------------------- | ------------------------------------------------------------------ | ----------------------------------------------- | ------------------------------ |
+| Definition         | Efficient tool focused on data processing            | Special view that pre-computes and stores query results            | Stores no data; only saves the query definition | General-purpose storage object |
+| Data Storage       | Yes                                                  | Yes                                                                | No                                              | Yes                            |
+| Data Freshness     | Adjustable; emphasizes processing flexibility        | Requires near-real-time updates (ensures accurate rewriting)       | Always latest data on each query                | Determined by write timing     |
+| Update Mechanism   | Incremental computation; only processes changed data | Periodic full/incremental refresh                                  | Real-time computation on each query             | Manual DML                     |
+| Query Optimization | Does not rely on optimizer auto-rewriting            | **Optimizer automatically identifies and uses pre-stored results** | Recomputed on every query                       | —                              |
+| DML Support        | No                                                   | No                                                                 | No                                              | Yes                            |
+| Primary Use        | Data processing pipelines (ODS → DWD → DWS)          | Query acceleration, result reuse                                   | Logic encapsulation for simple queries          | Raw data storage               |
+| Operations         | Supports adding columns, version rollback            | No complex operations                                              | No complex operations                           | Flexible                       |
 
 **When to use a Dynamic Table**: When you need to automatically compute and store results based on upstream tables. The typical scenario is the ODS → DWD → DWS data processing pipeline. Incremental computation only processes changed data, saving significant compute resources compared to full refreshes.
 
 **When not to use a Dynamic Table**:
 
-- Only need transparent acceleration of existing queries → use a Materialized View (the optimizer auto-rewrites queries to use pre-computed results)
-- Only need logic encapsulation without storing data → use a View
-- Data source is in an external database → use a sync job to write into a regular table; Dynamic Tables can only consume Lakehouse-internal tables
-- Need precise minute-level cron scheduling → use a Studio SQL job
-- Query contains heavy ORDER BY or complex window functions → incremental computation is limited; use a regular View + scheduling
+* Only need transparent acceleration of existing queries → use a Materialized View (the optimizer auto-rewrites queries to use pre-computed results)
+* Only need logic encapsulation without storing data → use a View
+* Data source is in an external database → use a sync job to write into a regular table; Dynamic Tables can only consume Lakehouse-internal tables
+* Need precise minute-level cron scheduling → use a Studio SQL job
+* Query contains heavy ORDER BY or complex window functions → incremental computation is limited; use a regular View + scheduling
 
 ## Incremental Computation Principles
 
@@ -36,9 +36,9 @@ Dynamic Tables work based on the Lakehouse's MVCC version management mechanism:
 1. **Version awareness**: On each refresh, the system records the source table's last version offset
 2. **Delta capture**: Compares the current version with the last version to identify INSERT/UPDATE/DELETE changes
 3. **Incremental execution**: Executes computation only on changed data; different operators handle changes differently:
-   - Filter/Project: processes only changed rows
-   - Join: joins changed rows with historical data from the right table
-   - Aggregate: merges changed rows with historical aggregation results
+   * Filter/Project: processes only changed rows
+   * Join: joins changed rows with historical data from the right table
+   * Aggregate: merges changed rows with historical aggregation results
 4. **Result merge**: Merges incremental results into the Dynamic Table via MERGE INTO
 
 The system automatically selects incremental or full refresh mode. When the SQL contains operators that don't support incremental processing (e.g., ORDER BY), when the source table change volume is too large, or on the first refresh, the system automatically falls back to full computation.
@@ -47,11 +47,11 @@ The system automatically selects incremental or full refresh mode. When the SQL
 
 Dynamic Tables support three scheduling approaches:
 
-| Scheduling Approach | Suitable Scenario | Advantages | Disadvantages |
-|---------|---------|------|------|
-| DDL-defined refresh interval (`REFRESH INTERVAL`) | Simple scenarios, quick deployment | Simple to use; no external tools needed | No upstream/downstream dependency support; minimum interval is 1 minute |
-| Lakehouse Studio scheduling | Multi-layer DT pipelines requiring dependency control | Visual configuration; supports task dependencies (trigger B after A completes); failure/timeout alerts | Minimum interval is 1 minute |
-| Third-party scheduling engine | Existing scheduling infrastructure requiring flexible control | No interval restrictions; integrates with existing scheduling systems | Introduces external dependencies; requires self-maintenance |
+| Scheduling Approach                               | Suitable Scenario                                             | Advantages                                                                                             | Disadvantages                                                           |
+| ------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- |
+| DDL-defined refresh interval (`REFRESH INTERVAL`) | Simple scenarios, quick deployment                            | Simple to use; no external tools needed                                                                | No upstream/downstream dependency support; minimum interval is 1 minute |
+| Lakehouse Studio scheduling                       | Multi-layer DT pipelines requiring dependency control         | Visual configuration; supports task dependencies (trigger B after A completes); failure/timeout alerts | Minimum interval is 1 minute                                            |
+| Third-party scheduling engine                     | Existing scheduling infrastructure requiring flexible control | No interval restrictions; integrates with existing scheduling systems                                  | Introduces external dependencies; requires self-maintenance             |
 
 > ⚠️ **Note**: The refresh interval must be greater than the duration of a single refresh run; otherwise jobs will queue up. Use `SHOW DYNAMIC TABLE REFRESH HISTORY` to check refresh durations.
 
@@ -109,9 +109,10 @@ SELECT * FROM dws_category_sales;
 **Symptom**: Refresh status shows `QUEUED`; data lag keeps growing.
 
 **Solution**:
-- Use `SHOW DYNAMIC TABLE REFRESH HISTORY` to check refresh durations
-- The refresh interval should be 1.5–2x the single refresh duration
-- If refresh duration keeps growing, incremental computation may have degraded to full computation
+
+* Use `SHOW DYNAMIC TABLE REFRESH HISTORY` to check refresh durations
+* The refresh interval should be 1.5–2x the single refresh duration
+* If refresh duration keeps growing, incremental computation may have degraded to full computation
 
 ### Issue 2: Non-Deterministic Functions Cause Inconsistent Results
 
@@ -120,42 +121,44 @@ SELECT * FROM dws_category_sales;
 **Symptom**: Function return values differ on each refresh, potentially causing incremental computation results to deviate from expectations.
 
 **Solution**:
-- Avoid non-deterministic functions in DT definitions
-- For day-based filtering, use parameterized DT + `SESSION_CONFIGS()['dt.args.bizdate']`; see [Dynamic Table Parameterized Definitions](dynamic-table-parameters.md)
-- If you need to record refresh time, use `CURRENT_TIMESTAMP()` in downstream queries rather than in the DT definition
+
+* Avoid non-deterministic functions in DT definitions
+* For day-based filtering, use parameterized DT + `SESSION_CONFIGS()['dt.args.bizdate']`; see [Dynamic Table Parameterized Definitions](dynamic-table-parameters.md)
+* If you need to record refresh time, use `CURRENT_TIMESTAMP()` in downstream queries rather than in the DT definition
 
 ### Issue 3: Multi-Layer Pipeline Latency Accumulation
 
-**Problem**: DT_A (5-minute refresh) → DT_B (1-minute refresh); expected DT_B latency is 1 minute.
+**Problem**: DT\_A (5-minute refresh) → DT\_B (1-minute refresh); expected DT\_B latency is 1 minute.
 
-**Symptom**: DT_B actual latency is at least 5 minutes.
+**Symptom**: DT\_B actual latency is at least 5 minutes.
 
 **Solution**:
-- The upstream DT's refresh frequency determines the minimum latency achievable downstream
-- Use Studio task dependencies (trigger B after A completes) to avoid polling waits
-- Total pipeline latency = sum of refresh intervals across all layers
+
+* The upstream DT's refresh frequency determines the minimum latency achievable downstream
+* Use Studio task dependencies (trigger B after A completes) to avoid polling waits
+* Total pipeline latency = sum of refresh intervals across all layers
 
 ## Usage Restrictions
 
-- **Non-deterministic functions not supported**: DT definitions cannot use `RANDOM()`, `CURRENT_TIMESTAMP()`, `CURRENT_DATE()`, or other non-deterministic functions; otherwise incremental refresh results are unpredictable. For time-based filtering, use parameterized DT (`SESSION_CONFIGS()['dt.args.bizdate']`); see [Dynamic Table Parameterized Definitions](dynamic-table-parameters.md).
-- **Direct data modification not supported**: You cannot run `UPDATE`, `DELETE`, or `TRUNCATE` on a Dynamic Table. Data in a Dynamic Table can only be updated through the refresh mechanism.
+* **Non-deterministic functions not supported**: DT definitions cannot use `RANDOM()`, `CURRENT_TIMESTAMP()`, `CURRENT_DATE()`, or other non-deterministic functions; otherwise incremental refresh results are unpredictable. For time-based filtering, use parameterized DT (`SESSION_CONFIGS()['dt.args.bizdate']`); see [Dynamic Table Parameterized Definitions](dynamic-table-parameters.md).
+* **Direct data modification not supported**: You cannot run `UPDATE`, `DELETE`, or `TRUNCATE` on a Dynamic Table. Data in a Dynamic Table can only be updated through the refresh mechanism.
 
 ## Cost Implications
 
 ### Compute Cost
 
-- Each refresh consumes VCluster CRU resources
-- Higher refresh frequency means greater CRU consumption:
-  - `1 DAY`: 1 refresh per day — lowest cost
-  - `1 HOUR`: 24 refreshes per day
-  - `1 MINUTE`: 1440 refreshes per day — evaluate carefully
-- Incremental refresh saves significantly more resources than full refresh (verify with actual testing)
+* Each refresh consumes VCluster CRU resources
+* Higher refresh frequency means greater CRU consumption:
+  * `1 DAY`: 1 refresh per day — lowest cost
+  * `1 HOUR`: 24 refreshes per day
+  * `1 MINUTE`: 1440 refreshes per day — evaluate carefully
+* Incremental refresh saves significantly more resources than full refresh (verify with actual testing)
 
 ### Storage Cost
 
-- Dynamic Tables store computed results and consume storage space
-- Time Travel is supported; the default retention is 1 day of historical versions, which increases storage
-- Time Travel retention can be adjusted with the following command (range: 0–90 days):
+* Dynamic Tables store computed results and consume storage space
+* Time Travel is supported; the default retention is 1 day of historical versions, which increases storage
+* Time Travel retention can be adjusted with the following command (range: 0–90 days):
 
 ```sql
 ALTER TABLE dws_category_sales SET PROPERTIES ('data_retention_days'='7');
@@ -182,23 +185,23 @@ SHOW DYNAMIC TABLE REFRESH HISTORY WHERE name = 'dws_category_sales' LIMIT 10;
 
 Field descriptions:
 
-| Field | Description |
-|------|------|
-| `workspace_name` | Workspace name |
-| `schema_name` | Schema name |
-| `name` | Dynamic Table name |
-| `virtual_cluster` | Cluster used for the refresh |
-| `start_time` | Refresh start time |
-| `end_time` | Refresh end time |
-| `duration` | Refresh duration |
-| `state` | Job state: `setup` / `resuming cluster` / `queued` / `running` / `SUCCEED` / `FAILED` |
-| `refresh_trigger` | Trigger type: `MANUAL` (user-triggered, including Studio scheduling) / `LH_SCHEDULED` (Lakehouse auto-scheduling) |
-| `suspended_reason` | Reason scheduling is suspended (null when not suspended) |
-| `refresh_mode` | Refresh mode: `INCREMENTAL` / `FULL` / `NO_DATA` (no changes) |
-| `error_message` | Error message on failure |
-| `source_tables` | List of source tables the Dynamic Table depends on (JSON format) |
-| `stats` | Incremental refresh stats: `rows_inserted` / `rows_deleted` (values are string type) |
-| `job_id` | Job ID; click to view the Job Profile and incremental execution plan |
+| Field              | Description                                                                                                       |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------- |
+| `workspace_name`   | Workspace name                                                                                                    |
+| `schema_name`      | Schema name                                                                                                       |
+| `name`             | Dynamic Table name                                                                                                |
+| `virtual_cluster`  | Cluster used for the refresh                                                                                      |
+| `start_time`       | Refresh start time                                                                                                |
+| `end_time`         | Refresh end time                                                                                                  |
+| `duration`         | Refresh duration                                                                                                  |
+| `state`            | Job state: `setup` / `resuming cluster` / `queued` / `running` / `SUCCEED` / `FAILED`                             |
+| `refresh_trigger`  | Trigger type: `MANUAL` (user-triggered, including Studio scheduling) / `LH_SCHEDULED` (Lakehouse auto-scheduling) |
+| `suspended_reason` | Reason scheduling is suspended (null when not suspended)                                                          |
+| `refresh_mode`     | Refresh mode: `INCREMENTAL` / `FULL` / `NO_DATA` (no changes)                                                     |
+| `error_message`    | Error message on failure                                                                                          |
+| `source_tables`    | List of source tables the Dynamic Table depends on (JSON format)                                                  |
+| `stats`            | Incremental refresh stats: `rows_inserted` / `rows_deleted` (values are string type)                              |
+| `job_id`           | Job ID; click to view the Job Profile and incremental execution plan                                              |
 
 ### Modifying and Dropping
 
@@ -217,7 +220,9 @@ UNDROP TABLE dws_category_sales;
 
 ## Related Documentation
 
-- [Dynamic Table Overview](dynamic_table_summary.md) — Core concepts and working principles
-- [CREATE DYNAMIC TABLE](create-dynamic-table.md) — Complete syntax
-- [Incremental Computation](incremental-computing.md) — Incremental refresh principles
-- [Real-Time Pipeline Selection Guide](realtime-pipeline-selection-guide.md) — Choosing between Pipe, Stream, and Dynamic Table
+* [Dynamic Table Overview](dynamic_table_summary.md) — Core concepts and working principles
+* [CREATE DYNAMIC TABLE](create-dynamic-table.md) — Complete syntax
+* [Incremental Computation](incremental-computing.md) — Incremental refresh principles
+* [Real-Time Pipeline Selection Guide](realtime-pipeline-selection-guide.md) — Choosing between Pipe, Stream, and Dynamic Table
+
+^

package/bin/skills/lakehouse-doc-en/references/om-vcluster.md

@@ -63,6 +63,8 @@ ALTER VCLUSTER my_gp_cluster SUSPEND;
 SHOW VCLUSTERS;
 ```
 
+> ⚠️ **Note**: VCluster names are automatically converted to **uppercase** when stored (unlike table names and schema names, which are lowercased). For example, a cluster created as `my_gp_cluster` will have the actual name `MY_GP_CLUSTER`. References are case-insensitive, but `SHOW VCLUSTERS` always displays uppercase names.
+
 ## Cost Implications
 
 ### Compute Cost

package/bin/skills/lakehouse-doc-en/references/open-api-create-session.md

@@ -0,0 +1,79 @@
+# CreateSession - Create a Conversation Session
+
+Create a new conversation session (Session) to organize one or more question-and-answer interactions.
+
+## Interface Description
+
+A Session represents a conversation context. After creation, a `sessionId` is returned. Subsequent question requests must be associated with a Session.
+
+If the client already has a reusable `sessionId`, this step can be skipped and a question can be submitted directly.
+
+### Usage Notes
+
+- A single Session can contain multiple questions.
+- A Session can be reused multiple times; you do not need to create a new one for every question.
+
+## Request Method
+
+```
+POST /open/session/safe_new?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, corresponding to a dataset |
+| title | Body | String | No | Session title, used to identify the Session |
+| loginToken | Query + Body | String | Yes | Authentication Token obtained via GenerateAuthToken |
+
+## Response Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| success | Boolean | Whether the request was successful |
+| data | Integer | The sessionId of the newly created session |
+
+## Request Example
+
+```http
+POST /open/session/safe_new
+Content-Type: application/json
+
+{
+  "tenantId": 10,
+  "userId": 1,
+  "domainId": 106,
+  "title": "Q1 Sales Analysis",
+  "loginToken": "eyJhbGciOiJIUzI1NiJ9..."
+}
+```
+
+## Response Example
+
+Successful response:
+
+```json
+{
+  "success": true,
+  "data": 4729
+}
+```
+
+The value `4729` in `data` is the newly created `sessionId`.
+
+## Error Codes
+
+| Error Code | Description |
+|------------|-------------|
+| success=false | Token is invalid, parameters are missing, or insufficient permissions |
+
+## Related Documentation
+
+- [GenerateAuthToken](open-api-generate-auth-token) — Previous step: obtain authentication Token
+- [Text2InsightQuery](open-api-text2insight-query) — Next step: submit a data analysis request
+- [Quick Start](open-api-quick-start) — Complete end-to-end example

package/bin/skills/lakehouse-doc-en/references/open-api-generate-auth-token.md

@@ -0,0 +1,63 @@
+# GenerateAuthToken - Obtain Authentication Token
+
+Obtain an authentication Token for subsequent API calls using an application secret key (appSecretKey).
+
+## Interface Description
+
+Before calling any business interface in Open Text2Insight, you must first use this interface to obtain a login Token. This Token serves as the identity credential for all subsequent requests.
+
+### Usage Notes
+
+- The appSecretKey is generated and distributed by the platform administrator in the backend.
+- The Token has an expiration time; you must obtain a new one after it expires.
+- Keep your appSecretKey secure to prevent leakage.
+
+## Request Method
+
+```
+GET /open/api/v1/appSecretKey/generateAuthToken
+```
+
+## Request Parameters
+
+| Parameter | Location | Type | Required | Description |
+|-----------|----------|------|----------|-------------|
+| appSecretKey | Query | String | Yes | Application secret key, assigned by the administrator |
+
+## Response Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| success | Boolean | Whether the request was successful |
+| data.token | String | Authentication Token, used for subsequent interface calls |
+
+## Request Example
+
+```http
+GET /open/api/v1/appSecretKey/generateAuthToken?appSecretKey=your_secret_key_here
+```
+
+## Response Example
+
+Successful response:
+
+```json
+{
+  "success": true,
+  "data": {
+    "token": "eyJhbGciOiJIUzI1NiJ9..."
+  }
+}
+```
+
+## Error Codes
+
+| Error Code | Description |
+|------------|-------------|
+| success=false | appSecretKey is invalid or has expired |
+
+## Related Documentation
+
+- [Open API Overview](open-api-overview) — Interface list and general description
+- [Quick Start](open-api-quick-start) — Complete call flow after obtaining the Token
+- [CreateSession](open-api-create-session) — Next step: create a session using the Token