Variant类型

Variant与JSON/JSONB的区别

JSON、JSONB和Variant均可表示半结构化数据，但适用的数据位置、物理编码和查询优化方式不同。JSON和JSONB的详细说明，请参见JSON和JSONB类型。

常用操作符

Variant类型支持的操作符如下表所示，语义与JSON/JSONB操作符保持一致。

Typed Cast（类型化转换）

Variant类型支持通过::type语法将子字段直接转换为原生类型，无需先转为TEXT再解析。支持的目标类型如下表所示。

投影字段裁剪

当查询仅涉及Variant对象中的个别字段时，引擎只读取被Shredded的物理子列，跳过其他字段的数据。例如对一个包含20个字段的Variant列，仅查询v->'age'时，只需读取age对应的typed_value列，I/O开销与读取单个普通INT列相当。

RowGroup DataSkip

对于Shredded子列，Parquet的RowGroup级统计信息（min、max、null_count）自动生效。查询引擎在扫描前根据过滤条件的统计信息跳过不满足条件的RowGroup，大幅减少I/O扫描量。

以下示例对50万行表执行点查，利用Shredded子列的RowGroup统计信息跳过大部分数据。

SELECT id, (v->'seq')::int8 AS seq
FROM ext_dlf.variant_acc.v_skip
WHERE (v->'seq')::int8 = 250000;

通过EXPLAIN ANALYZE可以观察DataSkip效果。

->  Seq Scan on v_skip
      Filter: (((v -> 'seq'::text))::bigint = '250000'::bigint)
      RowGroupFilter: (((v -> 'seq'::text))::bigint = '250000'::bigint)
      [scan_rows=3868]

上述执行计划中，RowGroupFilter表明过滤条件被用于RowGroup级裁剪，全表50万行仅实际扫描3868行。

基本读取

以下示例演示如何通过DLF外部数据库读取Paimon表中的Variant列。创建外部数据库的详细语法，请参见CREATE EXTERNAL DATABASE；通过DLF访问Paimon数据的完整流程，请参见基于DLF Catalog访问Paimon数据。

-- 1. 创建外部数据库（如尚未创建）
CREATE EXTERNAL DATABASE ext_dlf WITH
  catalog_type 'paimon'
  metastore_type 'dlf-rest'
  dlf_catalog '<YOUR_CATALOG_NAME>'
  comment 'DLF Paimon catalog';

-- 2. 直接读取Variant列
SELECT id, v::text
FROM ext_dlf.<YOUR_SCHEMA>.<YOUR_TABLE>
ORDER BY id
LIMIT 10;

执行结果示例如下。

 id |                    v
----+-----------------------------------------
  0 | {"age": 21, "city": "Beijing"}
  1 | {"age": 27}
  2 | {"city": "Beijing", "other": "xxx"}
  3 | {"other": "yyy"}
  4 | {"age": 28, "nested": {"k": [1, 2, 3]}}
(5 行记录)

多字段共投影

可同时提取Variant对象中的多个字段，每个字段独立进行typed cast。

SELECT
  id,
  v::text AS raw,
  (v->'age')::int8 AS age,
  (v->'city')::text AS city
FROM ext_dlf.<YOUR_SCHEMA>.<YOUR_TABLE>
ORDER BY id;

执行结果示例如下。

 id |                   raw                   | age  |   city
----+-----------------------------------------+------+-----------
  0 | {"age": 21, "city": "Beijing"}          |   21 | "Beijing"
  1 | {"age": 27}                             |   27 |
  2 | {"city": "Beijing", "other": "xxx"}     |      | "Beijing"
  3 | {"other": "yyy"}                        |      |
  4 | {"age": 28, "nested": {"k": [1, 2, 3]}} |   28 |
(5 行记录)

嵌套路径访问

使用#>操作符访问嵌套对象。

SELECT (v#>'{nested,k}')::text AS nested_array
FROM ext_dlf.<YOUR_SCHEMA>.<YOUR_TABLE>
WHERE id = 4;

执行结果如下。

 nested_array
--------------
 [1, 2, 3]
(1 行记录)

数组下标访问

以Variant值为[10, 20, 30]的行为例，通过数组下标访问各元素。

SELECT
  (v->0)::text AS idx0,
  (v->1)::text AS idx1,
  (v->2)::text AS idx2
FROM ext_dlf.<YOUR_SCHEMA>.<YOUR_TABLE>
WHERE id = 5;

执行结果如下。

 idx0 | idx1 | idx2
------+------+------
 10   | 20   | 30
(1 行记录)

键存在性检查

使用?操作符判断键是否存在。

SELECT id, v?'age' AS has_age
FROM ext_dlf.<YOUR_SCHEMA>.<YOUR_TABLE>
WHERE id IN (0, 3)
ORDER BY id;

执行结果如下。

 id | has_age
----+---------
  0 | t
  3 | f
(2 行记录)

使用Variant字段排序与聚合

Variant子字段经typed cast后可直接用于排序和聚合。

-- 按age字段排序
SELECT id
FROM ext_dlf.<YOUR_SCHEMA>.<YOUR_TABLE>
ORDER BY (v->'age')::int8 NULLS LAST
LIMIT 5;

-- 按age字段聚合
SELECT (v->'age')::int8 AS age, COUNT(*)
FROM ext_dlf.<YOUR_SCHEMA>.<YOUR_TABLE>
GROUP BY 1
ORDER BY 1 NULLS LAST;

访问不存在的字段

Variant列的根值可以是任意JSON值类型，不限于对象。对于非对象根值（数组、字符串、数字、布尔值、null），通过->访问不存在的键将返回SQL NULL。以下示例中，id为5至9的行的Variant值依次为[10,20,30]、"scalar string"、12345、true和null。

SELECT
  id,
  v::text,
  (v->'nokey')::int8 AS n_int,
  (v->'nokey')::text AS n_text
FROM ext_dlf.<YOUR_SCHEMA>.<YOUR_TABLE>
WHERE id >= 5
ORDER BY id;

执行结果如下。

 id |        v        | n_int | n_text
----+-----------------+-------+--------
  5 | [10, 20, 30]    |       |
  6 | "scalar string" |       |
  7 | 12345           |       |
  8 | true            |       |
  9 | null            |       |
(5 行记录)