支持的数据类型

参数

• column_name：列名称。

• data_type：类型修饰符，例如 varchar(n)、numeric(p,s) 和 bit(n)，先由 PostgreSQL 检查，再映射到 DuckDB。取值范围：

  • 标量类型：列出的标量类型。

  • 数组类型：列出的一维数组类型。

示例

CREATE TABLE columnar_type_example (
  id bigint,
  amount numeric(18, 4),
  ratio double precision,
  enabled boolean,
  label text,
  payload jsonb,
  raw bytea,
  event_time timestamptz,
  request_id uuid
) USING duckdb;

语法

numeric [ ( precision [, scale ] ) ]
decimal [ ( precision [, scale ] ) ]

参数

• precision：有效数字总位数，DuckDB DECIMAL 最大为 38

• scale：小数位数，负 scale 不受支持

使用说明

建议优先声明精度和小数位数：

amount numeric(18, 2)

• numeric(p,s) 在 p <= 38 且 scale 有效时映射为与声明一致的 DECIMAL(p,s)。未声明精度的 numeric 默认只有 10 位小数，超过目标小数位数（即声明的 scale 或 polar_csi.decimal_default 指定的小数位数）的小数位会丢失，超出目标整数位范围的值会报转换错误。

• PostgreSQL numeric 的 NaN、Infinity 和 -Infinity 不能表示成 DuckDB DECIMAL，INSERT 路径会把这些非有限值写成 NULL，应避免向列存 numeric 列写入非有限值。

• 浮点类型 real 和 double precision 可以保存浮点 NaN 和无穷值，它们与 numeric 的行为不同。

语法

element_type[]

支持下列一维数组：

• boolean[]

• smallint[]、integer[]、bigint[]、oid[]

• numeric[]、real[]、double precision[]

• character[]、varchar[]、text[]

• date[]、time[]、timetz[]、timestamp[]、timestamptz[]、interval[]

• uuid[]、bytea[]

• json[]、jsonb[]

示例：

数组可以为空，也可以包含 NULL 元素：

CREATE TABLE columnar_array_example (
  id integer,
  values integer[],
  labels text[]
) USING duckdb;

INSERT INTO columnar_array_example VALUES
  (1, ARRAY[1, NULL, 3], ARRAY['a', 'b']),
  (2, ARRAY[]::integer[], NULL);

数组维度和下界

DuckDB 列存数组只保存一维、下界为 1 的值。以下两种写入会报错。多行 INSERT 中任一行触发该类错误时，整条语句失败并回滚，已处理的行不会保留。

• 多维数组不受支持：

  INSERT INTO columnar_array_example
  VALUES (3, ARRAY[[1, 2], [3, 4]], NULL);

  ERROR:  multidimensional arrays are not supported on duckdb tables
  DETAIL:  The array has 2 dimensions, but DuckDB storage only supports empty or one-dimensional arrays.

• 下界不是 1 的数组不受支持：

  INSERT INTO columnar_array_example
  VALUES (4, '[5:7]={10,20,30}'::integer[], NULL);

  ERROR:  array lower bounds other than 1 are not supported on duckdb tables
  DETAIL:  The array lower bound is 5, but DuckDB storage only supports lower bound 1.

PostgreSQL 内部单字节类型 "char"[] 明确不受支持。它与 SQL 定长字符数组 character[] 不是同一种类型。

numeric[]

未声明精度的 numeric[] 使用 polar_csi.decimal_default 指定的元素类型，默认映射为 DuckDB DECIMAL(38,10)[]。显式声明且精度不超过 38 的 numeric(p,s)[] 保留声明的精度和小数位数。精度大于 38 时使用 polar_csi.decimal_default。

• 默认 DECIMAL(38,10)[] 映射下，每个元素最多有 38 位有效数字，其中 10 位为小数，超出范围时整条写入报转换错误。

• NaN、Infinity 和 -Infinity 元素会写成 NULL。

需要超过默认的 10 位小数、超过该范围，或不能接受非有限值变成 NULL 时，不应使用默认映射的 numeric[]。可以把数值拆成标量列、改用受控的整数缩放表示，或以文本保存后显式解析。

示例

对跨时区交换的数据，建议显式设置会话时区，并把偏移写进字面量：

SET timezone = 'UTC';

INSERT INTO columnar_type_example (id, event_time)
VALUES (1, TIMESTAMPTZ '2026-08-26 08:00:00+00');

示例

INSERT INTO columnar_type_example (id, payload, raw)
VALUES (
  2,
  '{"event":"click","ok":true}'::jsonb,
  '\x00ff'::bytea
);

语法

ALTER TABLE table_name
ALTER COLUMN column_name TYPE data_type;

DuckDB 必须能把所有已有值转换成新类型，且语句不能使用 USING。

示例

ALTER TABLE columnar_type_example
ALTER COLUMN id TYPE numeric(20, 0);

不确定转换是否兼容时，应使用CREATE TABLE AS SELECT创建新列存表并显式转换数据。列存表不支持以另一张列存表作为 INSERT ... SELECT 的数据来源，复制列存表数据请使用CREATE TABLE AS SELECT：

CREATE TABLE columnar_type_example_new
USING duckdb AS
SELECT id::numeric(20, 0), amount::numeric(20, 4)
FROM columnar_type_example;