@clickzetta/cz-cli-darwin-arm64 0.3.94 → 0.3.96

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

@@ -0,0 +1,199 @@
+# View
+
+A View is a **virtual table that stores no data** — it is essentially a saved SQL query. Each time a view is queried, the system executes the underlying SQL in real time and returns the results.
+
+Think of a view as a "saved query template" — you write a complex SQL statement, give it a name, and query it by that name from then on. Unlike a Materialized View: a Materialized View pre-computes and stores results (uses storage but queries are fast), while a View stores no data at all (zero storage cost but recomputed on every query).
+
+## Selection Reference
+
+| Aspect | View | Materialized View | Dynamic Table |
+|--------|------|----------|--------|
+| Data storage | No storage | Stores pre-computed results | Stores computed results |
+| Query performance | Same as underlying tables | High (reads results directly) | High (reads results directly) |
+| Data freshness | Real-time | Within refresh interval | Within refresh interval |
+| Suitable scenarios | Logic encapsulation, permission isolation | Query acceleration | Data processing pipelines |
+
+**When to use a View**: Encapsulating complex JOIN logic, exposing only certain columns externally (permission isolation), and scenarios where data storage is not needed.
+
+**When not to use a View**: If query performance is a bottleneck → use a Materialized View. If you need automatic incremental computation → use a Dynamic Table.
+
+## Core Features
+
+**Zero storage cost**: A view only saves the SQL definition and occupies no storage space.
+
+**Real-time data**: Every query against a view executes the underlying SQL in real time, returning the latest data.
+
+**Read-only**: Views do not support DML operations such as INSERT, UPDATE, or DELETE.
+
+**No Time Travel support**: Views cannot query historical versions of data.
+
+## Quick Examples
+
+### Encapsulating Complex JOINs
+
+```sql
+-- Create source tables
+CREATE TABLE IF NOT EXISTS users (
+    user_id   BIGINT,
+    username  STRING,
+    city      STRING,
+    phone     STRING
+);
+
+CREATE TABLE IF NOT EXISTS orders (
+    order_id  BIGINT,
+    user_id   BIGINT,
+    amount    DECIMAL(10,2)
+);
+
+-- Insert test data
+INSERT INTO users VALUES (1, 'Alice', 'Beijing', '13800000001');
+INSERT INTO orders VALUES (101, 1, 99.00);
+
+-- Create a view: encapsulate JOIN logic
+CREATE VIEW v_order_detail AS
+SELECT u.username, o.order_id, o.amount
+FROM users u
+JOIN orders o ON u.user_id = o.user_id;
+
+-- Query the view
+SELECT * FROM v_order_detail;
+-- Result:
+-- +----------+----------+--------+
+-- | username | order_id | amount |
+-- +----------+----------+--------+
+-- | Alice    | 101      | 99.00  |
+-- +----------+----------+--------+
+```
+
+### Permission Isolation (Hiding Sensitive Columns)
+
+```sql
+-- Create a view: expose only public fields, hide sensitive columns like phone
+CREATE VIEW v_user_public AS
+SELECT user_id, username, city
+FROM users;
+
+-- View the view's structure
+DESC VIEW v_user_public;
+-- Result:
+-- +-------------+-----------+---------+
+-- | column_name | data_type | comment |
+-- +-------------+-----------+---------+
+-- | user_id     | bigint    |         |
+-- | username    | string    |         |
+-- | city        | string    |         |
+-- +-------------+-----------+---------+
+```
+
+### Permission Isolation (Row-Level Data Filtering)
+
+```sql
+-- Source table contains sales data for all regions
+CREATE TABLE IF NOT EXISTS sales_all_regions (
+    region      STRING,
+    salesperson STRING,
+    amount      DECIMAL(10,2)
+);
+
+INSERT INTO sales_all_regions VALUES
+    ('North', 'Alice', 5000),
+    ('North', 'Bob', 3000),
+    ('South', 'Carol', 4000),
+    ('South', 'Dave', 6000);
+
+-- Create a view for the North region sales team — they can only see North region data
+CREATE VIEW v_sales_north AS
+SELECT salesperson, amount
+FROM sales_all_regions
+WHERE region = 'North';
+
+-- North region sales team queries the view
+SELECT * FROM v_sales_north;
+-- Result:
+-- +-------------+---------+
+-- | salesperson | amount  |
+-- +-------------+---------+
+-- | Alice       | 5000.00 |
+-- | Bob         | 3000.00 |
+-- +-------------+---------+
+
+-- Similarly, create v_sales_south for the South region — same table, different rows for different users
+```
+
+> 💡 **Tip**: **View vs. Dynamic Data Masking**: Views are a quick way to implement row- and column-level permission isolation with no extra configuration. For finer-grained dynamic access control (e.g., automatically masking sensitive columns based on user roles), use the Lakehouse's [Dynamic Data Masking](om-dynamic-mask.md).
+
+## Common Issues
+
+### Issue 1: View Performance Degrades as Underlying Data Grows
+
+**Problem**: The view's underlying query involves complex JOINs or aggregations, and query performance degrades as the underlying table data grows.
+
+**Symptom**: View queries are fast with small data volumes, but time out after data reaches the TB scale.
+
+**Solution**:
+- Views are suited for logic encapsulation, not performance optimization
+- When query performance becomes a bottleneck, switch to a Materialized View (pre-computes and stores results)
+- Or switch to a Dynamic Table (incremental computation with automatic refresh)
+
+### Issue 2: Underlying Table Schema Changes Invalidate the View
+
+**Problem**: A table the view depends on is dropped, or a column name is changed.
+
+**Symptom**: Querying the view produces `table or view not found` or `column not found` errors.
+
+**Solution**:
+- Views do not check whether the underlying tables exist; a successful creation does not guarantee permanent validity
+- Before modifying an underlying table's schema, use `DESC VIEW` to identify which views depend on it
+- Add COMMENT to important views to document their dependencies
+
+### Issue 3: Attempting DML Operations on a View
+
+**Problem**: Running `INSERT INTO v_user_public VALUES (...)` on a view.
+
+**Symptom**: Error: `view is read-only`.
+
+**Solution**:
+- Views are read-only and do not support INSERT/UPDATE/DELETE
+- To write data, operate directly on the underlying base table
+
+## Cost Implications
+
+### Storage Cost
+
+- A view only saves the SQL definition — essentially zero storage cost
+
+### Compute Cost
+
+- Every query against a view re-executes the underlying SQL, consuming VCluster CRU
+- Complex views (multi-table JOINs, aggregations) are fully recomputed on every query, which can be costly
+
+> 💡 **Tip**: For detailed billing rules, refer to the [Billing Documentation](billing.md).
+
+## Lifecycle Management
+
+```
+Create View → Query → Underlying Table Changes → View Invalidated/Rebuilt → Drop View
+     ↓           ↓              ↓                         ↓                     ↓
+  Save SQL   Real-time exec  Column/table changes    Error or wrong results   DROP VIEW
+```
+
+### Creating and Dropping
+
+```sql
+-- Create a view
+CREATE VIEW my_view AS SELECT ...;
+
+-- View the view's definition
+DESC VIEW my_view;
+
+-- Drop the view
+DROP VIEW my_view;
+```
+
+## Related Documentation
+
+- [CREATE VIEW](create-view.md) — Complete syntax
+- [Materialized View](materializedview.md) — When you need to store pre-computed results
+- [Dynamic Table](om-dynamic-table.md) — When you need incremental computation with automatic refresh
+- [Semantic View](om-semantic-view.md) — Semantic layer for business analysis

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

@@ -0,0 +1,39 @@
+# Workspace
+
+A workspace is the fundamental unit for **organizing and isolating resources** in Singdata Lakehouse. Multiple workspaces can be created under a single service instance, and workspaces are isolated from each other by default — tables, views, tasks, and compute clusters all belong to a specific workspace and are invisible across different workspaces by default.
+
+You can think of a workspace as a "project space": isolate development and production environments using different workspaces, or let different business teams each use their own independent workspace.
+
+## What a Workspace Does
+
+| Capability | Description |
+|------|------|
+| Resource Isolation | Tables, views, tasks, and compute clusters all belong to a workspace and do not interfere with each other |
+| Permission Management | Control member access scope through workspace roles |
+| Multi-Environment Management | Isolate dev/test/prod environments with independent workspaces |
+| Cross-Workspace Data Sharing | Enable data access between different workspaces through authorization |
+
+## Organization Hierarchy
+
+```
+Service Instance
+└── Workspace
+    └── Schema
+        └── Tables, views, functions, and other data objects
+```
+
+Users must join a workspace and be granted a role before they can use its resources.
+
+## Workspace Roles
+
+| Role | Code | Default Permissions |
+|------|------|---------|
+| Workspace Admin | `workspace_admin` | Full permissions to manage members, roles, tasks, data, and compute clusters |
+| Workspace Developer | `workspace_dev` | Manage tasks and instances; use permissions for data and compute clusters |
+| Workspace Member | `workspace_user` | View tasks and instances; cannot access data and compute clusters |
+
+## Related Operations
+
+- [Manage Workspaces](workspace-introduction.md) — Create, join, manage members
+- [Schema](om-schema.md) — Namespace within a workspace
+- [Cross-Workspace Data Sharing](data_sharing_between_accounts_guide.md)

package/bin/skills/lakehouse-doc-en/references/opensource/travel.md

@@ -0,0 +1,126 @@
+# ClickZetta Travel: Data Migration and SQL Translation Tool
+
+## Introduction
+
+ClickZetta Travel is an open-source tool meticulously crafted by the Singdata development team, designed to help users easily migrate from other data systems to ClickZetta Lakehouse. It offers a range of powerful features, including:
+- Translating other SQL dialects into SQL compatible with ClickZetta Lakehouse.
+- Executing SQL on both the source data system and ClickZetta Lakehouse and comparing the consistency of the result sets.
+- An easy-to-use Web UI that provides an intuitive interface.
+- Command-line tools that support batch SQL migration.
+
+## Installation and Startup
+
+### Installation Steps
+
+1. Ensure Docker is installed.
+2. Obtain the Docker image for ClickZetta Travel using the following command:
+```shell
+# Get the image
+docker pull clickzetta/clickzetta-travel:dev
+```
+3. Create a folder named `travel` locally to store the configuration and data needed for the evaluation:
+```shell
+mkdir travel
+cd travel
+```
+### Start Web UI
+
+Run the following command to start the ClickZetta Travel Web UI:
+```shell
+docker run --rm --name cztravel -v $(pwd):/mnt/userdata -p 8501:8501 clickzetta/clickzetta-travel:dev
+```
+Access http://localhost:8501/unify to use the Web UI.
+
+## Usage
+
+### Web Page Interactive Evaluation
+
+#### Transpile SQL
+
+1. Open http://localhost:8501/unify in your browser.
+2. Select the data platform you are using.
+3. Enter the SQL to be transpiled in the input box.
+4. Use the shortcut keys (hinted at the bottom right of the input box) or let the input box lose focus. Once the input is effective, the page will automatically display the original and transpiled SQL side by side.
+
+![transpile screenshot](travel_screenshot_transpile.png)
+
+#### Execute SQL and Compare Results
+
+1. Configure the database connection.
+   - Expand the config template on the page to see the configuration file template.
+   - Upload the edited configuration file through the page, or create a new conf subdirectory in the host machine's data directory and prepare the configuration file there. After refreshing the page, you can select it from the select config file section.
+   - If the configuration file is correct, the page will display a connection success message.
+2. Select the verification method and click the Validate button to run the SQL and verify the result set.
+   - Basic verification: Verification based on limited basic statistical information.
+   - Multidimensional verification: Verification based on rich statistical information.
+   - Line by line verification: Line-by-line verification.
+
+![validate screenshot](travel_screenshot_validate.png)
+
+### Command Line Batch Evaluation
+
+Collect the SQL statements to be evaluated and store the collected information in one or more files in the data directory. When a file contains multiple SQLs, they need to be separated by semicolons (;).
+```shell
+# Enter the docker command line environment
+docker exec -it cztravel /bin/bash
+# Switch to the data directory
+cd /mnt/userdata
+```
+The batch evaluation command provided in the command-line environment is `travel`. This tool
+- Accepts one or more SQL files with content separated by semicolons
+- Identifies, splits, and numbers the SQL in the input files, translates them into ClickZetta Lakehouse SQL, and attempts to execute these SQL on the Lakehouse
+- Produces a data directory, including evaluation summaries and runtime data. The runtime data includes successfully executed SQL, untranslatable SQL, and intelligently categorized execution-failed SQL
+- You can get the latest help information through `travel --help`.
+
+Example:
+```shell
+root@bce68cf855b8:/mnt/userdata#> travel -c conf/cz_conf.json batch-0906.sql
+
+# Screen display continuously outputs running logs until the final running summary is given
+summary:
+original sql      : 777
+transpiled        : 777, 100.00%
+transpile failed  : 0, 0.00%
+empty or set sql  : 1
+valid for running : 776
+run succeed       : 763, 98.32%
+run failed        : 13, 1.68%
+
+classified failed reasons:
+reason_0        1       submit sql job failed:SQL job execute failed.Error:CZLH-00000:Failed to generate call action, function not found: IN(bin,bin...)->b
+reason_1        2       submit sql job failed:SQL job execute failed.Error:CZLH-22007:DateTimeFormatter: pattern not supported ZONE_OFFSET_X - z : +0000; -08; -0830; -08:30; -083015; -08:30:15;. Detail  taskId 0, vertex name=stg4, vertexId=2023091814422045379827447_48514-V4
+reason_2        2       submit sql job failed:SQL job execute failed.Error:CZLH-22007:DateTimeFormatter: unknown pattern letter: W. Detail  taskId 0, vertex name=stg0, vertexId=2023091814365582826010390_48392-V0
+reason_3        2       submit sql job failed:SQL job execute failed.Error:CZLH-42000:[1,170] Semantic analysis exception - operator not found, string - string
+...
+
+# 2023-10-10_22-24-24 is the data directory produced by this run
+# The last symbolic link always points to the data directory of the last run
+root@bce68cf855b8:/mnt/userdata#> ls -l
+total 18408
+drwxr-xr-x@ 36 robert  staff   1.1K 10 10 22:48 2023-10-10_22-24-24/
+-rw-r--r--@  1 robert  staff   9.0M 10 10 22:22 batch-0906.sql
+drwxr-xr-x@  6 robert  staff   192B 10  8 19:03 conf/
+lrwxr-xr-x@  1 robert  staff    19B 10 10 22:48 last@ -> 2023-10-10_22-24-24
+
+# The data directory structure is shown below, and the data can be directly browsed and processed from the host machine
+robert@Roberts-MBP ~/D/travel> tree last
+last/
+├── log.txt # All execution logs
+├── reason_0
+├── reason_1
+│   ├── run.452.clickzetta.sql # Execution content of SQL No. 452 in Lakehouse
+│   ├── run.452.doris.sql      # Original information of SQL No. 452
+│   ├── run.776.clickzetta.sql
+│   └── run.776.doris.sql
+├── reason_2
+...
+├── success # Successfully executed SQL, can be used for subsequent stress testing
+└── summary.txt # Summary
+
+# The .clickzetta.sql file records the transpiled SQL content executed in Lakehouse, job id, reasons for failure, etc.
+robert@Roberts-MBP ~/D/travel> cat last/reason_1/run.452.clickzetta.sql
+WITH dt AS (SELECT ... DATE_FORMAT(`t1`.`created_at`, '%x') AS p, ... LIMIT 1000
+
+-- exception for job_id: 2023091814422045379827447
+-- submit sql job failed:SQL job execute failed.Error:CZLH-22007:DateTimeFormatter: pattern not supported ZONE_OFFSET_X - z : +0000; -08; -0830; -08:30; -083015; -08:30:15;. Detail  taskId 0, vertex name=stg4, vertexId=2023091814422045379827447_48514-V4
+```

package/bin/skills/lakehouse-doc-en/references/operation-maintenance.md

@@ -0,0 +1,149 @@
+## Task Operations and Instance Operations
+
+The Operations Center provides management operations for tasks and instances. The tasks managed by the Operations Center include manually triggered tasks and periodically scheduled tasks, along with their corresponding instances, for centralized management.
+
+### Task Operations
+#### Task List
+Click "Task Operations" in the left navigation to enter the task list page. The task list provides a summary display of tasks in all workspaces under the currently activated services.
+![](.topwrite/assets/image_1668864727926.png)
+
+##### Task List Content
+In the list, you can view key attributes such as task name, task ID, workspace, task status, task type, etc.
+
+##### Task List Operations
+In the task list, you can select single or multiple tasks for quick operations.
+![](.topwrite/assets/image_1668864740236.png)
+Single Task
+- Pause
+  - Can only be operated on tasks that are not in a paused state. After the operation, the task's scheduling attribute will be set to "Pause Scheduling," meaning no more task instances will be generated or run.
+- Start
+  - Can only be operated on tasks that are in a paused state. After the operation, the task's scheduling attribute will be restored to "Normal Scheduling," meaning task instances will be generated and run.
+- Delete
+  - This operation will take the task offline from the Operations Center, reverting the task to the "Unsubmitted" state in the file.
+Multiple Tasks, Batch Operations
+- Batch Start
+  - Batch operation on selected tasks, restoring the task's scheduling attribute to "Normal Scheduling."
+- Batch Pause
+  - Batch operation on selected tasks, setting the task's scheduling attribute to "Pause Scheduling."
+
+##### Task List Filtering
+At the top of the task list, you can filter tasks based on their attributes as needed.
+- More Filters
+  - Clicking this will expand more filtering options.
+![](.topwrite/assets/image_1668864750584.png)
+- Reset Filters
+  - Clicking this will reset and clear all currently given filtering conditions.
+- Refresh
+  - Refresh the list to retrieve it again based on the given conditions.
+
+#### Task Details
+From the task list, click the task name link to enter the task details page. On this page, you can view basic information, upstream and downstream dependency graphs, task instances, and code.
+
+##### Basic Information
+In this area, you can view the basic information of the task.
+![](.topwrite/assets/image_1668864765633.png)
+
+##### Dependency Graph
+In the dependency graph, you can view the directly upstream tasks that the current task depends on and the directly downstream tasks that depend on it.
+- Search
+  - By providing a keyword of the task name or task ID, you can quickly locate the task node on the graph. The matching method used is "contains."
+- Refresh
+  - Clicking this will reload the entire dependency graph.
+![](.topwrite/assets/image_1668864772611.png)
+
+##### Task Instances
+In the task instance area, all task instances generated by the current task will be displayed for all time ranges.
+![](.topwrite/assets/image_1668864779204.png)
+For a single task instance, you can perform basic control operations:
+- Stop
+  - Can be operated to stop instances that are not running.
+- Rerun
+  - Can be operated to rerun instances that have reached a terminal state, meaning the instance will be run again.
+Code
+The node code area displays the latest version of the code for the current task.
+![](.topwrite/assets/image_1668864785641.png)
+
+##### Task Operations
+On the task details page, you can pause, start, or delete the task, with the same meaning and effect as the operations provided in the list.
+- Pause
+  - Can only be operated on tasks that are not in a paused state. After the operation, the task's scheduling attribute will be set to "Pause Scheduling," meaning no more task instances will be generated or run.
+- Start
+  - Can only be operated on tasks that are in a paused state. After the operation, the task's scheduling attribute will be restored to "Normal Scheduling," meaning task instances will be generated and run.
+- Delete
+  - This operation will take the task offline from the Operations Center, reverting the task to the "Unsubmitted" state in the file.
+
+### Instance Operations
+#### Instance List
+Click "Instance Operations" in the left navigation to enter the instance list page. The instance list provides a summary display of task instances in all workspaces under the currently activated service instances.
+![](.topwrite/assets/image_1668864794756.png)
+
+##### Instance List Content
+In the list, you can view key attributes such as instance ID, corresponding task name, instance type, workspace, instance status, scheduled time, execution time, and completion time.
+
+##### Instance List Filtering
+At the top of the instance list, you can filter instances based on their attributes as needed.
+- More Filters
+  - Clicking this will expand more filtering options.
+![](.topwrite/assets/image_1668864807533.png)
+- Reset Filters
+  - Clicking this will reset and clear all currently given filtering conditions.
+- Refresh
+  - Refresh the list to retrieve it again based on the given conditions.
+
+##### Instance List Operations
+In the instance list, you can select single or multiple task instances for quick operations.
+![](.topwrite/assets/image_1668864815341.png)
+Single Task Instance
+- Pause
+- Pause
+  - Only operable for task instances that are not in a paused state. After the operation, the scheduling attribute of the task instance will be set to "pause scheduling", meaning the task instance will no longer be scheduled to run.
+- Resume
+  - Only operable for task instances that are in a paused state. After the operation, the scheduling attribute of the task instance will be restored to "normal scheduling", meaning the task instance will run according to the scheduled time.
+- Terminate
+  - Only operable for task instances that are running. After the operation, the task instance will be terminated, and its status will be set to failed.
+- Rerun
+  - Only operable for task instances that have completed running. After the operation, the task instance will be rerun.
+- Set to Success
+  - Only operable for task instances that have failed. After the operation, the task instance will be forcibly set to success. This can be used in emergency maintenance scenarios where it is determined that even if the current task instance fails, it does not affect the correctness of downstream task data, thus removing the blockage for downstream task instances.
+
+Multiple task instances, batch operations
+- Pause
+  - Same as single operation. Note that it is only operable for task instances that are not in a paused state.
+- Resume
+  - Same as single operation. Note that it is only operable for task instances that are in a paused state.
+- Terminate
+  - Same as single operation. Note that it is only operable for task instances that are running.
+- Rerun
+  - Same as single operation. Note that it is only operable for task instances that have completed running.
+- Set to Success
+  - Same as single operation. Note that it is only operable for task instances that have failed.
+
+#### Instance Details
+From the instance list, click the instance ID link to enter the details page of the task instance. On this page, you can view basic information, upstream and downstream dependency graphs, task instances, and code.
+
+##### Basic Information
+In this area, you can view the basic information of the task instance.
+![](.topwrite/assets/image_1668864827160.png)
+
+##### Dependency Graph
+On the dependency graph, you can view the direct upstream task instances that the current task instance depends on, to quickly determine whether the current task instance can be normally scheduled.
+- Search
+  - By providing a keyword of the task name or instance ID, you can quickly locate the task instance node on the graph. The matching method used is "contains".
+- Refresh
+  - Click to reload the entire dependency graph.
+![](.topwrite/assets/image_1668864833952.png)
+
+##### Code
+The code area displays the version of the code used by the current task instance at runtime. Note that this may not be the latest version of the task code.
+![](.topwrite/assets/image_1668864841562.png)
+
+##### Execution Log
+The execution log area displays all logs of the current instance execution, including logs generated after the task instance is rerun. Click the + icon on the left side of the list to expand and view detailed content.
+![](.topwrite/assets/image_1668864848251.png)
+
+##### Operation Log
+The operation log area displays records of operations performed on the current instance.
+![](.topwrite/assets/image_1668864855135.png)
+
+##### Instance Operations
+On the task instance details page, you can perform pause, resume, terminate, rerun, and set to success operations on the task instance. The meanings and functions are the same as the operations provided in the list.

package/bin/skills/lakehouse-doc-en/references/optimizing-computing-resources.md

@@ -0,0 +1 @@
+^

package/bin/skills/lakehouse-doc-en/references/org-hierarchy.md

@@ -0,0 +1,56 @@
+# Organization Hierarchy
+
+Singdata Lakehouse uses a four-tier organization structure to manage resources and data: Instance → Catalog → Schema → Data Objects.
+
+![](/.topwrite/assets/20-org-hierarchy.png)
+
+```
+Instance
+├── Workspace                          ← Internal Catalog, resource isolation unit
+│   ├── Schema                         ← Namespace, organizes tables/views/functions
+│   │   └── Tables, Views, Functions, etc.
+│   └── External Schema                ← Special Schema that maps an external Hive data source
+└── External Catalog                   ← External data catalog, entry point for federated queries
+    └── External Schema
+        └── External Table
+```
+
+## Tier Descriptions
+
+| Tier | Description | Reference |
+|------|-------------|-----------|
+| Instance | The top-level resource unit, corresponding to one Singdata Lakehouse instance. Instance-level configuration is shared across all Workspaces. | [Managing Instances](managing-instance.md) |
+| Workspace | The resource isolation unit within an instance, essentially an internal Catalog. Contains independent users, permissions, compute clusters, and data objects. Different Workspaces are invisible to each other by default. | [Workspace](om-workspace.md) |
+| External Catalog | An external data catalog at the same level as a Workspace, mapping external data systems such as Hive, Databricks, and Snowflake for federated queries. | [External Catalog](external-catalog-concept.md) |
+| Schema | The namespace within a Workspace, used to organize data objects by business domain or data layer (e.g., `ods`, `dwd`, `ads`). | [Schema](om-schema.md) |
+| External Schema | A special Schema within a Workspace that maps an external Hive data source, enabling direct queries without data migration. | [External Schema](external-schema.md) |
+
+## Recommendations
+
+**When to create multiple Workspaces:**
+- Isolating development, test, and production environments
+- Different business teams need independent permissions and compute resources
+- Business units that require separate billing
+
+**When to create multiple Schemas:**
+- Dividing by data layer within the same team (ODS / DWD / ADS)
+- Dividing by business domain within the same Workspace (orders, users, products)
+- Granting permissions to different data collections as a whole
+
+**When to use External Catalog vs. External Schema:**
+
+| Scenario | Recommendation |
+|----------|----------------|
+| Querying external systems such as Hive, Databricks, or Snowflake | External Catalog |
+| Mounting an external Hive database into the current Workspace for direct `schema.table` references | External Schema |
+| Federated queries across platforms without data migration | External Catalog |
+
+**In-place data lake acceleration**: Data stays in the original object storage (OSS/COS/S3/HDFS). Connect it to Lakehouse via External Catalog or External Schema, then use Lakehouse directly as a replacement for Spark/Hive for ETL processing, or as a replacement for Presto/Trino for ad-hoc queries — no data migration required, and you immediately gain Lakehouse's performance and SQL capabilities.
+
+## Related Documentation
+
+- [Workspace](om-workspace.md) — Create, manage members, configure roles
+- [Schema](om-schema.md) — Create, switch, cross-Schema references
+- [External Catalog](external-catalog-concept.md) — Federated queries on external data systems
+- [External Schema](external-schema.md) — Map external Hive data sources
+- [In-Place Data Lake Acceleration Implementation Guide](lakehouse-acceleration-guide.md) — Rapid POC validation, replace Spark/Hive and Presto/Trino without moving data

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

@@ -0,0 +1,39 @@
+# Create Volume to Access Alibaba Cloud OSS Data:
+
+## Prerequisites:
+
+After the STORAGE CONNECTION to Alibaba Cloud is created, you can create a Volume object to access object storage data:
+
+## Create Volume Object
+
+```SQL
+
+CREATE EXTERNAL VOLUME sh_image_volume
+    LOCATION 'oss://{bucket_name}/{path_to_data}'
+    USING CONNECTION sh_oss_conn_public
+    DIRECTORY = (
+        enable=true,
+        auto_refresh=true
+    )
+    RECURSIVE=true;
+```
+
+####
+
+#### 2. View Details of Created Volume Objects
+
+```SQL
+DESC VOLUME sh_image_volume
+```
+
+#### 3. View the files in the created Volume path
+
+```SQL
+SHOW VOLUME DIRECTORY sh_image_volume;
+```
+
+#### 4. Displaying Images in the Volume Path in Lakehouse Studio
+
+When in the Lakehouse Studio development interface, you can directly click the URL -> **Preview** to open the image after obtaining the access URL of the image through the [get\_presigned\_url](get_presigned_url.md) function:
+
+![](.topwrite/assets/20250219-153030.jpeg)