YMatrix 文档

版本发布历史
系统需求

关于 YMatrix

快速上手

标准集群部署

数据建模

连接到数据库

数据写入

数据迁移

数据查询

运维监控

性能调优

故障诊断

参考指南

SQL 参考

常见问题（FAQ）

场景应用

数据表类别参数

本文档介绍了系统配置参数中 数据表类别的相关参数。

注意！
为确保系统稳定与安全，请务必谨慎手动修改相关参数。


HEAP 表/追加优化表（AO）配置参数

default_table_access_method

当 CREATE TABLE 命令未显式指定访问方式时，设置默认的表访问方式。

数据类型 默认值 取值范围 设置分类
enum heap heap / ao_row / ao_column / mars2 / mars3 master；session

gp_create_table_random_default_distribution

使用不包含 DISTRIBUTED BY 子句的 CREATE TABLE 或 CREATE TABLE AS 创建 HEAP 表时，控制表的创建。

  • 对于 CREATE TABLE，如果此参数值为 off（缺省值），并且创建表命令不包含 DISTRIBUTED BY 子句，YMatrix 数据库将根据以下命令选择表分布键：
    • 如果指定了 LIKE 或 INHERITS 子句，则 YMatrix 将从源表或父表复制分布键。
    • 如果指定了 PRIMARY KEY 或 UNIQUE 约束，则 YMatrix 会选择所有键列的最大子集作为分布键。
    • 如果既没有指定约束也没有指定 LIKE 或 INHERITS 子句，则 YMatrix 选择第一个合适的列作为分布键。（具有几何或用户定义数据类型的列不符合 YMatrix 分布键列的条件。）
  • 如果参数的值设置为 on，则当未指定 DISTRIBUTED BY 子句时，YMatrix 数据库将遵循这些规则来创建表：
    • 如果未指定 PRIMARY KEY 或 UNIQUE 列，则表的分布是随机的（DISTRIBUTED RANDOMLY）。即使表创建命令包含 LIKE 或 INHERITS 子句，表分发也是随机的。
    • 如果指定了 PRIMARY KEY 或 UNIQUE 列，则还必须指定 DISTRIBUTED BY 子句。如果未将 DISTRIBUTED BY 子句指定为表创建命令的一部分，则该命令将失败。
  • 对于不包含分布子句的 CREATE TABLE AS 命令：
    • 如果 Postgres 查询优化器创建表，并且参数的值为 off，则根据该命令确定表分发策略。
    • 如果 Postgres 查询优化器创建表，并且参数的值为 on，则表分发策略是随机的。
    • 如果 Greenplum ORCA 创建表，则表分发策略是随机的。参数值没有影响。
数据类型 默认值 设置分类
boolean off master；system；reload

gp_default_storage_options

使用 CREATE TABLE 命令创建表时，设置以下表存储选项的默认值。

  • 支持项如下，将多个存储选项值指定为逗号分隔列表：
    • appendoptimized。注意：您可以使用 appendoptimized=value 语法指定追加优化的表存储类型。 appendoptimized 是 appendonly 传统存储选项的精简别名。YMatrix 数据库在 catalog 中存储 appendonly，并在列出追加优化表的存储选项时显示相同内容。
    • blocksize
    • checksum
    • compresstype
    • compresslevel
    • orientation
  • 您可以使用此参数设置存储选项，而不是在 CREATE TABLE 命令的 WITH 中指定表存储选项。使用 CREATE TABLE 命令指定的表存储选项会覆盖此参数指定的值。
  • 并非所有存储选项值组合都有效。如果指定的存储选项无效，则返回错误。有关表存储选项的信息，请参阅 CREATE TABLE 命令。
  • 可以为数据库和用户设置默认值。如果服务器配置参数设置在不同的级别，则当用户登录到数据库并创建表时，这是表存储值的优先顺序，从最高到最低：
    • 1.CREATE TABLE 命令中使用 WITH 子句或 ENCODING 子句指定的值
    • 2.使用 ALTER ROLE...SET 命令为用户设置的 gp_default_storage_options 的值
    • 3.使用 ALTER DATABASE...SET 命令为数据库设置的 gp_default_storage_options 的值
    • 4.使用 gpconfig 工具为 YMatrix 数据库系统设置的 gp_default_storage_options 的值
  • 参数值不是累积的。例如，如果参数指定数据库的 appendoptimized 和 compresstype 选项并且用户登录并设置参数以指定 orientation 选项的值，则忽略在数据库级别设置的 appendoptimized 和 compresstype 值。
  • 此示例 ALTER DATABASE 命令为数据库 mytest 设置默认 orientation 和 compresstype 表存储选项： ALTER DATABASE mytest SET gp_default_storage_options = 'orientation=column, compresstype=rle_type'。使用面向列的表和 RLE 压缩在 mytest 数据库中创建追加优化的表。你需要在 WITH 子句中仅指定 appendoptimized=TRUE。
  • 此示例 gpconfig 工具命令设置 YMatrix 数据库系统的默认存储选项。如果为多个表存储选项设置默认值，则该值必须用单引号括起来：gpconfig -c 'gp_default_storage_options' -v 'appendoptimized=true, orientation=column'。
  • 此示例 gpconfig 工具命令显示参数的值。参数值必须在 YMatrix 数据库的 Master 和所有 Segments 之间保持一致：gpconfig -s 'gp_default_storage_options'。
默认值 取值范围 设置分类
appendoptimized=FALSE
blocksize=32768
checksum=TRUE
compresstype=none
compresslevel=0
orientation=ROW		 appendoptimized= TRUE / FALSE
blocksize= integer between 8192 and 2097152
checksum= TRUE / FALSE
compresstype= ZLIB / ZSTD / QUICKLZ2 / RLE_TYPE / NONE
compresslevel= integer between 0 and 19
orientation= ROW / COLUMN		 使用 gpconfig 工具指定：master；session；reload
建表时指定：table

gp_appendonly_compaction

在 VACUUM 命令期间启用压缩 Segment 文件。

  • 禁用时，VACUUM 仅将 Segment 文件截断为 EOF 值，当前行为也是如此。
  • 管理员可能希望在高 I/O 负载情况或低空间情况下禁用压缩。
数据类型 默认值 设置分类
boolean on master；session；reload；superuser

gp_appendonly_compaction_threshold

指定在没有 FULL 选项（惰性 VACUUM）的情况下运行 VACUUM 时隐藏行与触发压缩 Segment 文件的总行的阈值比率（百分比）。

  • 如果 Segment 上的 Segment 文件中的隐藏行的比率小于此阈值，则不压缩 Segment 文件，并发出日志消息。
数据类型 默认值 取值范围 设置分类
int 10 0 ~ 100 master；session；reload

gp_safefswritesize

指定在非成熟文件系统中，对 AO 表进行安全写入操作的最小尺寸。

  • 当指定大于 0 的字节数时，追加优化的写入器将填充数据添加到该数字，以防止由于文件系统错误导致的数据损坏。
  • 每个非成熟文件系统都具有已知的安全写入大小，在使用具有该类型文件系统的 YMatrix 数据库时必须在此处指定。
  • 这通常设置为文件系统的范围大小的倍数; 例如，Linux ext3 是 4096 字节，因此通常使用值 32768。
数据类型 默认值 取值范围 设置分类
int 0 0 ～ INT_MAX master；system；restart


MARS2 表配置参数

compress_threshold

压缩阈值。用于控制单表多少元组（Tuple）进行一次压缩，是同一个单元中压缩的 Tuple 数上限。

数据类型 默认值 取值范围 设置分类
int 1000 1 ~ 10000 table

mars2_automerge_threshold

用于控制所有的 MARS2 表，L0 达到多少个 Run 触发合并。

  • 如果要为表单独指定可以使用表选项 level0_merge_threshold。
  • 如果在 system 级别设置此参数，需要 reload 以生效；如果只是在 session 级别修改则会直接生效，无需重新加载配置。
数据类型 默认值 取值范围 设置分类
int 32 10 ~ 2048 master；session/system；reload

level0_merge_threshold

用于控制单表 L0 达到多少个 Run 触发合并。

数据类型 默认值 取值范围 设置分类
int 32 1 ~ 2048 table

level0_upgrade_size

控制单表 L0 -> L1 升级的大小（MB），当 L0 发生合并后结果 Run 超过这个大小将升级到 L1。

数据类型 默认值 取值范围 设置分类
int 25 1 ~ 10000 table

level1_upgrade_size

控制单表 L1 -> L2 升级的大小（MB），当 L1 发生合并后结果 Run 超过这个大小将升级到 L2。

数据类型 默认值 取值范围 设置分类
int 1000 1 ~ 10000 table

mars2_sort_mem

控制单个插入的排序内存大小（KB），如果插入目标表是分区表，它们将共享这个大小。

  • 默认值为 2097152KB，即 2GB。取值范围为 128KB ～ 2147483647KB（即 2048GB）。
  • 如果在 system 级别设置此参数，需要 reload 以生效；如果只是在 session 级别修改则会直接生效，无需重新加载配置。
数据类型 默认值 取值范围 设置分类
int 2097152 128 ~ 2147483647 master；session/system；reload

mars2_sort_mem_core

控制单个分区表至少分配多少排序内存。

  • 默认值为 16384KB，即 16MB。取值范围为 128KB ～ 2147483647KB（即 2048GB）。
  • 如果在 system 级别设置此参数，需要 reload 以生效；如果只是在 session 级别修改则会直接生效，无需重新加载配置。
数据类型 默认值 取值范围 设置分类
int 16384 128 ~ 2147483647 master；session/system；reload


MARS3 表配置参数

注意！
此部分参数需在建表时使用 WITH 子句配置，适用于单表，且一旦配置便无法修改。

compress_threshold

压缩阈值。用于控制单表多少元组（Tuple）进行一次压缩，是同一个单元中压缩的 Tuple 数上限。

  • 用于调节 Range 大小，也是压缩的基本单位，可用于调节压缩效果和改善读取效率，如果配置过低压缩效果不明显，配置过高消耗内存较多。
数据类型 默认值 取值范围 设置分类
int 1200 1 ~ 100000 table

level_size_amplifier

指定 Level 尺寸的放大系数。

  • Level 触发合并操作的阈值，计算方式为：rowstore_size * (level_size_amplifier ^ level)。其值越大，读速越慢，写速越快。
  • 可以根据具体场景信息（写多读少/读多写少、压缩率等）来决定具体值。
  • 注意：确保每个 Level 的 run 数量不要过多，否则会影响查询性能，甚至阻止新数据插入。
数据类型 默认值 取值范围 设置分类
int 8 1 ~ 1000 table

prefer_load_mode

指定 MARS3 内部的数据加载模式。

  • normal 表示正常模式，新写入数据先写到 L0 层的行存 Run 中，积累到 rowstore_size 之后，落至 L1 层的列存 Run，相对于 bulk 模式会多一次 I/O，列存转换由同步变成了异步，但适用于 I/O 能力充足且对延迟敏感的高频次小批量写入场景。
  • bluk 表示批量加载模式，适用于低频大批量写入场景，直接写至 L1 层的列存 Run，相对于 normal 模式，减少了一次 I/O，列存转换由异步变成了同步，适用于 I/O 能力不足且对延迟不敏感的低频大批量的数据写入。
  • 更多原理介绍请见 MARS3 原理概述。
数据类型 默认值 取值范围 设置分类
enum normal normal / bluk table


rowstore_size

用于控制 L0 Run 何时切换。当数据大小超过该参数值（以 MB 为单位），将会切换下一个 Run。

  • 与读放大成正比，与写放大成反比，可根据具体场景（写多读少/读多写少）来决定具体值。
数据类型 默认值 取值范围 设置分类
int 64 8 ~ 1024 table


MARS3 降级存储配置参数

matrixts.enable_object_cache

开启/关闭对象存储的文件系统缓存。

数据类型 默认值 设置分类
boolean off master；session；reload

mars3.degrade_credential_update_interval

设置多久更新一次会话的访问授权。

  • 为提高对象存储的安全性，某些业务中会出现定期更新密钥的情况，此参数可控制会话多久（单位为 s）从表空间的系统目录中重新收集一次授权信息，以保证访问对象存储时使用最新的授权配置。
数据类型 默认值 取值范围 设置分类
int 0 0 ～ INT_MAX master；system；reload

mars3.degrade_probe_interval

数据库后台任务定时探测满足数据转储要求与否的时间间隔（单位 s）。

  • 修改后必须 mxstop -u 重启加载配置才能生效
数据类型 默认值 取值范围 设置分类
int 3600 1 ～ INT_MAX master；system；reload

mars3.enable_object_prefetch

开启/关闭对象存储的内存缓存。

数据类型 默认值 设置分类
boolean off master；session；reload

mars3.enable_objectstore

开启/关闭自动转储功能。

  • 修改后必须 mxstop -u 重启加载配置才能生效
数据类型 默认值 设置分类
boolean off master；system；reload


外部表配置参数

gp_external_enable_exec

启用或禁用在 Segment 主机上执行操作系统命令或脚本的外部表的使用（CREATE EXTERNAL TABLE EXECUTE 语法）。

  • 如果使用 Command Center 或 MapReduce 功能，则必须启用。
数据类型 默认值 设置分类
boolean on master；system；restart

gp_external_enable_filter_pushdown

从外部表读取数据时启用过滤器下推。

  • 如果下推失败，则执行查询而不将过滤器推送到外部数据源（相反，YMatrix 数据库会对结果应用相同的约束）。
数据类型 默认值 设置分类
boolean on master；session；reload

gp_external_max_segs

设置在外部表操作期间扫描外部表数据的 Segment 数量，目的是使系统不要超载扫描数据并从其他并发操作中夺走资源。

  • 这仅适用于使用 gpfdist:// 协议访问外部表数据的外部表。
数据类型 默认值 取值范围 设置分类
int 64 1 ～ INT_MAX master；session；reload

gp_initial_bad_row_limit

假设此参数值为 n，YMatrix 数据库在使用 COPY 命令或从外部表导入数据时，如果处理的前 n 行包含格式错误，则停止处理输入行。

  • 如果在前 n 行中处理有效行，则 YMatrix 数据库继续处理输入行。
  • 将值设置为 0 将禁用此限制。
  • 还可以为 COPY 命令或外部表定义指定 SEGMENT REJECT LIMIT 子句，以限制被拒绝的行数。
  • INT_MAX 是可以作为整数存储在系统中的最大值。
数据类型 默认值 取值范围 设置分类
int 1000 0 ~ INT_MAX master；session；reload

gp_reject_percent_threshold

对于 COPY 和外部表 SELECT 上的单行错误处理，设置在 SEGMENT REJECT LIMIT n PERCENT 开始计算之前处理的行数。

数据类型 默认值 取值范围 设置分类
int 300 0 ~ INT_MAX master；session；reload

mx_discard_gpfdist_data

丢弃来自 gpfdist v1 协议的数据包。

数据类型 默认值 设置分类
boolean off master；session；reload

readable_external_table_timeout

当 SQL 查询从外部表读取时，参数值指定当数据停止从外部表返回时，YMatrix 数据库在取消查询之前等待的时间（以秒为单位）。

  • 默认值 0，指定没有超时。YMatrix 数据库不会取消查询。
  • 如果使用 gpfdist 的查询运行很长时间然后返回错误间歇性网络连接问题，则可以为 readable_external_table_timeout 设定值。 如果 gpfdist 在指定的时间内没有返回任何数据，YMatrix 数据库将取消该查询。
数据类型 默认值 取值范围 设置分类
int 0 0 ～ INT_MAX master；system；reload

writable_external_table_bufsize

YMatrix 数据库用于网络通信的缓冲区大小（KB），例如 gpfdist 实用程序和外部 Web 表（使用 HTTP）。

  • YMatrix 数据库在写入数据之前将数据存储在缓冲区中。
  • 取值范围为 32KB ～ 131072KB（即 128MB）。
数据类型 默认值 取值范围 设置分类
int 64 32 ～ 131072 segments；session；reload

verify_gpfdists_cert

使用 gpfdists 协议定义 YMatrix 数据库外部表以使用 SSL 安全性时，此参数控制是否启用 SSL 证书身份验证。

  • 默认设置为 on，当 YMatrix 数据库与 gpfdist 实用程序通信以从外部数据源读取数据或将数据写入外部数据源时，将启用 SSL 身份验证。
  • 值 off 将禁用 SSL 证书身份验证。忽略这些 SSL 异常：
    • YMatrix 数据库不信任 gpfdist 使用的自签名 SSL 证书。
    • SSL 证书中包含的主机名与运行 gpfdist 的主机名不匹配。
  • 你可以将值设置为 off 以在测试 YMatrix 数据库外部表与提供外部数据的 gpfdist 实用程序之间的通信时禁用身份验证。
  • 注意：通过不验证 gpfdists SSL 证书来禁用 SSL 证书身份验证会暴露安全风险。
数据类型 默认值 设置分类
boolean on master；session；reload