跳到主要内容
版本: 最新版本-3.5

CREATE TABLE

在 StarRocks 中创建新表。

提示

此操作需要在目标数据库上具有 CREATE TABLE 权限。

语法​

CREATE [EXTERNAL] [TEMPORARY] TABLE [IF NOT EXISTS] [database.]table_name
(column_definition1[, column_definition2, ...]
[, index_definition1[, index_definition12,]])
[ENGINE = [olap|mysql|elasticsearch|hive|hudi|iceberg|jdbc]]
[key_desc]
[COMMENT "table comment"]
[partition_desc]
[distribution_desc]
[rollup_index]
[ORDER BY (column_name1,...)]
[PROPERTIES ("key"="value", ...)]
提示
  • 您创建的表名、分区名、列名和索引名称必须遵循系统限制中的命名约定。
  • 当您指定数据库名称、表名称、列名称或分区名称时，请注意某些文字用作 StarRocks 中的保留关键字。 请勿在 SQL 语句中直接使用这些关键字。 如果您想在 SQL 语句中使用此类关键字，请将其括在一对反引号 (`) 中。 请参阅关键字，了解这些保留关键字。

关键词​

EXTERNAL​

注意

EXTERNAL 关键字已弃用。

我们建议您使用外部 Catalog 从 Hive、Iceberg、Hudi 和 JDBC 数据源查询数据，而不是使用 EXTERNAL 关键字来创建外部表。

提示

建议

从 v3.1 开始，StarRocks 支持在 Iceberg Catalog 中创建 Parquet 格式的表，并支持使用 INSERT INTO 将数据 Sink 到这些 Parquet 格式的 Iceberg 表。

从 v3.2 开始，StarRocks 支持在 Hive Catalog 中创建 Parquet 格式的表，并支持使用 INSERT INTO 将数据 Sink 到这些 Parquet 格式的 Hive 表。 从 v3.3 开始，StarRocks 支持在 Hive Catalog 中创建 ORC 和 Textfile 格式的表，并支持使用 INSERT INTO 将数据 Sink 到这些 ORC 和 Textfile 格式的 Hive 表。

如果您想使用已弃用的 EXTERNAL 关键字，请展开 **EXTERNAL 关键字详情**

EXTERNAL 关键字详情

要创建外部表来查询外部数据源，请指定 CREATE EXTERNAL TABLE 并将 ENGINE 设置为以下任何值。 您可以参考外部表以获取更多信息。

  • 对于 MySQL 外部表，请指定以下属性

    PROPERTIES (
        "host" = "mysql_server_host",
        "port" = "mysql_server_port",
        "user" = "your_user_name",
        "password" = "your_password",
        "database" = "database_name",
        "table" = "table_name"
    )

    注意

    MySQL 中的“table_name”应指示真实的表名。 相比之下，CREATE TABLE 语句中的“table_name”指示此 MySQL 表在 StarRocks 上的名称。 它们可以不同也可以相同。

    在 StarRocks 中创建 MySQL 表的目的是访问 MySQL 数据库。 StarRocks 本身不维护或存储任何 MySQL 数据。

  • 对于 Elasticsearch 外部表，请指定以下属性

    PROPERTIES (
    "hosts" = "http://192.168.xx.xx:8200,http://192.168.xx0.xx:8200",
    "user" = "root",
    "password" = "root",
    "index" = "tindex",
    "type" = "doc"
    )
    • hosts：用于连接 Elasticsearch 集群的 URL。 您可以指定一个或多个 URL。
    • user：用于登录启用基本身份验证的 Elasticsearch 集群的 root 用户的帐户。
    • password：上述 root 帐户的密码。
    • index：Elasticsearch 集群中 StarRocks 表的索引。 索引名称与 StarRocks 表名称相同。 您可以将此参数设置为 StarRocks 表的别名。
    • type：索引的类型。 默认值为 doc。

  • 对于 Hive 外部表，请指定以下属性

    PROPERTIES (
        "database" = "hive_db_name",
        "table" = "hive_table_name",
        "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083"
    )

    在此，database 是 Hive 表中相应数据库的名称。 Table 是 Hive 表的名称。 hive.metastore.uris 是服务器地址。

  • 对于 JDBC 外部表，请指定以下属性

    PROPERTIES (
    "resource"="jdbc0",
    "table"="dest_tbl"
    )

    resource 是 JDBC 资源名称，table 是目标表。

  • 对于 Iceberg 外部表，请指定以下属性

     PROPERTIES (
     "resource" = "iceberg0", 
     "database" = "iceberg", 
     "table" = "iceberg_table"
     )

    resource 是 Iceberg 资源名称。 database 是 Iceberg 数据库。 table 是 Iceberg 表。

  • 对于 Hudi 外部表，请指定以下属性

      PROPERTIES (
      "resource" = "hudi0", 
      "database" = "hudi", 
      "table" = "hudi_table" 
      )

TEMPORARY​

创建临时表。 从 v3.3.1 开始，StarRocks 支持在默认 Catalog 中创建临时表。 有关更多信息，请参阅临时表。

注意

创建临时表时，必须将 ENGINE 设置为 olap。

列定义​

col_name col_type [agg_type] [NULL | NOT NULL] [DEFAULT "default_value"] [AUTO_INCREMENT] [AS generation_expr]

col_name​

请注意，通常您不能创建名称以 __op 或 __row 开头的列，因为这些名称格式在 StarRocks 中保留用于特殊目的，创建此类列可能会导致未定义的行为。 如果您确实需要创建这样的列，请将 FE 动态参数allow_system_reserved_names 设置为 TRUE。

col_type​

特定列信息，例如类型和范围

  • TINYINT（1 字节）：范围从 -2^7 + 1 到 2^7 - 1。

  • SMALLINT（2 字节）：范围从 -2^15 + 1 到 2^15 - 1。

  • INT（4 字节）：范围从 -2^31 + 1 到 2^31 - 1。

  • BIGINT（8 字节）：范围从 -2^63 + 1 到 2^63 - 1。

  • LARGEINT（16 字节）：范围从 -2^127 + 1 到 2^127 - 1。

  • FLOAT（4 字节）：支持科学计数法。

  • DOUBLE（8 字节）：支持科学计数法。

  • DECIMAL[(precision, scale)]（16 字节）

    • 默认值：DECIMAL(10, 0)

    • precision：1 ~ 38

    • scale：0 ~ precision

    • 整数部分：precision - scale

      不支持科学计数法。

  • DATE（3 字节）：范围从 0000-01-01 到 9999-12-31。

  • DATETIME（8 字节）：范围从 0000-01-01 00:00:00 到 9999-12-31 23:59:59。

  • CHAR[(length)]：固定长度字符串。 范围：1 ~ 255。默认值：1。

  • VARCHAR[(length)]：可变长度字符串。 默认值为 1。单位：字节。 在早于 StarRocks 2.1 的版本中，length 的取值范围为 1–65533。[预览] 在 StarRocks 2.1 及更高版本中，length 的取值范围为 1–1048576。

  • HLL（1~16385 字节）：对于 HLL 类型，无需指定长度或默认值。 长度将在系统内根据数据聚合进行控制。 HLL 列只能通过hll_union_agg、Hll_cardinality 和 hll_hash 进行查询或使用。

  • BITMAP：Bitmap 类型不需要指定的长度或默认值。 它表示一组无符号 bigint 数字。 最大的元素可以达到 2^64 - 1。

agg_type​

聚合类型。 如果未指定，则此列是键列。 如果指定，则它是值列。 支持的聚合类型如下

  • SUM、MAX、MIN、REPLACE
  • HLL_UNION（仅适用于 HLL 类型）
  • BITMAP_UNION（仅适用于 BITMAP）
  • REPLACE_IF_NOT_NULL：这意味着仅当导入的数据为非空值时才会替换它。 如果它是空值，StarRocks 将保留原始值。
注意
  • 当导入聚合类型为 BITMAP_UNION 的列时，其原始数据类型必须为 TINYINT、SMALLINT、INT 和 BIGINT。
  • 如果在创建表时 REPLACE_IF_NOT_NULL 列指定了 NOT NULL，StarRocks 仍会将数据转换为 NULL，而不会向用户发送错误报告。 这样，用户可以导入选定的列。

此聚合类型仅适用于 key_desc 类型为 AGGREGATE KEY 的聚合表。 自 v3.1.9 起，REPLACE_IF_NOT_NULL 新支持 BITMAP 类型的列。

**NULL | NOT NULL**：是否允许该列为 NULL。 默认情况下，使用 Duplicate Key、Aggregate 或 Unique Key 表的表中的所有列都指定为 NULL。 在使用主键表的表中，默认情况下，值列指定为 NULL，而键列指定为 NOT NULL。 如果原始数据中包含 NULL 值，请使用 \N 表示它们。 StarRocks 在数据加载期间将 \N 视为 NULL。

**DEFAULT "default_value"**：列的默认值。 当您将数据加载到 StarRocks 中时，如果映射到该列的源字段为空，StarRocks 会自动在该列中填充默认值。 您可以通过以下方式之一指定默认值

  • **DEFAULT current_timestamp**：使用当前时间作为默认值。 有关更多信息，请参阅current_timestamp()。
  • **DEFAULT <default_value>**：使用给定列数据类型的值作为默认值。 例如，如果列的数据类型为 VARCHAR，您可以指定一个 VARCHAR 字符串，例如 beijing，作为默认值，如 DEFAULT "beijing" 所示。 请注意，默认值不能是以下任何类型：ARRAY、BITMAP、JSON、HLL 和 BOOLEAN。
  • **DEFAULT (<expr>)**：使用给定函数返回的结果作为默认值。 仅支持 uuid() 和 uuid_numeric() 表达式。

**AUTO_INCREMENT**：指定 AUTO_INCREMENT 列。 AUTO_INCREMENT 列的数据类型必须为 BIGINT。 自动递增的 ID 从 1 开始，并以 1 为步长递增。 有关 AUTO_INCREMENT 列的更多信息，请参阅AUTO_INCREMENT。 自 v3.0 起，StarRocks 支持 AUTO_INCREMENT 列。

**AS generation_expr**：指定生成的列及其表达式。 生成的列可用于预先计算和存储表达式的结果，这可以显着加速具有相同复杂表达式的查询。 自 v3.1 起，StarRocks 支持生成的列。

索引定义​

INDEX index_name (col_name[, col_name, ...]) [USING BITMAP] COMMENT 'xxxxxx'

有关参数描述和使用说明的更多信息，请参阅Bitmap 索引。

ENGINE​

默认值：olap。 如果未指定此参数，则默认情况下会创建 OLAP 表（StarRocks 原生表）。

可选值：mysql、elasticsearch、hive、jdbc、iceberg 和 hudi。

Key​

语法

key_type(k1[,k2 ...])

数据按指定的键列排序，并且对于不同的键类型具有不同的属性

  • AGGREGATE KEY：键列中相同的内容将根据指定的聚合类型聚合到值列中。 它通常适用于财务报表和多维分析等业务场景。

  • UNIQUE KEY/PRIMARY KEY：键列中相同的内容将根据导入顺序替换为值列中的内容。 它可以应用于对键列进行添加、删除、修改和查询。

  • DUPLICATE KEY：键列中相同的内容，同时也存在于 StarRocks 中。 它可以用于存储详细数据或没有聚合属性的数据。

    注意

    DUPLICATE KEY 是默认类型。 数据将按键列排序。

注意

除了 AGGREGATE KEY 之外，使用其他 key_type 创建表时，值列不需要指定聚合类型。

COMMENT​

您可以在创建表时添加表注释，这是可选的。 请注意，COMMENT 必须放置在 key_desc 之后。 否则，无法创建表。

从 v3.1 开始，您可以使用 ALTER TABLE <table_name> COMMENT = "新的表注释" 修改表注释。

分区​

可以通过以下方式管理分区

动态创建分区​

动态分区为分区提供生存时间 (TTL) 管理。 StarRocks 会自动提前创建新分区并删除过期的分区，以确保数据的新鲜度。 要启用此功能，您可以在创建表时配置动态分区相关属性。

逐个创建分区​

仅指定分区的上限​

语法

PARTITION BY RANGE ( <partitioning_column1> [, <partitioning_column2>, ... ] )
  PARTITION <partition1_name> VALUES LESS THAN ("<upper_bound_for_partitioning_column1>" [ , "<upper_bound_for_partitioning_column2>", ... ] )
  [ ,
  PARTITION <partition2_name> VALUES LESS THAN ("<upper_bound_for_partitioning_column1>" [ , "<upper_bound_for_partitioning_column2>", ... ] )
  , ... ] 
)
注意

请使用指定键列和指定值范围进行分区。

  • 有关分区的命名约定，请参阅系统限制。

  • 在 v3.3.0 之前，范围分区的列仅支持以下类型：TINYINT、SMALLINT、INT、BIGINT、LARGEINT、DATE 和 DATETIME。 从 v3.3.0 开始，可以使用三个特定的时间函数作为范围分区的列。 有关详细用法，请参阅数据分发。

  • 分区是左闭右开的。 第一个分区的左边界是最小值。

  • NULL 值仅存储在包含最小值的分区中。 当包含最小值的分区被删除时，将无法再导入 NULL 值。

  • 分区列可以是单列或多列。 分区值是默认最小值。

  • 当仅指定一列作为分区列时，您可以将 MAXVALUE 设置为最新分区的分区列的上限。

    PARTITION BY RANGE (pay_dt) (
      PARTITION p1 VALUES LESS THAN ("20210102"),
      PARTITION p2 VALUES LESS THAN ("20210103"),
      PARTITION p3 VALUES LESS THAN MAXVALUE
    )
注意
  • 分区通常用于管理与时间相关的数据。
  • 当需要数据回溯时，您可能需要考虑清空第一个分区，以便以后在必要时添加分区。

同时指定分区的下限和上限​

语法

PARTITION BY RANGE ( <partitioning_column1> [, <partitioning_column2>, ... ] )
(
    PARTITION <partition_name1> VALUES [( "<lower_bound_for_partitioning_column1>" [ , "<lower_bound_for_partitioning_column2>", ... ] ), ( "<upper_bound_for_partitioning_column1?" [ , "<upper_bound_for_partitioning_column2>", ... ] ) ) 
    [,
    PARTITION <partition_name2> VALUES [( "<lower_bound_for_partitioning_column1>" [ , "<lower_bound_for_partitioning_column2>", ... ] ), ( "<upper_bound_for_partitioning_column1>" [ , "<upper_bound_for_partitioning_column2>", ... ] ) ) 
    , ...]
)
注意
  • 固定范围比 LESS THAN 更灵活。 您可以自定义左右分区。
  • 固定范围在其他方面与 LESS THAN 相同。
  • 当仅指定一列作为分区列时，您可以将 MAXVALUE 设置为最新分区的分区列的上限。
PARTITION BY RANGE (pay_dt) (
  PARTITION p202101 VALUES [("20210101"), ("20210201")),
  PARTITION p202102 VALUES [("20210201"), ("20210301")),
  PARTITION p202103 VALUES [("20210301"), (MAXVALUE))
)

批量创建多个分区​

语法

  • 如果分区列是日期类型。

    PARTITION BY RANGE (<partitioning_column>) (
        START ("<start_date>") END ("<end_date>") EVERY (INTERVAL <N> <time_unit>)
    )

  • 如果分区列是整数类型。

    PARTITION BY RANGE (<partitioning_column>) (
        START ("<start_integer>") END ("<end_integer>") EVERY (<partitioning_granularity>)
    )

描述

您可以在 START() 和 END() 中指定开始值和结束值，并在 EVERY() 中指定时间单位或分区粒度，以批量创建多个分区。

  • 在 v3.3.0 之前，范围分区的列仅支持以下类型：TINYINT、SMALLINT、INT、BIGINT、LARGEINT、DATE 和 DATETIME。 从 v3.3.0 开始，可以使用三个特定的时间函数作为范围分区的列。 有关详细用法，请参阅数据分发。
  • 如果分区列是日期类型，则需要使用 INTERVAL 关键字指定时间间隔。 您可以将时间单位指定为小时（自 v3.0 起）、天、周、月或年。 分区的命名约定与动态分区的命名约定相同。

有关更多信息，请参阅数据分发。

分发​

StarRocks 支持哈希分桶和随机分桶。 如果您不配置分桶，StarRocks 将使用随机分桶，并默认自动设置桶数。

  • 随机分桶（自 v3.1 起）

    对于分区中的数据，StarRocks 会将数据随机分发到所有桶中，而不是基于特定的列值。 如果您希望 StarRocks 自动设置桶数，则无需指定任何分桶配置。 如果您选择手动指定桶数，则语法如下

    DISTRIBUTED BY RANDOM BUCKETS <num>

    但是，请注意，当您查询大量数据并经常使用某些列作为条件列时，随机分桶提供的查询性能可能不理想。 在这种情况下，建议使用哈希分桶。 因为只需要扫描和计算少量桶，从而显着提高查询性能。

    注意事项

    • 您只能使用随机分桶来创建 Duplicate Key 表。
    • 您不能为随机分桶的表指定Colocation Group。
    • Spark Load 不能用于将数据加载到随机分桶的表中。
    • 自 StarRocks v2.5.7 起，您无需在创建表时设置桶数。 StarRocks 会自动设置桶数。 如果您要设置此参数，请参阅设置桶数。

    有关更多信息，请参阅随机分桶。

  • 哈希分桶

    语法

    DISTRIBUTED BY HASH (k1[,k2 ...]) [BUCKETS num]

    分区中的数据可以根据分桶列的哈希值和桶数细分为多个桶。 我们建议您选择满足以下两个要求的列作为分桶列。

    • 高基数列，例如 ID
    • 查询中经常用作过滤器的列

    如果不存在这样的列，您可以根据查询的复杂性确定分桶列。

    • 如果查询很复杂，我们建议您选择一个高基数列作为分桶列，以确保数据在桶之间均匀分发，并提高集群资源利用率。
    • 如果查询相对简单，我们建议您选择经常用作查询条件的列作为分桶列，以提高查询效率。

    如果使用一个分桶列无法将分区数据均匀分发到每个桶中，您可以选择多个分桶列（最多三个）。 有关更多信息，请参阅选择分桶列。

    注意事项:

    • 创建表时，必须指定其分桶列.
    • 无法更新分桶列的值。
    • 分桶列在指定后无法修改。
    • 自 StarRocks v2.5.7 起，您无需在创建表时设置桶数。 StarRocks 会自动设置桶数。 如果您要设置此参数，请参阅设置桶数。

Rollup 索引​

您可以在创建表时批量创建 Rollup。

语法

ROLLUP (rollup_name (column_name1, column_name2, ...)
[FROM from_index_name]
[PROPERTIES ("key"="value", ...)],...)

ORDER BY​

自 v3.0 起，Primary Key 表支持使用 ORDER BY 定义排序键。 自 v3.3 起，Duplicate Key 表、Aggregate 表和 Unique Key 表支持使用 ORDER BY 定义排序键。

有关排序键的更多描述，请参阅排序键和前缀索引。

PROPERTIES​

存储和副本​

如果引擎类型为 OLAP，您可以在创建表时指定初始存储介质 (storage_medium)、自动存储冷却时间 (storage_cooldown_time) 或时间间隔 (storage_cooldown_ttl) 以及副本数 (replication_num)。

属性生效的范围：如果表只有一个分区，则属性属于表。 如果表分为多个分区，则属性属于每个分区。 当您需要为指定分区配置不同的属性时，可以在创建表后执行ALTER TABLE ... ADD PARTITION 或 ALTER TABLE ... MODIFY PARTITION。

设置初始存储介质和自动存储冷却时间​

PROPERTIES (
    "storage_medium" = "[SSD|HDD]",
    { "storage_cooldown_ttl" = "<num> { YEAR | MONTH | DAY | HOUR } "
    | "storage_cooldown_time" = "yyyy-MM-dd HH:mm:ss" }
)

属性

  • storage_medium：初始存储介质，可以设置为 SSD 或 HDD。 确保您显式指定的存储介质类型与 StarRocks 集群的 BE 磁盘类型一致，该类型在 BE 静态参数 storage_root_path 中指定。

    如果 FE 配置项 enable_strict_storage_medium_check 设置为 true，则系统会在创建表时严格检查 BE 磁盘类型。 如果您在 CREATE TABLE 中指定的存储介质与 BE 磁盘类型不一致，则会返回错误“Failed to find enough host in all backends with storage medium is SSD|HDD.”，并且表创建失败。 如果 enable_strict_storage_medium_check 设置为 false，则系统会忽略此错误并强制创建表。 但是，加载数据后，集群磁盘空间可能会不均匀分配。

    从 v2.3.6、v2.4.2、v2.5.1 和 v3.0 开始，如果未显式指定 storage_medium，系统会自动根据 BE 磁盘类型推断存储介质。

    • 在以下情况下，系统会自动将此参数设置为 SSD

      • BE 报告的磁盘类型 (storage_root_path) 仅包含 SSD。
      • BE 报告的磁盘类型 (storage_root_path) 同时包含 SSD 和 HDD。 请注意，从 v2.3.10、v2.4.5、v2.5.4 和 v3.0 开始，当 BE 报告的 storage_root_path 同时包含 SSD 和 HDD 并且指定了属性 storage_cooldown_time 时，系统会将 storage_medium 设置为 SSD。

    • 在以下情况下，系统会自动将此参数设置为 HDD

      • BE 报告的磁盘类型 (storage_root_path) 仅包含 HDD。
      • 从 2.3.10、2.4.5、2.5.4 和 3.0 开始，当 BE 报告的 storage_root_path 同时包含 SSD 和 HDD 并且未指定属性 storage_cooldown_time 时，系统会将 storage_medium 设置为 HDD。

  • storage_cooldown_ttl 或 storage_cooldown_time：自动存储冷却时间或时间间隔。 自动存储冷却是指自动将数据从 SSD 迁移到 HDD。 此功能仅在初始存储介质为 SSD 时有效。

    • storage_cooldown_ttl：此表中分区的自动存储冷却的**时间间隔**。 如果您需要将最近的分区保留在 SSD 上，并在一定时间间隔后自动将较旧的分区冷却到 HDD，则可以使用此参数。 每个分区的自动存储冷却时间是使用此参数的值加上分区的上限时间计算的。

    支持的值为 <num> YEAR、<num> MONTH、<num> DAY 和 <num> HOUR。 <num> 是一个非负整数。 默认值为 null，表示不自动执行存储冷却。

    例如，您在创建表时将值指定为 "storage_cooldown_ttl"="1 DAY"，并且存在范围为 [2023-08-01 00:00:00,2023-08-02 00:00:00) 的分区 p20230801。 此分区的自动存储冷却时间为 2023-08-03 00:00:00，即 2023-08-02 00:00:00 + 1 DAY。 如果您在创建表时将值指定为 "storage_cooldown_ttl"="0 DAY"，则此分区的自动存储冷却时间为 2023-08-02 00:00:00。

用法​

  • 与自动存储冷却相关的参数之间的比较如下

    • storage_cooldown_ttl：一个表属性，用于指定表中分区的自动存储冷却的时间间隔。 系统会在 此参数的值加上分区的上限时间 的时间自动冷却分区。 因此，自动存储冷却以分区粒度执行，这更加灵活。
    • storage_cooldown_time：一个表属性，用于指定此表的自动存储冷却时间（**绝对时间**）。 此外，您还可以在创建表后为指定分区配置不同的属性。
    • storage_cooldown_second：一个静态 FE 参数，用于指定集群中所有表的自动存储冷却延迟。

  • 表属性 storage_cooldown_ttl 或 storage_cooldown_time 的优先级高于 FE 静态参数 storage_cooldown_second。

  • 配置这些参数时，您需要指定 "storage_medium = "SSD"。

  • 如果您不配置这些参数，则不会自动执行自动存储冷却。

  • 执行 SHOW PARTITIONS FROM <table_name> 以查看每个分区的自动存储冷却时间。

限制​
  • 不支持表达式和列表分区。
  • 分区列需要是日期类型。
  • 不支持多个分区列。
  • 不支持主键表。

设置分区中每个 Tablet 的副本数​

replication_num：分区中每个表的副本数。 默认数量：3。

PROPERTIES (
    "replication_num" = "<num>"
)

Bloom filter 索引​

如果 Engine 类型为 olap，则可以指定一个列来采用 Bloom filter 索引。

使用 Bloom filter 索引时，以下限制适用

  • 您可以为 Duplicate Key 表或 Primary Key 表的所有列创建 Bloom filter 索引。 对于 Aggregate 表或 Unique Key 表，您只能为键列创建 Bloom filter 索引。
  • TINYINT、FLOAT、DOUBLE 和 DECIMAL 列不支持创建 Bloom filter 索引。
  • Bloom filter 索引只能提高包含 in 和 = 运算符的查询的性能，例如 Select xxx from table where x in {} 和 Select xxx from table where column = xxx。 此列中更多的离散值将导致更精确的查询。

有关更多信息，请参阅Bloom filter 索引

PROPERTIES (
    "bloom_filter_columns"="k1,k2,k3"
)

Colocate Join​

如果您想使用 Colocate Join 属性，请在 properties 中指定它。

PROPERTIES (
    "colocate_with"="table1"
)

动态分区​

如果您想使用动态分区属性，请在属性中指定它。

PROPERTIES (
    "dynamic_partition.enable" = "true|false",
    "dynamic_partition.time_unit" = "DAY|WEEK|MONTH",
    "dynamic_partition.start" = "${integer_value}",
    "dynamic_partition.end" = "${integer_value}",
    "dynamic_partition.prefix" = "${string_value}",
    "dynamic_partition.buckets" = "${integer_value}"

属性

参数必需描述
dynamic_partition.enable否是否启用动态分区。有效值：TRUE 和 FALSE。默认值：TRUE。
dynamic_partition.time_unit是动态创建分区的时间粒度。这是一个必填参数。有效值：DAY、WEEK 和 MONTH。时间粒度决定了动态创建分区的后缀格式。
- 如果值为 DAY，则动态创建分区的后缀格式为 yyyyMMdd。例如，分区名称后缀为 20200321。
- 如果值为 WEEK，则动态创建分区的后缀格式为 yyyy_ww，例如 2020_13 表示 2020 年的第 13 周。
- 如果值为 MONTH，则动态创建分区的后缀格式为 yyyyMM，例如 202003。
dynamic_partition.start否动态分区的起始偏移量。此参数的值必须为负整数。基于当前日期、周或月（由 dynamic_partition.time_unit 确定），将删除此偏移量之前的分区。默认值为 Integer.MIN_VALUE，即 -2147483648，这意味着不会删除历史分区。
dynamic_partition.end是动态分区的结束偏移量。此参数的值必须为正整数。将预先创建从当前日期、周或月到结束偏移量的分区。
dynamic_partition.prefix否添加到动态分区名称的前缀。默认值：p。
dynamic_partition.buckets否每个动态分区的桶数。默认值与保留字 BUCKETS 确定的桶数或 StarRocks 自动设置的桶数相同。

随机分桶的桶大小​

自 v3.2 起，对于配置了随机分桶的表，您可以在创建表时使用 PROPERTIES 中的 bucket_size 参数指定桶大小，以启用按需和动态增加桶的数量。单位：B。

PROPERTIES (
    "bucket_size" = "1073741824"
)

数据压缩算法​

您可以通过在创建表时添加属性 compression 来指定表的数据压缩算法。

compression 的有效值为

  • LZ4：LZ4 算法。
  • ZSTD：Zstandard 算法。
  • ZLIB：zlib 算法。
  • SNAPPY：Snappy 算法。

从 v3.3.2 开始，StarRocks 支持在创建表时指定 zstd 压缩格式的压缩级别。

语法

PROPERTIES ("compression" = "zstd(<compression_level>)")

compression_level：ZSTD 压缩格式的压缩级别。类型：整数。范围：[1,22]。默认值：3（推荐）。数字越大，压缩率越高。压缩级别越高，压缩和解压缩的时间消耗越大。

示例

PROPERTIES ("compression" = "zstd(3)")

有关如何选择合适的数据压缩算法的更多信息，请参见 数据压缩。

数据加载的写入仲裁​

如果您的 StarRocks 集群有多个数据副本，您可以为表设置不同的写入仲裁，即在 StarRocks 确定加载任务成功之前，需要多少个副本返回加载成功。您可以通过在创建表时添加属性 write_quorum 来指定写入仲裁。此属性自 v2.5 起支持。

write_quorum 的有效值为

  • MAJORITY：默认值。当大多数数据副本返回加载成功时，StarRocks 返回加载任务成功。否则，StarRocks 返回加载任务失败。
  • ONE：当一个数据副本返回加载成功时，StarRocks 返回加载任务成功。否则，StarRocks 返回加载任务失败。
  • ALL：当所有数据副本返回加载成功时，StarRocks 返回加载任务成功。否则，StarRocks 返回加载任务失败。
注意
  • 为加载设置较低的写入仲裁会增加数据不可访问甚至丢失的风险。例如，您在一个包含两个副本的 StarRocks 集群中，以一个写入仲裁将数据加载到表中，并且数据仅成功加载到一个副本中。尽管 StarRocks 确定加载任务成功，但只有一份数据的副本幸存。如果存储加载数据的 Tablet 的服务器发生故障，则这些 Tablet 中的数据将变得不可访问。如果服务器的磁盘损坏，则数据将丢失。
  • StarRocks 仅在所有数据副本都返回状态后才返回加载任务状态。当存在加载状态未知的副本时，StarRocks 不会返回加载任务状态。在副本中，加载超时也被视为加载失败。

副本数据写入和复制模式​

如果您的 StarRocks 集群有多个数据副本，您可以在 PROPERTIES 中指定 replicated_storage 参数来配置副本之间的数据写入和复制模式。

  • true（v3.0 及更高版本中的默认值）表示“单 Leader 复制”，这意味着数据仅写入主副本。其他副本从主副本同步数据。此模式显着降低了因将数据写入多个副本而导致的 CPU 成本。自 v2.5 起支持。
  • false（v2.5 中的默认值）表示“无 Leader 复制”，这意味着数据直接写入多个副本，而不区分主副本和辅助副本。CPU 成本乘以副本数。

在大多数情况下，使用默认值可以获得更好的数据写入性能。如果要更改副本之间的数据写入和复制模式，请运行 ALTER TABLE 命令。示例

ALTER TABLE example_db.my_table
SET ("replicated_storage" = "false");

Delta Join 唯一键和外键约束​

要启用 View Delta Join 场景中的查询重写，您必须为要在 Delta Join 中连接的表定义唯一键约束 unique_constraints 和外键约束 foreign_key_constraints。有关更多信息，请参见 异步物化视图 - 在 View Delta Join 场景中重写查询。

PROPERTIES (
    "unique_constraints" = "<unique_key>[, ...]",
    "foreign_key_constraints" = "
    (<child_column>[, ...]) 
    REFERENCES 
    [catalog_name].[database_name].<parent_table_name>(<parent_column>[, ...])
    [;...]
    "
)
  • child_column：表的外键。您可以定义多个 child_column。
  • catalog_name：要连接的表所在的 Catalog 的名称。如果未指定此参数，则使用默认 Catalog。
  • database_name：要连接的表所在的数据库的名称。如果未指定此参数，则使用当前数据库。
  • parent_table_name：要连接的表的名称。
  • parent_column：要连接的列。它们必须是相应表的主键或唯一键。
注意
  • unique_constraints 和 foreign_key_constraints 仅用于查询重写。将数据加载到表时，不保证外键约束检查。您必须确保加载到表中的数据满足约束条件。
  • Primary Key 表的主键或 Unique Key 表的唯一键默认是相应的 unique_constraints。您无需手动设置。
  • 表的 foreign_key_constraints 中的 child_column 必须引用另一个表的 unique_constraints 中的 unique_key。
  • child_column 和 parent_column 的数量必须一致。
  • child_column 和相应的 parent_column 的数据类型必须匹配。

共享数据集群的云原生表​

要使用您的 StarRocks 共享数据集群，您必须创建具有以下属性的云原生表

PROPERTIES (
    "storage_volume" = "<storage_volume_name>",
    "datacache.enable" = "{ true | false }",
    "datacache.partition_duration" = "<string_value>"
)

  • storage_volume：用于存储要创建的云原生表的存储卷的名称。如果未指定此属性，则使用默认存储卷。此属性自 v3.1 起支持。

  • datacache.enable：是否启用本地磁盘缓存。默认值：true。

    • 如果此属性设置为 true，则要加载的数据将同时写入对象存储和本地磁盘（作为查询加速的缓存）。
    • 如果此属性设置为 false，则数据仅加载到对象存储中。
    注意

    要启用本地磁盘缓存，您必须在 BE 配置文件项 storage_root_path 中指定磁盘目录。

  • datacache.partition_duration：热数据的有效期限。启用本地磁盘缓存后，所有数据都会加载到缓存中。当缓存已满时，StarRocks 会从缓存中删除最近较少使用的数据。当查询需要扫描已删除的数据时，StarRocks 会检查数据是否在有效期限内。如果数据在期限内，StarRocks 会再次将数据加载到缓存中。如果数据不在期限内，StarRocks 不会将其加载到缓存中。此属性是一个字符串值，可以使用以下单位指定：YEAR、MONTH、DAY 和 HOUR，例如 7 DAY 和 12 HOUR。如果未指定，则所有数据都将缓存为热数据。

    注意

    仅当 datacache.enable 设置为 true 时，此属性才可用。

快速 Schema 演进​

fast_schema_evolution：是否为表启用快速 Schema 演进。有效值为 TRUE 或 FALSE（默认）。启用快速 Schema 演进可以提高 Schema 更改的速度，并减少添加或删除列时的资源使用。当前，此属性只能在创建表时启用，创建表后无法使用 ALTER TABLE 进行修改。

注意
  • 自 v3.2.0 起，共享无集群支持快速 Schema 演进。
  • 自 v3.3 起，共享数据集群支持快速 Schema 演进，并且默认启用。在共享数据集群中创建云原生表时，您无需指定此属性。FE 动态参数 enable_fast_schema_evolution（默认值：true）控制此行为。

禁止 Base Compaction​

base_compaction_forbidden_time_ranges：禁止表进行 Base Compaction 的时间范围。设置此属性后，系统仅在指定时间范围之外对符合条件的 Tablet 执行 Base Compaction。此属性自 v3.2.13 起支持。

注意

确保在禁止 Base Compaction 的期间，加载到表中的数据量不超过 500。

base_compaction_forbidden_time_ranges 的值遵循 Quartz cron 语法，并且仅支持以下字段：<minute> <hour> <day-of-the-month> <month> <day-of-the-week>，其中 <minute> 必须为 *。

crontab_param_value ::= [ "" | crontab ]

crontab ::= * <hour> <day-of-the-month> <month> <day-of-the-week>
  • 如果未设置此属性或将其设置为 ""（空字符串），则在任何时间都不会禁止 Base Compaction。
  • 如果将此属性设置为 * * * * *，则始终禁止 Base Compaction。
  • 其他值遵循 Quartz cron 语法。
    • 独立值表示字段的单位时间。例如，<hour> 字段中的 8 表示 8:00-8:59。
    • 值范围表示字段的时间范围。例如，<hour> 字段中的 8-9 表示 8:00-9:59。
    • 用逗号分隔的多个值范围表示该字段的多个时间范围。
    • <day of the week> 的起始值为 1 表示星期日，7 表示星期六。

示例

-- Forbid Base Compaction from 8:00 am to 9:00 pm every day.
'base_compaction_forbidden_time_ranges' = '* 8-20 * * *'

-- Forbid Base Compaction from 0:00 am to 5:00 am and from 9:00 pm to 11:00 pm every day.
'base_compaction_forbidden_time_ranges' = '* 0-4,21-22 * * *'

-- Forbid Base Compaction from Monday to Friday (that is, allow it on Saturday and Sunday).
'base_compaction_forbidden_time_ranges' = '* * * * 2-6'

-- Forbid Base Compaction from 8:00 am to 9:00 pm every working day (that is, Monday to Friday).
'base_compaction_forbidden_time_ranges' = '* 8-20 * * 2-6'

指定通用分区表达式 TTL​

从 v3.5.0 开始，StarRocks 原生表支持通用分区表达式 TTL。

partition_retention_condition：声明要动态保留的分区的表达式。不满足表达式条件的分区将定期删除。

  • 表达式只能包含分区列和常量。不支持非分区列。
  • 通用分区表达式对 List 分区和 Range 分区的应用方式不同
    • 对于具有 List 分区的表，StarRocks 支持删除通过通用分区表达式过滤的分区。
    • 对于具有 Range 分区的表，StarRocks 只能使用 FE 的分区裁剪功能来过滤和删除分区。与分区裁剪不支持的谓词对应的分区无法被过滤和删除。

示例

-- Retain the data from the last three months. Column `dt` is the partition column of the table.
"partition_retention_condition" = "dt >= CURRENT_DATE() - INTERVAL 3 MONTH"

要禁用此功能，您可以使用 ALTER TABLE 语句将此属性设置为空字符串

ALTER TABLE tbl SET('partition_retention_condition' = '');

配置扁平 JSON 配置（目前仅在共享无集群上支持）​

如果要使用扁平 JSON 属性，请在属性中指定它。有关更多信息，请参见 扁平 JSON 

PROPERTIES (
    "flat_json.enable" = "true|false",
    "flat_json.null.factor" = "0-1",
    "flat_json.sparsity.factor" = "0-1",
    "flat_json.column.max" = "${integer_value}"
)

属性

属性必需描述
flat_json.enable否是否启用 Flat JSON 功能。启用此功能后，新加载的 JSON 数据将自动展平，从而提高 JSON 查询性能。
flat_json.null.factor否要提取的 Flat JSON 列中 NULL 值的比例。如果列中 NULL 值的比例高于此阈值，则不会提取该列。此参数仅在 flat_json.enable 设置为 true 时生效。默认值：0.3。
flat_json.sparsity.factor否具有相同名称的 Flat JSON 列的比例。如果具有相同名称的列的比例低于此值，则不执行提取。此参数仅在 flat_json.enable 设置为 true 时生效。默认值：0.9。
flat_json.column.max否Flat JSON 可以提取的最大子字段数。此参数仅在 flat_json.enable 设置为 true 时生效。默认值：100。

示例​

具有 Hash 分桶和列式存储的 Aggregate 表​

CREATE TABLE example_db.table_hash
(
    k1 TINYINT,
    k2 DECIMAL(10, 2) DEFAULT "10.5",
    v1 CHAR(10) REPLACE,
    v2 INT SUM
)
ENGINE=olap
AGGREGATE KEY(k1, k2)
COMMENT "my first starrocks table"
DISTRIBUTED BY HASH(k1)
PROPERTIES ("storage_type"="column");

具有存储介质和冷却时间设置的 Aggregate 表​

CREATE TABLE example_db.table_hash
(
    k1 BIGINT,
    k2 LARGEINT,
    v1 VARCHAR(2048) REPLACE,
    v2 SMALLINT SUM DEFAULT "10"
)
ENGINE=olap
UNIQUE KEY(k1, k2)
DISTRIBUTED BY HASH (k1, k2)
PROPERTIES(
    "storage_type"="column",
    "storage_medium" = "SSD",
    "storage_cooldown_time" = "2015-06-04 00:00:00"
);

具有 Range 分区、Hash 分桶、列式存储、存储介质和冷却时间的 Duplicate Key 表​

LESS THAN

CREATE TABLE example_db.table_range
(
    k1 DATE,
    k2 INT,
    k3 SMALLINT,
    v1 VARCHAR(2048),
    v2 DATETIME DEFAULT "2014-02-04 15:36:00"
)
ENGINE=olap
DUPLICATE KEY(k1, k2, k3)
PARTITION BY RANGE (k1)
(
    PARTITION p1 VALUES LESS THAN ("2014-01-01"),
    PARTITION p2 VALUES LESS THAN ("2014-06-01"),
    PARTITION p3 VALUES LESS THAN ("2014-12-01")
)
DISTRIBUTED BY HASH(k2)
PROPERTIES(
    "storage_medium" = "SSD", 
    "storage_cooldown_time" = "2015-06-04 00:00:00"
);

注意

此语句将创建三个数据分区

( {    MIN     },   {"2014-01-01"} )
[ {"2014-01-01"},   {"2014-06-01"} )
[ {"2014-06-01"},   {"2014-12-01"} )

这些范围之外的数据将不会被加载。

固定范围

CREATE TABLE table_range
(
    k1 DATE,
    k2 INT,
    k3 SMALLINT,
    v1 VARCHAR(2048),
    v2 DATETIME DEFAULT "2014-02-04 15:36:00"
)
ENGINE=olap
DUPLICATE KEY(k1, k2, k3)
PARTITION BY RANGE (k1, k2, k3)
(
    PARTITION p1 VALUES [("2014-01-01", "10", "200"), ("2014-01-01", "20", "300")),
    PARTITION p2 VALUES [("2014-06-01", "100", "200"), ("2014-07-01", "100", "300"))
)
DISTRIBUTED BY HASH(k2)
PROPERTIES(
    "storage_medium" = "SSD"
);

MySQL 外部表​

CREATE EXTERNAL TABLE example_db.table_mysql
(
    k1 DATE,
    k2 INT,
    k3 SMALLINT,
    k4 VARCHAR(2048),
    k5 DATETIME
)
ENGINE=mysql
PROPERTIES
(
    "host" = "127.0.0.1",
    "port" = "8239",
    "user" = "mysql_user",
    "password" = "mysql_passwd",
    "database" = "mysql_db_test",
    "table" = "mysql_table_test"
)

具有 HLL 列的表​

CREATE TABLE example_db.example_table
(
    k1 TINYINT,
    k2 DECIMAL(10, 2) DEFAULT "10.5",
    v1 HLL HLL_UNION,
    v2 HLL HLL_UNION
)
ENGINE=olap
AGGREGATE KEY(k1, k2)
DISTRIBUTED BY HASH(k1)
PROPERTIES ("storage_type"="column");

使用 BITMAP_UNION 聚合类型的表​

v1 和 v2 列的原始数据类型必须为 TINYINT、SMALLINT 或 INT。

CREATE TABLE example_db.example_table
(
    k1 TINYINT,
    k2 DECIMAL(10, 2) DEFAULT "10.5",
    v1 BITMAP BITMAP_UNION,
    v2 BITMAP BITMAP_UNION
)
ENGINE=olap
AGGREGATE KEY(k1, k2)
DISTRIBUTED BY HASH(k1)
PROPERTIES ("storage_type"="column");

支持 Colocate Join 的表​

CREATE TABLE `t1` 
(
     `id` int(11) COMMENT "",
    `value` varchar(8) COMMENT ""
) 
ENGINE=OLAP
DUPLICATE KEY(`id`)
DISTRIBUTED BY HASH(`id`)
PROPERTIES 
(
    "colocate_with" = "t1"
);

CREATE TABLE `t2` 
(
    `id` int(11) COMMENT "",
    `value` varchar(8) COMMENT ""
) 
ENGINE=OLAP
DUPLICATE KEY(`id`)
DISTRIBUTED BY HASH(`id`)
PROPERTIES 
(
    "colocate_with" = "t1"
);

具有 Bitmap 索引的表​

CREATE TABLE example_db.table_hash
(
    k1 TINYINT,
    k2 DECIMAL(10, 2) DEFAULT "10.5",
    v1 CHAR(10) REPLACE,
    v2 INT SUM,
    INDEX k1_idx (k1) USING BITMAP COMMENT 'xxxxxx'
)
ENGINE=olap
AGGREGATE KEY(k1, k2)
COMMENT "my first starrocks table"
DISTRIBUTED BY HASH(k1)
PROPERTIES ("storage_type"="column");

动态分区表​

必须在 FE 配置中启用动态分区功能（“dynamic_partition.enable” = “true”）。有关更多信息，请参见 配置动态分区。

此示例为接下来的三天创建分区，并删除三天前创建的分区。例如，如果今天是 2020-01-08，则将创建以下名称的分区：p20200108、p20200109、p20200110、p20200111，它们的范围是

[types: [DATE]; keys: [2020-01-08]; ‥types: [DATE]; keys: [2020-01-09]; )
[types: [DATE]; keys: [2020-01-09]; ‥types: [DATE]; keys: [2020-01-10]; )
[types: [DATE]; keys: [2020-01-10]; ‥types: [DATE]; keys: [2020-01-11]; )
[types: [DATE]; keys: [2020-01-11]; ‥types: [DATE]; keys: [2020-01-12]; )
CREATE TABLE example_db.dynamic_partition
(
    k1 DATE,
    k2 INT,
    k3 SMALLINT,
    v1 VARCHAR(2048),
    v2 DATETIME DEFAULT "2014-02-04 15:36:00"
)
ENGINE=olap
DUPLICATE KEY(k1, k2, k3)
PARTITION BY RANGE (k1)
(
    PARTITION p1 VALUES LESS THAN ("2014-01-01"),
    PARTITION p2 VALUES LESS THAN ("2014-06-01"),
    PARTITION p3 VALUES LESS THAN ("2014-12-01")
)
DISTRIBUTED BY HASH(k2)
PROPERTIES(
    "storage_medium" = "SSD",
    "dynamic_partition.enable" = "true",
    "dynamic_partition.time_unit" = "DAY",
    "dynamic_partition.start" = "-3",
    "dynamic_partition.end" = "3",
    "dynamic_partition.prefix" = "p",
    "dynamic_partition.buckets" = "10"
);

以批处理方式创建多个分区，并以整数列作为分区列的表​

在以下示例中，分区列 datekey 的类型为 INT。所有分区仅由一个简单的分区子句 START ("1") END ("5") EVERY (1) 创建。所有分区的范围从 1 开始到 5 结束，分区粒度为 1

注意

START() 和 END() 中的分区列值需要用引号括起来，而 EVERY() 中的分区粒度不需要用引号括起来。

CREATE TABLE site_access (
    datekey INT,
    site_id INT,
    city_code SMALLINT,
    user_name VARCHAR(32),
    pv BIGINT DEFAULT '0'
)
ENGINE=olap
DUPLICATE KEY(datekey, site_id, city_code, user_name)
PARTITION BY RANGE (datekey) (START ("1") END ("5") EVERY (1)
)
DISTRIBUTED BY HASH(site_id)
PROPERTIES ("replication_num" = "3");

Hive 外部表​

在创建 Hive 外部表之前，您必须已经创建了 Hive 资源和数据库。有关更多信息，请参见 外部表。

CREATE EXTERNAL TABLE example_db.table_hive
(
    k1 TINYINT,
    k2 VARCHAR(50),
    v INT
)
ENGINE=hive
PROPERTIES
(
    "resource" = "hive0",
    "database" = "hive_db_name",
    "table" = "hive_table_name"
);

具有特定排序键的 Primary Key 表​

假设您需要从用户地址和上次活动时间等维度实时分析用户行为。创建表时，您可以将 user_id 列定义为主键，并将 address 和 last_active 列的组合定义为排序键。

create table users (
    user_id bigint NOT NULL,
    name string NOT NULL,
    email string NULL,
    address string NULL,
    age tinyint NULL,
    sex tinyint NULL,
    last_active datetime,
    property0 tinyint NOT NULL,
    property1 tinyint NOT NULL,
    property2 tinyint NOT NULL,
    property3 tinyint NOT NULL
) 
PRIMARY KEY (`user_id`)
DISTRIBUTED BY HASH(`user_id`)
ORDER BY(`address`,`last_active`)
PROPERTIES(
    "replication_num" = "3",
    "enable_persistent_index" = "true"
);

分区临时表​

CREATE TEMPORARY TABLE example_db.temp_table
(
    k1 DATE,
    k2 INT,
    k3 SMALLINT,
    v1 VARCHAR(2048),
    v2 DATETIME DEFAULT "2014-02-04 15:36:00"
)
ENGINE=olap
DUPLICATE KEY(k1, k2, k3)
PARTITION BY RANGE (k1)
(
    PARTITION p1 VALUES LESS THAN ("2014-01-01"),
    PARTITION p2 VALUES LESS THAN ("2014-06-01"),
    PARTITION p3 VALUES LESS THAN ("2014-12-01")
)
DISTRIBUTED BY HASH(k2);

支持 Flat JSON 的表​

注意

Flat JSON 目前仅在共享无集群上支持。

CREATE TABLE example_db.example_table
(
    k1 DATE,
    k2 INT,
    v1 VARCHAR(2048),
    v2 JSON
)
ENGINE=olap
DUPLICATE KEY(k1, k2)
DISTRIBUTED BY HASH(k2)
PROPERTIES (
    "flat_json.enable" = "true",
    "flat_json.null.factor" = "0.5",
    "flat_json.sparsity.factor" = "0.5",
    "flat_json.column.max" = "50"
);

参考​