@clickzetta/cz-cli-darwin-x64 0.3.1

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/ip_functions/get_ip_info.md

@@ -0,0 +1,199 @@
+# GET\_IP\_INFO
+
+# 函数概述
+
+```python
+ get_ip_info(string ip, string table, string column)
+```
+
+该函数会在运行时根据第二个参数的指定的表名自动加载IP信息库,该表要求至少有 start\_ip end\_ip列,表示IP范围的闭区间。返回结果为第三个参数指定的column列。
+
+# **参数说明**
+
+| 参数       | 类型     | 必填 | 说明                                         |
+| -------- | ------ | -- | ------------------------------------------ |
+| `ip`     | string | 是  | 待查询的IP地址（支持IPv4/IPv6格式）                    |
+| `table`  | string | 是  | 指定Lakehouse表名字，且表结构需包含`start_ip`和`end_ip`列 |
+| `column` | string | 是  | 需返回的目标字段名，STRING类型必须是第二个参数table中存在的字段      |
+
+# **返回值**
+
+* 匹配成功：返回指定`column`列的字段值（STRING类型）
+
+# **使用示例**
+
+## 示例1
+
+1. 准备IP数据库表
+
+```sql
+CREATE TABLE IF NOT EXISTS ip_db(
+  start_ip   STRING COMMENT 'IP段起始地址',
+  end_ip     STRING COMMENT 'IP段结束地址',
+  geoname_id STRING,
+  country    STRING,
+  city       STRING
+);
+
+INSERT OVERWRITE TABLE ip_db VALUES
+  ("2a7:1c44:39f3:1b::", "2a7:1c44:39f3:1b:ffff:ffff:ffff:ffff", "8070", "USA", "LA"),
+  ("2c0f:ffb8::", "2c0f:ffb8:ffff:fff:fff:ffff:ff:ffff", "37210", "CHINA", "BJ"),
+  ("1.0.0.0", "1.0.0.255", "5987", "JAPAN", "TOKYO"),  -- 修正城市名拼写
+  ("2.0.0.0", "2.0.0.255", "8026", "INDIA", "DELHI");  -- 修正国家名拼写
+```
+
+2. 执行查询
+
+```sql
+SELECT 
+  ip, 
+  get_ip_info(ip, 'ip_db', 'country') AS country
+FROM VALUES
+  ('2c0f:ffb8:1b::'),  -- IPv6
+  ('1.0.0.2'),         -- IPv4
+  ('3.0.0.0')          -- 无匹配
+AS t(ip);
+```
+
+预期输出
+
+| ip              | country |
+| --------------- | ------- |
+| 2c0f\:ffb8:1b:: | CHINA   |
+| 1.0.0.2         | JAPAN   |
+| 3.0.0.0         | NULL    |
+
+***
+
+## 示例2
+
+### **一、业务背景**
+
+需基于IP地址快速获取7维地理信息：
+
+| 字段              | 说明     | 示例值           |
+| --------------- | ------- | ------------- |
+| `country`       | 国家名称  | 中国            |
+| `province`      | 省级行政区 | 北京市           |
+| `city`      | 城市名称  | 朝阳区           |
+| `timezone`      | 时区信息  | Asia/Shanghai |
+| `latitude`      | 纬度坐标  | 39.9042       |
+| `longitude`     | 经度坐标  | 116.4074      |
+| `countryCode`   | 国家代码  | CN            |
+| `continentCode` | 大洲代码  | AS            |
+
+### 二、技术实现
+
+基于Lakehouse内置函数`get_ip_info(ip, table_name, column)`实现IP解析，底层采用ip2location技术方案。
+
+### 三、实施流程
+
+#### 1. 数据准备
+
+* **下载官方数据包**
+  访问[MaxMind官网](https://dev.maxmind.com/geoip/geoip2/geolite2/)获取最新版GeoLite2-City-CSV数据包（含IPv4/IPv6数据）
+
+* **转换CIDR为IP段**
+  使用官方转换工具生成可查询的IP范围：
+  ```bash
+  # 转换IPv4数据
+  ./geoip2-csv-converter -block-file GeoLite2-City-Blocks-IPv4.csv \
+    -include-range -output-file IPv4_Blocks_Converted.csv
+
+  # 转换IPv6数据
+  ./geoip2-csv-converter -block-file GeoLite2-City-Blocks-IPv6.csv \
+    -include-range -output-file IPv6_Blocks_Converted.csv
+  ```
+  本文使用的是如下两个 CSV 文件，分别是网络 IP 地址段表和中国地理信息表：
+  ![](../../../.topwrite/assets/image_1744721445413.png)
+
+#### 2. 数据建模
+
+##### (1) IP地址段表 `geoip`
+
+```sql
+CREATE TABLE geoip (
+  network_start_ip  STRING  COMMENT 'IP段起始地址',
+  network_last_ip   STRING  COMMENT 'IP段结束地址',
+  geoname_id        STRING  COMMENT '地理位置ID',
+  latitude          STRING  COMMENT '纬度',
+  longitude         STRING  COMMENT '经度'
+)
+;
+```
+
+##### (2) 地理信息表 `geolocation`
+
+```sql
+CREATE TABLE geolocation (
+  geoname_id        STRING  COMMENT '地理位置ID',
+  country_code      STRING  COMMENT '国家代码(ISO 3166)',
+  country           STRING  COMMENT '国家名称',
+  province          STRING  COMMENT '省级行政区',
+  city              STRING  COMMENT '城市名称',
+  time_zone         STRING  COMMENT '时区',
+  continent_code    STRING  COMMENT '大洲代码'
+);
+```
+
+##### (3) 聚合视图表 `geo_lite_info`
+
+```sql
+-- 创建聚合表
+CREATE TABLE geo_lite_info (
+  start_ip          STRING  COMMENT 'IP段起始',
+  end_ip            STRING  COMMENT 'IP段结束',
+  country           STRING,
+  province          STRING,
+  city              STRING,
+  timezone          STRING,
+  latitude          STRING,
+  longitude         STRING,
+  country_code      STRING,
+  continent_code    STRING
+);
+
+-- 数据关联写入
+INSERT OVERWRITE TABLE geo_lite_info
+SELECT 
+  a.network_start_ip,
+  a.network_last_ip,
+  b.country,
+  b.province,
+  b.city,
+  b.time_zone,
+  a.latitude,
+  a.longitude,
+  b.country_code,
+  b.continent_code
+FROM geoip a
+JOIN geolocation b 
+  ON a.geoname_id = b.geoname_id;
+```
+
+***
+
+### 四、函数调用
+
+#### 前提条件
+
+* 目标表`geo_lite_info`已正确创建且数据就绪
+* IP地址需为规范化格式（支持IPv4/IPv6）
+
+#### 调用示例
+
+```sql
+-- 单点查询
+SELECT 
+  get_ip_info('114.246.239.157', 'geo_lite_info', 'city') AS city,
+  get_ip_info('2001:4860:4860::8888', 'geo_lite_info', 'timezone') AS tz;
+
+-- 批量查询
+SELECT 
+  ip,
+  get_ip_info(ip, 'geo_lite_info', 'country') AS country,
+  get_ip_info(ip, 'geo_lite_info', 'province') AS province
+FROM VALUES (('8.8.8.8'), ('114.114.114.114')) AS t(ip);
+```
+
+

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/ip_functions/ipv4_num_to_string.md

@@ -0,0 +1,29 @@
+### IPv4_NUM_TO_STRING 函数
+
+#### 功能描述
+`ipv4_num_to_string` 函数用于将 IPv4 地址的数字形式（只考虑低位的 32 位）转换为可读的字符串形式。该函数接收一个 bigint 类型的参数，并返回一个字符串类型的 IPv4 地址。
+
+#### 参数说明
+* `expr`: 一个 bigint 类型的参数，代表 IPv4 地址的数字形式。
+
+#### 返回结果
+* 返回一个字符串，表示传入的 IPv4 地址的可读形式。
+
+#### 使用示例
+以下展示了 `ipv4_num_to_string` 函数的几个使用示例：
+
+```sql
+-- 例子 1: 转换一个常见的回环地址
+SELECT ipv4_num_to_string(2130706433); -- 返回 '127.0.0.1'
+
+-- 例子 2: 转换一个公网地址
+SELECT ipv4_num_to_string(3232235777); -- 返回 '192.168.1.1'
+
+-- 例子 3: 转换一个私有地址
+SELECT ipv4_num_to_string(1730150097); -- 返回 '103.31.254.209'
+
+-- 例子 4: 转换一个特殊用途的地址
+SELECT ipv4_num_to_string(2130706432); -- 返回 '127.0.0.0'
+```
+
+通过上述示例，我们可以看到 `ipv4_num_to_string` 函数能够准确地将数字形式的 IPv4 地址转换为对应的字符串形式，方便用户进行网络相关的查询和操作。

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/ip_functions/ipv4_string_to_num.md

@@ -0,0 +1,34 @@
+### IPV4_STRING_TO_NUM 函数
+```
+ipv4_string_to_num(expr)
+```
+
+#### 功能描述
+IPV4_STRING_TO_NUM 函数用于将 IPv4 地址的字符串形式转换为内部使用的 64 位整数（bigint）格式。这对于执行基于 IP 地址的数值比较和计算非常有用。
+
+#### 参数说明
+* `expr`：string 类型，表示要转换的 IPv4 地址字符串。
+
+#### 返回结果
+* 返回一个 64 位整数（bigint），表示输入的 IPv4 地址字符串对应的数值。
+
+#### 使用示例
+1.  将本地回环地址转换为数值：
+    ```sql
+SELECT ipv4_string_to_num("127.0.0.1");
+-- 返回结果：2130706433
+```
+2.  将两个 IPv4 地址进行数值比较：
+    ```sql
+SELECT ipv4_string_to_num('192.168.1.1') > ipv4_string_to_num('192.168.1.2');
+-- 返回结果：false
+```
+3.  计算一个 IPv4 地址范围内的主机数量：
+    ```sql
+SELECT (ipv4_string_to_num('192.168.1.255') - ipv4_string_to_num('192.168.1.0') + 1) AS host_count;
+-- 返回结果：256
+```
+
+
+
+通过以上示例，您可以看到 IPV4_STRING_TO_NUM 函数在处理 IPv4 地址时的灵活性和实用性。此函数可以帮助您更方便地进行 IP 地址相关的数值计算和比较。

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/ip_functions/ipv6_num_to_string.md

@@ -0,0 +1,35 @@
+### IPv6 转换为字符串
+
+#### 功能描述
+
+`ipv6_num_to_string` 函数用于将二进制形式的 IPv6 地址转换为可读的字符串形式。该函数接受一个二进制类型的参数，并返回一个字符串类型的结果。
+
+#### 参数说明
+
+* `expr`: 二进制类型的 IPv6 地址。
+
+#### 返回结果
+
+* 返回一个字符串类型的 IPv6 地址。
+
+#### 使用示例
+
+以下示例展示了如何使用 `ipv6_num_to_string` 函数将二进制形式的 IPv6 地址转换为可读的字符串形式：
+
+将 IPv6 地址 `::ffff:127.0.0.1` 从字符串形式转换为二进制形式，然后再转换回字符串形式：
+
+```sql
+SELECT ipv6_num_to_string(ipv6_string_to_num('::ffff:127.0.0.1'));
++------------------+
+|       res        |
++------------------+
+| ::ffff:127.0.0.1 |
++------------------+
+```
+
+#### 注意事项
+
+* 请确保输入的二进制参数是有效的 IPv6 地址。
+* 在转换过程中，如果输入的参数不是有效的 IPv6 地址，函数将返回空字符串。
+
+

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/ip_functions/ipv6_string_to_num.md

@@ -0,0 +1,46 @@
+### IPV6\_STRING\_TO\_NUM 函数
+
+#### 功能描述
+
+`ipv6_string_to_num` 函数用于将 IPv6 地址的字符串形式转换为内部存储的二进制格式。该函数对于处理和比较 IPv6 地址非常有用，因为它可以消除不同表示形式之间的差异。
+
+#### 函数语法
+
+```
+ipv6_string_to_num(expr)
+```
+
+其中 `expr` 是一个表示 IPv6 地址的字符串。
+
+#### 参数说明
+
+* `expr`：一个有效的 IPv6 地址字符串。
+
+#### 返回值
+
+* 返回一个二进制格式的 IPv6 地址。
+
+#### 使用示例
+
+1.  将 IPv6 地址转换为二进制格式：
+    ```sql
+   SELECT ipv6_string_to_num('2001:0db8:85a3:0000:0000:8a2e:0370:7334') as res;
+   +---------------------------------------------------+
+   |                        res                        |
+   +---------------------------------------------------+
+   | [20 01 0d b8 85 a3 00 00 00 00 8a 2e 03 70 73 34] |
+   +---------------------------------------------------+
+   ```
+    结果为二进制格式的 IPv6 地址。
+
+2.  比较两个 IPv6 地址：
+    ```sql
+   SELECT ipv6_string_to_num('2001:0db8:85a3:0000:0000:8a2e:0370:7334') = ipv6_string_to_num('2001:0db8:85a3:0:0:8a2e:370:7334');
+   ```
+    结果为 true，表示这两个 IPv6 地址相等。
+
+#### 注意事项
+
+* 确保输入的 IPv6 地址字符串是有效的，否则函数将返回错误。
+
+

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/ip_functions/is_ip_address_in_range.md

@@ -0,0 +1,42 @@
+## 功能概述
+
+`IS_IP_ADDRESS_IN_RANGE`用于判断一个 IP 地址是否包含在某个网络范围内。该函数接受一个 IP 地址和一个表示网络范围的 CIDR 表示法字符串，返回一个布尔值，指示 IP 地址是否在指定的网络范围内。
+
+## 语法
+
+```SQL
+IS_IP_ADDRESS_IN_RANGE(address,prefix)
+```
+
+## 参数说明
+
+* **address**: 要检查的 IP 地址，可以是 IPv4 或 IPv6 地址的字符串形式。
+* **prefix**: 表示网络范围的 CIDR 表示法，也是一个字符串。
+
+## 返回结果
+
+如果 IP 地址在指定的网络范围内，返回 `true`；如果 IP 地址不在指定的网络范围内，则返回 `false`。
+
+## 示例
+
+示例 1：IPv4 地址范围检查
+
+```SQL
+SELECT is_ip_address_in_range('127.0.0.1', '127.0.0.0/8') as res;
++------+
+| res  |
++------+
+| true |
++------+
+```
+
+示例 2：IPv6 地址范围检查
+
+```SQL
+SELECT is_ip_address_in_range('::ffff:192.168.0.1', '::ffff:192.168.0.0/120') as res;
++------+
+| res  |
++------+
+| true |
++------+
+```

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/json_functions/from_json.md

@@ -0,0 +1,86 @@
+### FROM\_JSON 函数
+
+```sql
+from_json(json_string, schema)
+```
+
+#### 功能描述
+
+`FROM_JSON` 函数用于解析 JSON 格式的字符串（`json_string`），并根据提供的模式定义（`schema`）提取相应的数据。在解析过程中，未在模式中描述的 JSON 字段将被忽略，而模式中定义的字段若在 JSON 中不存在，则相应的字段值将被设置为 `NULL`。若 `json_string` 不是合法的 JSON 格式，函数将返回 `NULL`。
+
+模式定义的语法与建表时的语法相同，支持以下类型：
+
+1.  数组类型：`array<T>`，其中 `T` 为数组元素的类型。
+2.  键值对类型：`map<K, V>`，其中 `K` 为键的类型，`V` 为值的类型。
+3.  结构体类型：`struct<f1:T1, f2:T2, ... fn:Tn>`，其中 `f1, f2, ... fn` 为字段名，`T1, T2, ... Tn` 为字段类型。
+
+类型对应关系（JSON 类型转 LakeHouse 类型）：
+
+* JSON 对象（object）可转换为 LakeHouse 的结构体（struct）、映射（map）或字符串（string）。
+* JSON 数组（array）可转换为 LakeHouse 的数组（array）或字符串（string）。
+* 数值类型（numeric）可转换为 LakeHouse 的微秒整数（tinyint）、小整数（smallint）、整数（int）、大整数（bigint）、浮点数（float）、双精度浮点数（double）、十进制数（decimal）或字符串（string）。
+* 布尔类型（boolean）可转换为 LakeHouse 的布尔值（boolean）或字符串（string）。
+* 字符串类型（string）可转换为 LakeHouse 的字符串（string）、字符（char）、可变长字符串（varchar）、二进制（binary）、日期（date）或时间戳（timestamp）。
+* JSON 的 `null` 值可转换为任意类型。
+
+对于浮点数（float、double）类型，`FROM_JSON` 函数会尽量保证解析的精度；对于十进制数（decimal）类型，能保证在定义范围内的精度。
+
+#### 参数说明
+
+* `json_string`：类型为 `string`，表示包含 JSON 字符串的文本。
+* `schema`：类型为 `string`，定义了期望提取的数据结构，可以参考建表时的语法。
+
+#### 返回类型
+
+返回值的类型与模式定义（`schema`）中描述的类型一致。
+
+#### 使用示例
+
+```sql
+-- 解析 JSON 字符串为包含整数、浮点数和日期的结构体
+SELECT from_json('{"a": 1, "b": 1.0, "c": "2020-10-10"}', 'struct<a:int, b:float, c:date>');
+-- 返回结果：{"a":1,"b":1.0,"c":"2020-10-10"}
+
+-- 解析 JSON 数组为整数数组
+SELECT from_json('[1, 2, 3]', 'array<int>');
+-- 返回结果：[1,2,3]
+
+-- 解析 JSON 对象为映射
+SELECT from_json('{"name": "Alice", "age": 25}', 'map<string, string>');
+-- 返回结果：{"name":"Alice","age":"25"}
+
+-- 解析 JSON 字符串，其中包含嵌套结构体
+SELECT from_json('{"user": {"name": "Bob", "age": 30}, "active": true}', 'struct<`user`:map<string, string>, active:boolean>');
+-- 返回结果：{"user":{"name":"Bob","age":"30"},"active":true}
+
+-- 解析 JSON 数组，其中包含嵌套数组
+SELECT from_json('[{"id": 1, "name": "Product A"}, {"id": 2, "name": "Product B"}]', 'array<struct<id:int, name:string>>');
+-- 返回结果：[{"id":1,"name":"Product A"},{"id":2,"name":"Product B"}]
+```
+
+#### 注意事项
+
+* 确保提供的 JSON 字符串是合法的，否则函数将返回 `NULL`。
+* 模式定义应与 JSON 字符串中的数据结构相匹配，否则可能导致某些字段无法正确解析。
+* 在处理浮点数和十进制数时，应注意精度可能会受到影响。
+*   在使用 `from_json` 函数从 JSON 字符串中提取指定 schema 的数据时，如果 JSON 字符串中存在大小写敏感的键，可能会导致解析错误或结果不符合预期。例如：
+    ```SQL
+     select from_json('{"A":1,"a":2}','struct<A:bigint,a:bigint>');
+    java.lang.IllegalArgumentException: not all nodes and buffers were consumed. nodes: 
+    ```
+    为了避免这种错误，推荐使用 `parse_json` 函数。`parse_json` 函数能够正确处理大小写敏感的 JSON 键，并且提供了更灵活的数据访问方式。
+    ```SQL
+    select parse_json('{"A":1,"a":2}')['A'] as res;
+    +-----+
+    | res |
+    +-----+
+    | 1   |
+    +-----+
+    select parse_json('{"A":1,"a":2}')['a'] as res;
+    +-----+
+    | res |
+    +-----+
+    | 2   |
+    +-----+
+    
+    ```

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/json_functions/get_json_object.md

@@ -0,0 +1,83 @@
+### GET\_JSON\_OBJECT 函数
+
+#### 功能描述
+
+GET\_JSON\_OBJECT 函数用于从 JSON 格式的字符串（str）中提取特定字段的值。它接受两个参数：第一个参数是一个 JSON 格式的字符串，第二个参数是一个字符串，用于指定 JSON 对象中所需提取字段的路径。
+
+#### 语法格式
+
+```
+get_json_object(string <str>, string <path>)
+```
+
+#### 参数说明
+
+* str (string): 一个包含 JSON 格式数据的字符串。
+* path (string): 一个描述所需提取字段位置的字符串路径。可以参考[json path规范](<https://goessner.net/articles/JsonPath/>)
+    * "$" 表示根元素。
+    * ".key" 或者 "\['key']" 用来查找 JSON object 中的 key。特殊的，"\[\*]" 表示获取所有的 value，要求 key 必须用单引号。
+    * "\[index]" 用来根据 index 访问 JSON array 的元素，起始值为 0。特殊的，"\[\*]" 表示所有的元素。
+
+#### 返回值
+
+* 返回指定字段的值，类型为字符串。
+
+#### 使用示例
+
+1. 假设我们有一个 JSON 对象如下所示：
+   ```json
+   {
+     "name": "张三",
+     "age": 30,
+     "address": {
+       "city": "北京",
+       "zipcode": "100000"
+     },
+     "hobbies": ["篮球", "旅游", "阅读"]
+   }
+   ```
+   我们可以使用 GET\_JSON\_OBJECT 函数来提取 JSON 对象中的不同字段，例如：
+   * 提取名字：
+     ```sql
+     SELECT get_json_object('{"name": "张三", "age": 30, "address": {"city": "北京", "zipcode": "100000"}, "hobbies": ["篮球", "旅游", "阅读"]}', '$.name');
+     ```
+     结果：张三
+   * 提取城市：
+     ```sql
+     SELECT get_json_object('{"name": "张三", "age": 30, "address": {"city": "北京", "zipcode": "100000"}, "hobbies": ["篮球", "旅游", "阅读"]}', '$.address.city');
+     ```
+     结果：北京
+   * 提取所有爱好：
+     ```sql
+     SELECT get_json_object('{"name": "张三", "age": 30, "address": {"city": "北京", "zipcode": "100000"}, "hobbies": ["篮球", "旅游", "阅读"]}', '$.hobbies');
+     ```
+     结果：\["篮球", "旅游", "阅读"]
+
+2. 另一个例子，我们有一个 JSON 数组如下所示：
+   ```json
+   [
+     {
+       "id": 1,
+       "name": "产品A",
+       "price": 100
+     },
+     {
+       "id": 2,
+       "name": "产品B",
+       "price": 200
+     }
+   ]
+   ```
+   我们可以使用 GET\_JSON\_OBJECT 函数来提取数组中特定元素的字段，例如：
+   * 提取第一个产品的价格：
+     ```sql
+     SELECT get_json_object('[{"id": 1, "name": "产品A", "price": 100}, {"id": 2, "name": "产品B", "price": 200}]', '$[0].price');
+     ```
+     结果：100
+   * 提取所有产品的名称：
+     ```sql
+     SELECT get_json_object('[{"id": 1, "name": "产品A", "price": 100}, {"id": 2, "name": "产品B", "price": 200}]', '$[*].name');
+     ```
+     结果：\["产品A", "产品B"]
+
+通过以上示例，您可以看到 GET\_JSON\_OBJECT 函数在处理 JSON 数据时的灵活性和实用性。在实际应用中，您可以根据需要自由组合路径字符串，以提取 JSON 数据中的任意字段。

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/json_functions/json_array.md

@@ -0,0 +1,30 @@
+### JSON_ARRAY
+```sql
+json_array([val1, val2, ...])
+```
+#### 功能
+构造一个 JSON 数组。接受零个或多个参数，将它们转换为 JSON 数组元素。
+
+#### 参数
+* val1, val2, ... : 可选参数，任意类型的表达式，用作数组元素
+
+#### 返回结果
+* json 类型，表示 JSON 数组
+
+#### 举例
+```sql
+> SELECT json_array();
+[]
+
+> SELECT json_array(1);
+[1]
+
+> SELECT json_array(NULL);
+[null]
+
+> SELECT json_array(NULL::int, 1, TRUE, FALSE, NULL::int, "a", 1.2, 1.3d);
+[null,1,true,false,null,"a","1.2",1.3]
+```
+#### 说明
+* 支持各种基本类型，包括整数、浮点数、布尔值、字符串和 NULL。
+* 返回的 JSON 数组会压缩空格。

package/bin/skills/lakehouse-doc/references/sql_functions/scalar_functions/json_functions/json_contains.md

@@ -0,0 +1,86 @@
+###  JSON_CONTAINS
+``` sql
+json_contains(target, candidate)
+json_contains(target, candidate, jsonPath)
+```
+
+#### 功能
+检查 target JSON 对象/数组是否包含 candidate JSON 对象/数组。
+
+**两参数版本：**检查 target 是否包含 candidate
+- 对于标量值（字符串、数字、布尔值、null）：检查是否完全相等
+- 对于对象：检查 candidate 的所有键值对是否都存在于 target 中（target 可以有额外的键）
+- 对于数组：检查 candidate 的所有元素是否都能在 target 中找到（顺序无关）
+
+**三参数版本：**在 target 的指定 jsonPath 位置检查是否包含 candidate
+- jsonPath 必须是字符串字面量
+- 先按 jsonPath 从 target 中提取元素，再检查该元素是否包含 candidate
+
+#### 参数
+* target: json - 目标 JSON 对象
+* candidate: json - 待检查的候选 JSON 对象
+* jsonPath: string (可选) - JSON 路径，必须是字面量
+
+#### 返回结果
+* boolean - 如果包含返回 true，否则返回 false；如果任一参数为 NULL，返回 NULL
+
+#### 举例
+```sql
+-- 对象包含检查
+> select target, candidate, json_contains(json_parse(target), json_parse(candidate)) as contains
+  from values
+  ('{"a":1,"b":2}', '{"a":1,"b":2}'),              -- 完全匹配
+  ('{"a":1,"b":2}', '{"b":2,"a":1}'),              -- 顺序不同，内容相同
+  ('{"a":1,"b":2,"c":3}', '{"a":1}'),              -- target 包含 candidate
+  ('{"a":1,"b":2,"c":3}', '{"a":1,"b":2}'),        -- target 包含 candidate 的多个键
+  ('{"a":1,"b":2}', '{"a":1,"b":2,"c":3}'),        -- target 缺少键
+  ('{"a":{"b":1,"c":2}}', '{"a":{"b":1}}'),        -- 嵌套对象
+  ('{"a":1}', '{}')                                -- 空对象总是被包含
+  as t(target, candidate);
+{"a":1,"b":2}	{"a":1,"b":2}	true
+{"a":1,"b":2}	{"b":2,"a":1}	true
+{"a":1,"b":2,"c":3}	{"a":1}	true
+{"a":1,"b":2,"c":3}	{"a":1,"b":2}	true
+{"a":1,"b":2}	{"a":1,"b":2,"c":3}	false
+{"a":{"b":1,"c":2}}	{"a":{"b":1}}	true
+{"a":1}	{}	true
+
+-- 数组包含检查
+> select target, candidate, json_contains(json_parse(target), json_parse(candidate)) as contains
+  from values
+  ('[1,2,3]', '[1,2,3]'),                          -- 完全匹配
+  ('[1,2,3,4,5]', '[1,3,5]'),                      -- 包含所有元素（顺序无关）
+  ('[1,2,3]', '1'),                                 -- 包含单个值
+  ('[1,2,3]', '[1,2,3,4]'),                        -- candidate 有额外元素
+  ('[[1,2],[3,4]]', '[[1,2]]'),                    -- 嵌套数组（完全匹配）
+  ('[]', '[]')                                      -- 空数组
+  as t(target, candidate);
+[1,2,3]	[1,2,3]	true
+[1,2,3,4,5]	[1,3,5]	true
+[1,2,3]	1	true
+[1,2,3]	[1,2,3,4]	false
+[[1,2],[3,4]]	[[1,2]]	true
+[]	[]	true
+
+-- 数组包含对象（分布式包含）
+> select target, candidate, json_contains(json_parse(target), json_parse(candidate)) as contains
+  from values
+  ('[{"a":1},{"b":2}]', '{"a":1}'),                -- 数组包含完整对象元素
+  ('[{"a":1},{"b":2}]', '{"a":1,"b":2}')           -- 对象字段分布在数组的多个元素中
+  as t(target, candidate);
+[{"a":1},{"b":2}]	{"a":1}	true
+[{"a":1},{"b":2}]	{"a":1,"b":2}	true
+
+-- 三参数版本：指定路径的包含检查
+> select target, candidate,
+         json_contains(json_parse(target), json_parse(candidate), '$.a') as contains_at_a,
+         json_contains(json_parse(target), json_parse(candidate), '$.c') as contains_at_c
+  from values
+  ('{"a": 1, "b": 2, "c": {"d": 4}}', '1'),
+  ('{"a": 1, "b": 2, "c": {"d": 4}}', '{"d": 4}')
+  as t(target, candidate);
+{"a": 1, "b": 2, "c": {"d": 4}}	1	true	false
+{"a": 1, "b": 2, "c": {"d": 4}}	{"d": 4}	false	true
+
+```
+