@clickzetta/cz-cli-darwin-x64 0.3.95 → 0.3.96

package/bin/skills/lakehouse-doc-en/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: lakehouse-doc-en
+description: |
+  Singdata/Clickzetta Lakehouse official documentation knowledge base (English). Consult references/
+  when writing SQL or answering questions about query syntax, functions, data types, DDL/DML,
+  dynamic tables, permissions, vclusters, data lake, AI functions, external catalog federation queries,
+  and other Lakehouse topics.
+  Keywords: documentation, SQL syntax, functions, DDL, DML, data types, permissions, vcluster, reference
+---
+
+# lakehouse-doc-en
+
+Singdata/Clickzetta Lakehouse official documentation (English). Locate docs by filename under `references/` based on the user's question.
+
+## references/ layout
+
+```
+references/
+├── *.md                          # Main topic docs (named by topic, see index below)
+├── eco_integration/              # Ecosystem integrations
+│   ├── dbt.md, superset.md, datagrip-lakehouse.md, trino.md ...
+├── java_reference/               # Java SDK
+│   ├── java-sdk-summary.md, jdbc.md, realtime-upload.md, client.md ...
+├── python_reference/             # Python SDK
+│   ├── connector.md, sqlalchemy.md, python-sdk-summary.md
+├── opensource/                   # Open-source tools
+│   └── travel.md
+├── aggregate_functions/          # Top-level aggregate function docs
+└── sql_functions/                # SQL function reference
+    ├── aggregate_functions/      # count.md, sum.md, avg.md ...
+    ├── window_functions/         # row_number.md, rank.md, lag.md ...
+    ├── table_functions/          # table_changes.md ...
+    ├── context_functions/        # current_user.md ...
+    └── scalar_functions/
+        ├── datetime_functions/   # date/time
+        ├── string_functions/     # string
+        ├── math_functions/       # numeric
+        ├── nested_functions/     # array/map/struct
+        ├── bitmap_functions/     # bitmap
+        ├── json_functions/       # JSON
+        ├── conditional_functions/# conditional
+        ├── high_order_functions/ # high-order
+        ├── vector_functions/     # vector
+        ├── ip_functions/         # IP
+        ├── search_functions/     # search
+        ├── hash_functions/       # hash
+        ├── geo_functions/        # geo
+        ├── bitwise_functions/    # bitwise
+        ├── file_functions/       # file
+        └── partition/            # partition
+```
+
+## Document Index (llms.txt)
+
+# Singdata/Clickzetta Lakehouse Documentation (LLM Navigation)
+
+> Singdata/Clickzetta Lakehouse is a fully managed lakehouse architecture platform built from the ground up on cloud-native design principles. Through **storage-compute separation**, **Serverless elastic architecture**, **open storage formats**, and **AI-optimized tools**, it provides enterprises with a unified platform for data warehousing, data lakes, real-time processing, and BI reporting. [Free Trial](https://www.singdata.com)
+
+
+## Quick Start
+
+- [Overview](references/overview.md): Top-level Singdata Lakehouse overview introducing the incremental computation engine, lake acceleration, AI infrastructure, and role-based navigation paths for engineers, analysts, admins, and AI agents.
+- [Concept Index](references/concepts.md): Product introduction to Singdata Lakehouse covering its vectorized engine, Generic Incremental Computation, AI Lakehouse vision, Iceberg storage, and serving humans, apps, and AI Agents.
+- [Tutorials](references/tutorials.md): A role-based getting-started guide offering onboarding paths for data engineers and data analysts, covering data ingestion, processing pipelines, SQL queries, and tool connections.
+
+## User Guide
+
+- [Object Model](references/object_model_design.md): Comprehensive overview of the Lakehouse object model, describing the Instance/Workspace/Schema hierarchy and categorizing objects: catalogs, tables, volumes, connections, pipes, streams, indexes, partitions, functions, and synonyms.
+- [Manage Compute Resources](references/tutorial_virtual_cluster.md): Managing compute resources (VClusters), covering the three cluster types General, Analytical, and Integration, their elasticity models, and common operations like viewing, switching, and starting clusters.
+- [Lakehouse Studio](references/studio_manual.md): An overview of Studio, the serverless web console and data services platform for Lakehouse, covering its AI-driven Data Agent and six core modules including data sync, task development, scheduling, and SQL query.
+- [Data Ingestion](references/Ingestion.md): Decision-oriented overview of Singdata Lakehouse data ingestion, routing relational database, file, Kafka, custom/programmatic, and warehouse-migration scenarios to the appropriate Studio sync, Pipe, COPY INTO, or SDK approach.
+- [Data Transformation via SQL](references/sql_data_transform.md): Navigation guide for data transformation patterns, helping choose between Dynamic Tables, Studio scheduled ETL, Table Stream CDC, and Materialized Views by latency and trigger needs.
+- [Data Analysis and SQL Guide](references/Analysis.md): A scenario-based navigation guide to Singdata Lakehouse analytics capabilities, covering SQL querying, BI tool connectivity, data lake file analysis, federated queries, AI-powered analysis, and query performance optimization.
+- [Federation Query](references/federation-query.md): Overview of Federation Query for querying external systems (Hive, Databricks, Iceberg, Snowflake) directly via standard SQL using EXTERNAL CATALOG, covering supported sources, core concepts, and quick-start examples.
+- [Data Lake Management and Analytics](references/datalake_volume_analytics.md): An overview of data lake management via Volume objects, covering internal and external storage, direct querying, import and export, permissions, and a quick selection guide.
+- [Developing Custom Functions](references/RemoteFunction-as-udf.md): An overview of developing External (Remote) Functions in Python or Java that run on cloud function services, covering how they work, supported function types, runtime environments, and the creation workflow.
+- [Data Sharing](references/data_sharing_guide.md): Navigation guide for zero-copy cross-instance data sharing, organized by provider and consumer roles, covering Studio UI and SQL workflows, required roles, and sharing limitations.
+- [Data Governance](references/time_travel_guide.md): An overview of data governance with Time Travel, covering MVCC-based historical version querying, table rollback, dropped-table recovery, and the difference between data_retention_days and data_lifecycle.
+- [Security](references/data_security.md): Navigation hub for Lakehouse security covering user permissions, data masking, network access control, audit compliance, identity authentication, and data recovery with task-oriented reference links.
+- [INFORMATION SCHEMA](references/information_schema_guide.md): The INFORMATION_SCHEMA metadata query interface, covering instance-level and workspace-level access scopes, comparison with SHOW and DESC, and common metadata and asset inventory queries.
+- [Account and Billing](references/management_guide.md): Account and billing management guide covering account information, users and permissions, account funds and top-ups, billing statements, and cost control, noting the administrator roles required for each operation.
+- [Connect Using Ecosystem Tools](references/ecosystem-all.md): A guide to connecting Lakehouse with ecosystem tools, covering SQL clients, BI tools, ETL platforms, and programmatic access via JDBC, Python/Java SDKs, and Spark/Flink connectors.
+- [Performance Optimization](references/performance_optimization.md): Overview of Lakehouse performance optimization capabilities including result cache, compute cluster cache, small file optimization, sort-column recommendations, and job profiling, with a quick selection guide.
+- [Performance Testing](references/benchmark_guide.md): Summary of Singdata Lakehouse performance benchmarks against ClickHouse (SSB), Trino (TPC-H), and Spark SQL (TPC-DS), with comparison results and links to detailed reports.
+
+## AI Guide
+
+- [Lakehouse AI Overview](references/LakehouseAI-overview.md): Overview of Lakehouse AI capabilities, presenting a selection guide and core features: AI Functions, Vector Search, External Functions, Semantic Views, and Zettapark for in-SQL LLM and RAG workflows.
+- [AI + BI Unified Workflow](references/unified-workflow.md): Stub landing page titled Unified Workflow, intended as an overview entry point for Lakehouse unified development and orchestration workflow documentation.
+- [AI Gateway](references/AIGateway.md): Introduces Singdata AI Gateway, an enterprise service offering unified multi-model API access, intelligent routing, BYOK integration, and per-key usage control, fully compatible with the OpenAI interface format.
+- [Conversational Analytics (Analytics Agent)](references/datagpt_introduction.md): Introduction to Analytics Agent (formerly DataGPT), a conversational agentic analysis assistant, covering when to use it, quick start, core concepts of data assets and analysis domains, user roles, and Agentic RAG architecture.
+- [Singdata CLI (cz-cli)](references/cz-cli.md): Introduces cz-cli, the Singdata Lakehouse command-line tool, explaining its advantages for AI agents over JDBC/REST/MCP, the orchestrator-subagent pattern, command overview, and quick-start installation and configuration.
+- [AI Ecosystem](references/AI_eco.md): Overview of Singdata Lakehouse AI ecosystem integrations including Dify, N8N, LangChain, Unstructured ETL, and Datus, with a quick selection guide for vector storage and RAG scenarios.
+
+## SQL Manual
+
+- [SQL Statements](references/sql-commands.md): Basic commands reference covering object identifiers, comment syntax, session parameters, and general DDL (CREATE, ALTER, DROP, UNDROP, DESC, SHOW) applicable to all object types.
+- [Data Types](references/data-type-guide.md): Overview of Lakehouse data types covering numeric, string, time, boolean, binary, and complex types (ARRAY, MAP, STRUCT, JSON, VECTOR, BITMAP), with quick reference tables and chapter links.
+- [SQL Functions](references/functions.md): Catalog of Singdata Lakehouse SQL functions organized by category, covering numeric, string, datetime, complex types, aggregation, window, AI functions, vector, BITMAP, and system functions.
+
+## Development Manual
+
+- [Java SDK](references/java_sdk_guide.md): Overview of the clickzetta-java SDK providing JDBC queries, real-time streaming writes, and high-throughput Bulkload, with a contents table and comparison of the three write methods and their use cases.
+- [Python SDK (SQL Interface)](references/python_sdk_guide.md): Overview of the clickzetta-connector Python SDK, covering its four integration methods (Database API, SQLAlchemy, Bulkload, and real-time writes) with a comparison of use cases and links to detailed references.
+- [ZettaPark (DataFrame API)](references/LakehousePython-zettapark.md): Overview of ZettaPark, the pandas/PySpark-style Python DataFrame API that lazily translates operations into SQL for distributed execution on Lakehouse, with links to quick start, ETL, and feature engineering guides.
+
+## Practice Tutorials
+
+- [Efficient Object and Data Organization Management](references/data_org.md):
+- [Data Import and Export Practice](references/practice_data_import_and_export.md): An empty placeholder page with no substantive content.
+- [Data Lake Acceleration](references/datalake-acceleration.md): Brief overview of in-place data lake acceleration, connecting directly to an existing Hive Metastore and object storage via External Schema to replace Spark/Hive ETL and Presto/Trino queries with Serverless compute.
+- [Migration Guide](references/tutorial_migration.md): Migration guide hub mapping source systems (Databricks/PySpark, RDD, Spark SQL, Snowflake, Medallion) to recommended Lakehouse migration paths with links and path-selection advice.
+- [Data Query and Analysis Practice](references/practice_data_analysis.md): Empty placeholder page containing only a content marker symbol, with no data analysis practice content, examples, or guidance currently present in the file body.
+- [Building and Maintaining ELT Processes](references/ELT_practice.md): Placeholder page for ELT practice in Singdata Lakehouse; currently empty with no substantive content.
+- [Optimize Computing Resources](references/optimizing-computing-resources.md): Placeholder page for optimizing computing resources in Singdata Lakehouse; currently empty with no substantive content.
+- [Performance Experience](references/performence_test.md): Empty placeholder page intended for performance testing content; no substantive material is present beyond a content marker.
+- [Modern Data Stack with Ecosystem Tools](references/modern-data-stack-with-ecosystem-tools.md):
+- [AI Application Development](references/ai_app_dev_practical.md): Brief landing page introducing practical guides for building AI-powered applications on Singdata Lakehouse.
+- [Security Compliance Audit](references/security_compliance_audit_dir_guide.md): A brief section header introducing security and compliance audit topics.
+- [Cost Management](references/cost_management.md): Stub page titled Cost Management for Singdata Lakehouse, intended to cover billing and cost control topics but currently without content.
+
+## Release Notes
+
+- [Release Notes](references/release-notes.md): A landing page indexing the release notes history for the Singdata Lakehouse platform.
+
+## Other
+
+- [User Agreement](references/service-aggrement.md): The Singdata Service Agreement (effective January 10, 2025), setting legal terms for account registration, service use, member responsibilities, account security, and liability limitations.
+- [Privacy Policy](references/privacy-policy.md): Singdata privacy policy (2024.08) detailing collection, use, disclosure, transfer, retention, and destruction of personal data, plus security measures, cookies, and user rights to access or correct data.
+- [Product Trial Agreement](references/product-trial-agreement.md): Legal product trial agreement for Singdata, covering service description, user responsibilities, company rights, intellectual property, disclaimers, and dispute resolution during the testing phase.

package/bin/skills/lakehouse-doc-en/SKILL.md.template

@@ -0,0 +1,49 @@
+---
+name: lakehouse-doc-en
+description: "Singdata Lakehouse official documentation knowledge base (English). Consult references/ when writing SQL or answering questions about query syntax, functions, data types, DDL/DML, dynamic tables, permissions, vclusters, data lake, AI functions, and other Lakehouse topics."
+---
+
+# lakehouse-doc-en
+
+Singdata Lakehouse official documentation (English). Locate docs by filename under `references/` based on the user's question.
+
+## references/ layout
+
+```
+references/
+├── *.md                          # Main topic docs (named by topic, see index below)
+├── eco_integration/              # Ecosystem integrations
+│   ├── dbt.md, superset.md, datagrip-lakehouse.md, trino.md ...
+├── java_reference/               # Java SDK
+│   ├── java-sdk-summary.md, jdbc.md, realtime-upload.md, client.md ...
+├── python_reference/             # Python SDK
+│   ├── connector.md, sqlalchemy.md, python-sdk-summary.md
+├── opensource/                   # Open-source tools
+│   └── travel.md
+├── aggregate_functions/          # Top-level aggregate function docs
+└── sql_functions/                # SQL function reference
+    ├── aggregate_functions/      # count.md, sum.md, avg.md ...
+    ├── window_functions/         # row_number.md, rank.md, lag.md ...
+    ├── table_functions/          # table_changes.md ...
+    ├── context_functions/        # current_user.md ...
+    └── scalar_functions/
+        ├── datetime_functions/   # date/time
+        ├── string_functions/     # string
+        ├── math_functions/       # numeric
+        ├── nested_functions/     # array/map/struct
+        ├── bitmap_functions/     # bitmap
+        ├── json_functions/       # JSON
+        ├── conditional_functions/# conditional
+        ├── high_order_functions/ # high-order
+        ├── vector_functions/     # vector
+        ├── ip_functions/         # IP
+        ├── search_functions/     # search
+        ├── hash_functions/       # hash
+        ├── geo_functions/        # geo
+        ├── bitwise_functions/    # bitwise
+        ├── file_functions/       # file
+        └── partition/            # partition
+```
+
+## Document Index (llms.txt)
+

package/bin/skills/lakehouse-doc-en/references/AI Gateway Guide.md

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

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

@@ -0,0 +1,27 @@
+# AI Gateway
+
+Singdata AI Gateway is an enterprise-grade AI gateway service that provides unified multi-model API management, intelligent routing, BYOK model integration, and usage statistics. It helps enterprises simplify multi-vendor LLM integration so that a single onboarding gives you access to all models.
+
+## What do you want to do?
+
+| Goal | Where to go |
+|------|-------------|
+| Learn about AI Gateway's features and positioning | [Product Introduction](introduction.md) |
+| Complete setup and call your first model in 10 minutes | [Quick Start](quickstart.md) |
+| View supported models and pricing | [Model Pricing](modelprice.md) |
+| Connect your own third-party model (BYOK) | [Product Introduction → BYOK](introduction.md) |
+| Manage API Keys and set usage limits | [Product Introduction → API Key Management](introduction.md) |
+
+## Core Capabilities at a Glance
+
+**Unified access**: Call mainstream models from Alibaba Cloud Bailian, ByteDance Doubao, AWS Bedrock, and others through a single API endpoint. 100% compatible with the OpenAI interface format — existing code only needs the endpoint and key replaced.
+
+**Intelligent routing**: Automatically selects the optimal model by price, latency, and throughput, with automatic failover support.
+
+**BYOK**: Bring your own third-party API Key. Billing goes through your own vendor account; the platform charges no additional fees.
+
+**Usage control**: Track token consumption by API Key, team, or project dimension, with support for limits and alerts.
+
+## Quick Start
+
+→ [Complete initial setup and call your first model in 10 minutes](quickstart.md)

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

@@ -0,0 +1,239 @@
+# AI_COMPLETE
+
+`AI_COMPLETE` is the core scalar function for generative AI tasks on the Singdata Lakehouse platform. It allows you to invoke large language models (LLMs) directly within the SQL environment, generating responses based on text prompts or multimodal inputs, enabling tasks such as text completion, translation, sentiment analysis, code generation, and complex reasoning.
+
+Singdata pushes AI computation down to the storage layer and execution engine, so data can be intelligently processed within the platform without being transferred to external environments — safeguarding data security while significantly reducing task latency.
+
+> When a task can be accomplished with a dedicated function (such as `AI_TRANSLATE`, `AI_SENTIMENT`, `AI_CLASSIFY`, etc.), prefer the dedicated function — it has built-in prompts optimized for that specific task, producing more stable results at lower cost. Use `AI_COMPLETE` for custom scenarios that dedicated functions cannot cover.
+
+---
+
+## Syntax
+
+`AI_COMPLETE` supports two calling forms:
+
+**Text mode**
+
+```sql
+ai_complete(<model>, <prompt> [, json '{}'])
+```
+
+**Image mode**
+
+```sql
+ai_complete(<model>, (<prompt> AS prompt, <image_url> AS image) [, json '{}'])
+```
+
+---
+
+## Parameter Description
+
+### model (required)
+
+Specifies the language model to invoke. Two sources are supported:
+
+**Source 1: API Gateway Endpoint (recommended)**
+
+The platform administrator pre-configures model services in the API Gateway (including provider, version, and authentication credentials). Regular users reference them using the `endpoint:` prefix without needing to know the underlying connection details.
+
+```sql
+'endpoint:<endpoint_name>'
+
+-- Examples
+'endpoint:qwen3-max-preview'
+'endpoint:qwen3.5-plus'
+'endpoint:doubao-seed-2-0-pro-260215'
+```
+
+**Source 2: API Connection object**
+
+Users create connection objects themselves via `CREATE API CONNECTION`, suitable for scenarios requiring custom service addresses, authentication keys, or connections to privately deployed models.
+
+```sql
+-- Create a connection object
+CREATE API CONNECTION conn_bailian
+    TYPE ai_function
+    PROVIDER = 'bailian'
+    BASE_URL = 'https://dashscope.aliyuncs.com/api/v1'
+    API_KEY = 'sk-xxxxxxxxxxxxxxxxxxxxxxxx';
+
+-- Reference using the connection: prefix
+SELECT ai_complete('conn_bailian:qwen3.5-plus', 'Briefly introduce the basic principles of quantum computing.');
+```
+
+`CREATE API CONNECTION` field descriptions:
+
+| Field | Description |
+|-------|-------------|
+| `TYPE` | Fixed as `ai_function` |
+| `PROVIDER` | Model provider identifier, e.g. `'bailian'`, `'openai'`, `'anthropic'` |
+| `BASE_URL` | API base address of the model service |
+| `API_KEY` | Authentication key required to call the service |
+
+---
+
+### prompt (required)
+
+The input content to send to the model, of type STRING.
+
+**Text mode**: pass a string directly:
+
+```sql
+SELECT ai_complete('endpoint:qwen3-max-preview', 'Explain what a vector database is in one sentence');
+```
+
+Dynamic content can be concatenated using `CONCAT` or `||`:
+
+```sql
+SELECT ai_complete(
+    'endpoint:qwen3-max-preview',
+    CONCAT('Summarize the following text in 20 words: ', content)
+) AS summary
+FROM articles;
+```
+
+**Image mode**: use named tuple syntax to pass both a text prompt and an image URL:
+
+```sql
+SELECT ai_complete(
+    'endpoint:doubao-seed-2-0-pro-260215',
+    ('What is in the image?' AS prompt,
+     GET_PRESIGNED_URL(USER VOLUME, 'images/product.jpg', 36000) AS image)
+);
+```
+
+> In image mode, the `image` field cannot be NULL; otherwise the error `invalid type of image field: void` is thrown.
+
+---
+
+### options (optional)
+
+Passed using the `json '{}'` literal syntax to control execution behavior and model parameters:
+
+| Parameter key | Type | Description |
+|---------------|------|-------------|
+| `model.params.temperature` | FLOAT | Output randomness, range [0, 2]; lower values produce more deterministic output |
+| `model.params.max_tokens` | INT | Maximum number of output tokens |
+| `model.params.top_p` | FLOAT | Nucleus sampling probability, range (0, 1] |
+| `model.params.enable_thinking` | BOOL | Whether to enable thinking mode; recommended to set to `false` for batch processing |
+| `response.timeout` | STRING | Timeout per request in seconds, e.g. `"60"` |
+| `task.concurrency` | STRING | Concurrency level for batch processing, e.g. `"5"` |
+
+```sql
+-- Disable thinking mode
+SELECT ai_complete(
+    'endpoint:qwen3-max-preview',
+    'What is artificial intelligence? Answer in one sentence',
+    json '{"model.params":{"enable_thinking":false}}'
+) AS result;
+
+-- Combine multiple parameters
+SELECT ai_complete(
+    'endpoint:qwen3-max-preview',
+    question,
+    json '{"model.params":{"enable_thinking":false},"task.concurrency":"5"}'
+) AS answer
+FROM questions;
+```
+
+---
+
+## Return Value
+
+Returns a STRING — the response text generated by the model.
+
+- When prompt is `NULL` or an empty string, returns `NULL`
+- When the endpoint does not exist, throws `CZLH-67000: No available endpoints found`
+- When the model format is invalid (missing `endpoint:` or `connection:` prefix), throws `CZLH-65000: Invalid model coordinates`
+
+---
+
+## Usage Examples
+
+### Basic Text Completion
+
+```sql
+SELECT ai_complete('endpoint:qwen3-max-preview', 'What is the capital of China?') AS result;
+```
+
+### Batch Processing Table Data
+
+```sql
+SELECT
+    id,
+    ai_complete(
+        'endpoint:qwen3-max-preview',
+        question,
+        json '{"model.params":{"enable_thinking":false},"task.concurrency":"5"}'
+    ) AS answer
+FROM questions;
+```
+
+### Dynamic Prompt with CONCAT
+
+```sql
+SELECT
+    product_id,
+    ai_complete(
+        'endpoint:qwen3-max-preview',
+        CONCAT('Write a selling point description of no more than 30 words for the following product: ', product_name)
+    ) AS selling_point
+FROM products;
+```
+
+### Image Description
+
+```sql
+SELECT ai_complete(
+    'endpoint:doubao-seed-2-0-pro-260215',
+    ('What is in the image?' AS prompt,
+     GET_PRESIGNED_URL(USER VOLUME, 'images/product.jpg', 36000) AS image)
+) AS result;
+```
+
+### Image with a Specific Question
+
+```sql
+SELECT ai_complete(
+    'endpoint:doubao-seed-2-0-pro-260215',
+    ('What is the price of this product? Answer in one sentence.' AS prompt,
+     GET_PRESIGNED_URL(USER VOLUME, 'images/product.jpg', 36000) AS image)
+) AS result;
+```
+
+### Batch Image Processing
+
+```sql
+SELECT
+    relative_path,
+    ai_complete(
+        'endpoint:doubao-seed-2-0-pro-260215',
+        ('Describe the product in the image in one sentence.' AS prompt,
+         GET_PRESIGNED_URL(USER VOLUME, relative_path, 36000) AS image),
+        json '{"model.params":{"enable_thinking":false},"task.concurrency":"3"}'
+    ) AS description
+FROM (SHOW USER VOLUME DIRECTORY SUBDIRECTORY 'images/products')
+LIMIT 10;
+```
+
+### Combining with Other AI Functions
+
+```sql
+-- AI_COMPLETE generates text → AI_CLASSIFY categorizes it
+SELECT ai_classify(
+    'endpoint:qwen3.5-plus',
+    ai_complete('endpoint:qwen3-max-preview', 'Write a technology news headline'),
+    ARRAY('Technology', 'Sports', 'Finance', 'Entertainment')
+) AS category;
+```
+
+---
+
+## Notes
+
+- **Model selection**: Image mode requires a model that supports multimodal input (e.g. `doubao-seed-2-0-pro-260215`). Text-only models such as `qwen3-max-preview` do not support image input — passing an image does not cause an error, but the image content is ignored and the response is generated from the text prompt only.
+- **Thinking mode**: The qwen3 model series enables thinking mode by default, which increases latency and token consumption. For batch processing scenarios, it is recommended to disable it via options: `json '{"model.params":{"enable_thinking":false}}'`.
+- **Image field cannot be NULL**: Passing NULL for the `image` field in image mode throws `invalid type of image field: void`. Ensure `GET_PRESIGNED_URL()` returns a valid URL.
+- **NULL and empty strings**: When prompt is `NULL` or an empty string, the function returns `NULL` without error.
+- **Error codes**: A missing endpoint throws `CZLH-67000`; an invalid model format (missing `endpoint:` prefix) throws `CZLH-65000`.
+- **Token limits**: Different models have different context window limits. Inputs exceeding the limit will be truncated or cause an error. Pay attention to input length when processing long text.

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

@@ -0,0 +1,192 @@
+# AI_EMBEDDING
+
+## Overview
+
+Converts text into embedding vectors. An embedding vector is an abstract numerical representation of the semantic features of text, which can be used to measure the degree of semantic similarity between texts. It is suitable for downstream tasks such as semantic search, text similarity computation, cluster analysis, and recommendation systems.
+
+## Syntax
+
+```sql
+AI_EMBEDDING( <model>, <input> [, <model_parameters>] )
+```
+
+## Parameter Description
+
+### Required Parameters
+
+**`model`**
+
+Specifies the model to use for generating embedding vectors. Two reference methods are supported:
+
+**Method 1: Call via API Gateway endpoint**
+
+```
+'endpoint:<endpoint_name>'
+```
+
+**Method 2: Call via API Connection object**
+
+First create a connection object using `CREATE API CONNECTION`, then reference it in the format `<connection_name>:<model_name>`:
+
+```
+'<connection_object_name>:<model_name>'
+```
+
+> Ensure the specified model is an Embedding Model, not a Chat Completion Model. Embedding models are specifically designed to map text to fixed-dimension numerical vectors. Common embedding models include OpenAI's `text-embedding-3-small`, `text-embedding-3-large`, and Alibaba Cloud Bailian's `text-embedding-v4`.
+
+**`input`**
+
+The input text used to generate the embedding vector. This can be a single word, a sentence, a paragraph, or a value from a column in a data table.
+
+### Optional Parameters
+
+**`model_parameters`**
+
+Model hyperparameters passed in as a JSON object. Supported parameters may vary by model. `text-embedding-v4` supports the following parameters:
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `input` | STRING | `'document'` | Specifies the purpose type of the input content. Values are `'document'` (document content) or `'query'` (query text). In retrieval scenarios, use `'document'` when indexing documents and `'query'` for user queries — the model optimizes vectors differently for each purpose, improving retrieval accuracy. For symmetric tasks such as clustering and classification, use the default `'document'`. |
+| `dimensions` | STRING | `'1024'` | Specifies the output vector dimension. `text-embedding-v4` supports 8 dimensions: `'64'`, `'128'`, `'256'`, `'512'`, `'768'`, `'1024'`, `'1536'`, `'2048'`. Higher dimensions generally preserve richer semantic information but consume more storage space and computational resources. |
+
+## Return Value
+
+The embedding vector derived from the input text, of type `ARRAY<FLOAT>`.
+
+- Use the `SIZE()` function to get the vector dimension
+- Use the `COSINE_SIMILARITY()` function to compute the cosine similarity between two vectors
+
+## Usage Notes
+
+- **Results are deterministic**: Embedding models are deterministic — the same input text always returns the same vector.
+- **NULL input returns NULL**: When `input` is `NULL`, the function returns `NULL` without error.
+- **Distinguish input types in retrieval scenarios**: Use `"input": "document"` when indexing documents and `"input": "query"` for user queries to improve retrieval accuracy.
+- **Filter NULLs in batch processing**: In batch processing scenarios, it is recommended to filter out NULL rows in advance to avoid query failures caused by mixing NULL and non-NULL data.
+
+## Limitations
+
+- **Empty strings are not supported**: When `input` is an empty string `''`, the function throws the error `input.texts should not be null` rather than returning NULL. Filter empty values before calling: `WHERE input IS NOT NULL AND LENGTH(input) > 0`.
+- **Maximum input length is 8,192 tokens**: Exceeding this limit causes an error; the input is not automatically truncated. Chinese text corresponds to roughly 26,000 characters or fewer.
+- **Maximum 10 items per batch**: When calling in batch, a single request can process at most 10 inputs.
+
+## Model Specifications (text-embedding-v4)
+
+| Attribute | Specification |
+| --- | --- |
+| Model Family | Qwen3-Embedding |
+| Supported Dimensions | 64 / 128 / 256 / 512 / 768 / **1024 (default)** / 1536 / 2048 |
+| Maximum Input Length | 8,192 tokens |
+| Supported Languages | Chinese, English, Japanese, Korean, German, French, Spanish, Portuguese, Russian, Indonesian, and 100+ other languages |
+
+## Examples
+
+### Basic Usage
+
+```sql
+-- Call via API Connection
+SELECT AI_EMBEDDING(
+    'cz_bailian:text-embedding-v4',
+    'The capital of China is Beijing'
+) AS embedding;
+
+-- Call via API Gateway endpoint
+SELECT AI_EMBEDDING(
+    'endpoint:text-embedding-v4',
+    'The capital of China is Beijing'
+) AS embedding;
+```
+
+### Get Vector Dimension
+
+```sql
+SELECT SIZE(AI_EMBEDDING('cz_bailian:text-embedding-v4', 'hello')) AS dim;
+-- Returns: 1024
+```
+
+### Specify Input Type (Retrieval Scenario)
+
+```sql
+-- Indexing documents: use input=document
+SELECT AI_EMBEDDING(
+    'cz_bailian:text-embedding-v4',
+    'Singdata Lakehouse is a fully managed lakehouse architecture platform',
+    JSON '{"input": "document"}'
+) AS embedding;
+
+-- User query: use input=query
+SELECT AI_EMBEDDING(
+    'cz_bailian:text-embedding-v4',
+    'What is a lakehouse?',
+    JSON '{"input": "query"}'
+) AS embedding;
+```
+
+### Specify Output Dimension
+
+```sql
+-- Output 512-dimension vector (saves storage)
+SELECT AI_EMBEDDING(
+    'cz_bailian:text-embedding-v4',
+    'Singdata Lakehouse is a fully managed lakehouse architecture platform',
+    JSON '{"dimensions": "512"}'
+) AS embedding;
+
+-- Output 2048-dimension vector (richer semantic information)
+SELECT AI_EMBEDDING(
+    'cz_bailian:text-embedding-v4',
+    'Singdata Lakehouse is a fully managed lakehouse architecture platform',
+    JSON '{"dimensions": "2048"}'
+) AS embedding;
+```
+
+### Combine Parameters
+
+```sql
+SELECT AI_EMBEDDING(
+    'cz_bailian:text-embedding-v4',
+    'What is a lakehouse?',
+    JSON '{"input": "query", "dimensions": "512"}'
+) AS embedding;
+```
+
+### Compute Text Semantic Similarity
+
+```sql
+SELECT COSINE_SIMILARITY(
+    AI_EMBEDDING('cz_bailian:text-embedding-v4', 'artificial intelligence'),
+    AI_EMBEDDING('cz_bailian:text-embedding-v4', 'machine learning')
+) AS similarity;
+```
+
+### Batch Vectorize Table Data
+
+```sql
+SELECT
+    id,
+    content,
+    AI_EMBEDDING('cz_bailian:text-embedding-v4', content) AS embedding
+FROM documents
+WHERE content IS NOT NULL AND LENGTH(content) > 0;
+```
+
+### Semantic Search
+
+```sql
+WITH query_vec AS (
+    SELECT AI_EMBEDDING(
+        'cz_bailian:text-embedding-v4',
+        'real-time data processing',
+        JSON '{"input": "query"}'
+    ) AS q
+)
+SELECT
+    d.id,
+    d.content,
+    COSINE_SIMILARITY(
+        AI_EMBEDDING('cz_bailian:text-embedding-v4', d.content, JSON '{"input": "document"}'),
+        q.q
+    ) AS similarity
+FROM documents d, query_vec q
+ORDER BY similarity DESC
+LIMIT 10;
+```