Amazon Keyspaces 中的 DDL 语句（数据定义语言） - Amazon Keyspaces（Apache Cassandra 兼容）
Keyspaces表

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

Amazon Keyspaces 中的 DDL 语句（数据定义语言）

数据定义语言 (DDL) 是一组用于管理 Amazon Keyspaces（Apache Cassandra 兼容）中的数据结构（如键空间和表）的 Cassandra 查询语言 (CQL) 语句。可以使用 DDL 创建这些数据结构，在创建数据结构后对其进行修改，以及在不再使用数据结构时将其删除。Amazon Keyspaces 以异步方式执行 DDL 操作。有关如何确认异步操作已完成的更多信息，请参阅异步创建与删除键空间和表。

支持以下 DDL 语句：

Keyspaces

键空间 对与一个或多个应用程序相关的表进行分组。就关系数据库管理系统 (RDBMS) 而言，键空间与数据库、表空间或类似的结构大致相似。

注意

在 Apache Cassandra 中，键空间将决定如何在多个存储节点之间复制数据。但是，Amazon Keyspaces 是一项完全托管式服务：系统将为您管理其存储层的详细信息。因此，Amazon Keyspaces 中的键空间只是逻辑结构，并且与底层物理存储无关。

有关 Amazon Keyspaces 键空间的配额限制和约束的信息，请参阅 Amazon Keyspaces（Apache Cassandra 兼容）限额。

CREATE KEYSPACE

使用 CREATE KEYSPACE 语句可创建新的键空间。

语法

create_keyspace_statement ::= 
    CREATE KEYSPACE [ IF NOT EXISTS ] keyspace_name
    WITH options

其中：

  • keyspace_name 是要创建的键空间的名称。

  • 选项 为下列一个或多个项：

    • REPLICATION：表示键空间复制策略的映射：

      • SingleRegionStrategy：用于单区域键空间。（必需）

      • NetworkTopologyStrategy— 指定至少两个，最多六个 AWS 区域。每个区域的复制因子为 3。（可选）

    • DURABLE_WRITES：由于对 Amazon Keyspaces 的写入操作始终是持久的，因此此选项不是必需的。但是，如果指定此选项，则值必须为 true。

    • TAGS：创建资源时要附加到资源的键值对标签的列表。（可选）

示例

创建键空间，如下所示。

CREATE KEYSPACE my_keyspace
    WITH REPLICATION = {'class': 'SingleRegionStrategy'} and TAGS ={'key1':'val1', 'key2':'val2'} ;

要创建多区域键空间，请指定 NetworkTopologyStrategy 并包含最少两个、最多六个 AWS 区域。每个区域的复制因子为 3。

CREATE KEYSPACE my_keyspace
    WITH REPLICATION = {'class':'NetworkTopologyStrategy', 'us-east-1':'3', 'ap-southeast-1':'3','eu-west-1':'3'};

ALTER KEYSPACE

使用 ALTER KEYSPACE 可在键空间中添加或删除标签。

语法

alter_keyspace_statement ::= 
    ALTER KEYSPACE keyspace_name
    [[ADD | DROP] TAGS

其中：

  • keyspace_name 是要更改的键空间的名称。

  • TAGS：要在键空间中添加或删除的键值对标签的列表。

示例

更改键空间，如下所示。

ALTER KEYSPACE "myGSGKeyspace" ADD TAGS {'key1':'val1', 'key2':'val2'};

DROP KEYSPACE

使用 DROP KEYSPACE 语句可删除键空间，包括其所有内容（如表）。

语法

drop_keyspace_statement ::= 
    DROP KEYSPACE [ IF EXISTS ] keyspace_name

其中：

  • keyspace_name 是要删除的键空间的名称。

示例

DROP KEYSPACE "myGSGKeyspace";

表

表是 Amazon Keyspaces 中的主要数据结构。表中的数据按行和列进行组织。这些列的子集用于通过指定分区键来确定分区（以及最终的数据放置）。

可以将另一组列定义为聚类列，这意味着它们可以作为谓词参与查询执行。

默认情况下，将创建具有按需 吞吐容量的新表。您可以更改新表和现有表的容量模式。有关读/写容量吞吐量模式的更多信息，请参阅 Amazon Keyspaces 中的读/写容量模式。

对于处于预配模式的表，您可以配置可选AUTOSCALING_SETTINGS。有关 Amazon Keyspaces 自动扩展和可用选项的更多信息，请参阅。使用 Cassandra 查询语言 (CQL) 管理 Amazon Keyspaces 自动扩展

有关 Amazon Keyspaces 表的配额限制和约束的信息，请参阅 Amazon Keyspaces（Apache Cassandra 兼容）限额。

CREATE TABLE

使用 CREATE TABLE 语句可创建新表。

语法

create_table_statement ::=  CREATE TABLE [ IF NOT EXISTS ] table_name
    '('
        column_definition 
        ( ',' column_definition )*
        [ ',' PRIMARY KEY '(' primary_key ')' ]
    ')' [ WITH table_options ]

column_definition      ::=  column_name cql_type [ FROZEN ][ STATIC ][ PRIMARY KEY]

primary_key            ::=  partition_key [ ',' clustering_columns ]

partition_key          ::=  column_name
                              | '(' column_name ( ',' column_name )* ')'

clustering_columns     ::=  column_name ( ',' column_name )*

table_options          ::=  [table_options]
                              | CLUSTERING ORDER BY '(' clustering_order ')' [ AND table_options ]
                              | options
                              | CUSTOM_PROPERTIES
                              | AUTOSCALING_SETTINGS
                              | default_time_to_live
                              | TAGS

clustering_order       ::=  column_name (ASC | DESC) ( ',' column_name (ASC | DESC) )*

其中：

  • table_name 是要创建的表的名称。

  • column_definition 包含以下各项：

    • column_name：列的名称。

    • cql_type：一种 Amazon Keyspaces 数据类型（参见数据类型）。

    • FROZEN：将 collection 类型（例如 LIST、SET 或 MAP）的此列指定为已冻结。冻结集合将被序列化为单个不可变值，并被视为 BLOB。有关更多信息，请参阅 集合类型。

    • STATIC：将此列指定为静态。静态列存储由同一分区中的所有行共享的值。

    • PRIMARY KEY：将此列指定为表的主键。

  • primary_key 包含以下各项：

    • partition_key

    • clustering_columns

  • partition_key:

    • 分区键可以是单个列，也可以是由两列或多个列组成的复合值。主键的分区键部分是必需的，它决定了 Amazon Keyspaces 存储数据的方式。

  • clustering_columns:

    • 主键的可选聚类列部分决定如何在每个分区中聚类和排序数据。

  • table_options 包含以下各项：

    • CLUSTERING ORDER BY：表上的默认 CLUSTERING ORDER 包含 ASC（升序）排序方向的聚类键。指定它可覆盖默认排序行为。

    • CUSTOM_PROPERTIES：特定于 Amazon Keyspaces 的设置的映射。

      • capacity_mode：指定表的读/写吞吐容量模式。选项为 throughput_mode:PAY_PER_REQUEST 和 throughput_mode:PROVISIONED。预置容量模式要求将 read_capacity_units 和 write_capacity_units 作为输入。默认值为 throughput_mode:PAY_PER_REQUEST。

      • client_side_timestamps：指定为表启用还是禁用客户端时间戳。选项为 {'status': 'enabled'} 和 {'status': 'disabled'}。如果未指定，则默认为 status:disabled。为表启用客户端时间戳后便无法禁用该设置。

      • encryption_specification：为静态加密指定加密选项。如果未指定，则默认为 encryption_type:AWS_OWNED_KMS_KEY。加密选项客户托管密钥要求输入 Amazon 资源名称 (ARN) 格式的 AWS KMS 密钥作为输入:: kms_key_identifier:ARN。kms_key_identifier:ARN

      • point_in_time_recovery：指定是启用还是禁用表的 point-in-time 还原。选项为 status:enabled 和 status:disabled。如果未指定，则默认为 status:disabled。

      • replica_updates：指定多区域表中特定于的 AWS 区域设置。对于多区域表，您可以根据不同的方式配置表的读取容量。 AWS 区域您可以通过配置以下参数来做到这一点。有关更多信息以及示例，请参阅 创建具有预置容量模式和 auto Scaling (CQL) 的多区域表。

        • region— 具有以下设置 AWS 区域 的表副本的：

          • read_capacity_units

      • TTL：为表启用存活时间自定义设置。要启用，请使用 status:enabled。默认值为 status:disabled。为表启用 TTL 后便无法禁用该设置。

    • AUTOSCALING_SETTINGS包括置备模式下的表的以下可选设置。有关更多信息以及示例，请参阅 使用 CQL 创建具有自动缩放功能的新表。

      • provisioned_write_capacity_autoscaling_update:

        • autoscaling_disabled— 要为写入容量启用 auto 缩放，请将该值设置为false。默认值为 true。（可选）

        • minimum_units— 表应随时准备支持的最低写入吞吐量级别。该值必须介于 1 和您账户的最大每秒吞吐量配额（默认为 40,000）之间。

        • maximum_units— 表应随时准备支持的最大写入吞吐量级别。该值必须介于 1 和您账户的最大每秒吞吐量配额（默认为 40,000）之间。

        • scaling_policy— Amazon Keyspaces 支持目标跟踪政策。auto Scaling 目标是表的预配置写入容量。

          • target_tracking_scaling_policy_configuration— 要定义目标跟踪策略，必须定义目标值。有关目标跟踪和冷却时间的更多信息，请参阅 App lication Auto Scaling 用户指南中的目标跟踪扩展策略。

            • target_value— 表格的目标利用率。Amazon Keyspaces 自动扩展可确保已用容量与预配置容量的比率保持在该值或接近该值。您将 target_value 定义为百分比。20 到 90 之间的双打。（必需）

            • scale_in_cooldown— 两次缩放活动之间的冷却时间（以秒为单位），可让表格在另一个缩放活动开始之前稳定下来。如果未提供任何值，则默认值为 0。（可选）

            • scale_out_cooldown— 两次扩展活动之间的冷却时间（以秒为单位），可让表格在另一个扩展活动开始之前稳定下来。如果未提供任何值，则默认值为 0。（可选）

            • disable_scale_in: Aboolean，它指定该表scale-in是禁用还是启用。默认情况下，此参数处于禁用状态。要开启scale-in，请将该boolean值设置为FALSE。这意味着代表您自动缩小餐桌的容量。（可选）

      • provisioned_read_capacity_autoscaling_update:

        • autoscaling_disabled— 要为读取容量启用 auto 缩放，请将该值设置为false。默认值为 true。（可选）

        • minimum_units— 表应随时准备支持的最低吞吐量级别。该值必须介于 1 和您账户的最大每秒吞吐量配额（默认为 40,000）之间。

        • maximum_units— 表应随时准备支持的最大吞吐量级别。该值必须介于 1 和您账户的最大每秒吞吐量配额（默认为 40,000）之间。

        • scaling_policy— Amazon Keyspaces 支持目标跟踪政策。auto Scaling 目标是表的预配置读取容量。

          • target_tracking_scaling_policy_configuration— 要定义目标跟踪策略，必须定义目标值。有关目标跟踪和冷却时间的更多信息，请参阅 App lication Auto Scaling 用户指南中的目标跟踪扩展策略。

            • target_value— 表格的目标利用率。Amazon Keyspaces 自动扩展可确保已用容量与预配置容量的比率保持在该值或接近该值。您将 target_value 定义为百分比。20 到 90 之间的双打。（必需）

            • scale_in_cooldown— 两次缩放活动之间的冷却时间（以秒为单位），可让表格在另一个缩放活动开始之前稳定下来。如果未提供任何值，则默认值为 0。（可选）

            • scale_out_cooldown— 两次扩展活动之间的冷却时间（以秒为单位），可让表格在另一个扩展活动开始之前稳定下来。如果未提供任何值，则默认值为 0。（可选）

            • disable_scale_in: Aboolean，它指定该表scale-in是禁用还是启用。默认情况下，此参数处于禁用状态。要开启scale-in，请将该boolean值设置为FALSE。这意味着代表您自动缩小餐桌的容量。（可选）

      • replica_updates：指定多区域表的 AWS 区域 特定自动缩放设置。对于多区域表，您可以根据不同的方式配置表的读取容量。 AWS 区域您可以通过配置以下参数来做到这一点。有关更多信息以及示例，请参阅 创建具有预置容量模式和 auto Scaling (CQL) 的多区域表。

        • region— 具有以下设置 AWS 区域 的表副本的：

          • provisioned_read_capacity_autoscaling_update

            • autoscaling_disabled— 要为表的读取容量启用 auto 缩放，请将该值设置为false。默认值为 true。（可选）

              注意

              必须为该表的所有副本启用或禁用多区域表的自动缩放。

            • minimum_units— 表应随时准备支持的最低读取吞吐量级别。该值必须介于 1 和您账户的最大每秒吞吐量配额（默认为 40,000）之间。

            • maximum_units— 表应随时准备支持的最大读取吞吐量级别。该值必须介于 1 和您账户的最大每秒吞吐量配额（默认为 40,000）之间。

            • scaling_policy— Amazon Keyspaces 支持目标跟踪政策。auto Scaling 目标是表的预配置读取容量。

              • target_tracking_scaling_policy_configuration— 要定义目标跟踪策略，必须定义目标值。有关目标跟踪和冷却时间的更多信息，请参阅 App lication Auto Scaling 用户指南中的目标跟踪扩展策略。

                • target_value— 表格的目标利用率。Amazon Keyspaces 自动扩展可确保已消耗的读取容量与预配置读取容量的比率保持在该值或接近该值。您将 target_value 定义为百分比。20 到 90 之间的双打。（必需）

                • scale_in_cooldown— 两次缩放活动之间的冷却时间（以秒为单位），可让表格在另一个缩放活动开始之前稳定下来。如果未提供任何值，则默认值为 0。（可选）

                • scale_out_cooldown— 两次扩展活动之间的冷却时间（以秒为单位），可让表格在另一个扩展活动开始之前稳定下来。如果未提供任何值，则默认值为 0。（可选）

                • disable_scale_in: Aboolean，它指定该表scale-in是禁用还是启用。默认情况下，此参数处于禁用状态。要开启scale-in，请将该boolean值设置为FALSE。这意味着代表您自动缩小表格的读取容量。（可选）

    • default_time_to_live：表的默认存活时间设置（以秒为单位）。

    • TAGS：创建资源时要附加到资源的键值对标签的列表。

  • clustering_order 包含以下各项：

    • column_name：列的名称。

    • ASC | DESC：设置升序 (ASC) 或降序 (DESC) 顺序修饰符。如果未指定，则默认顺序为 ASC。

示例

CREATE TABLE IF NOT EXISTS "my_keyspace".my_table (
                                            id text,
                                            name text,
                                            region text,
                                            division text,
                                            project text,
                                            role text,
                                            pay_scale int,
                                            vacation_hrs float,
                                            manager_id text,
                                            PRIMARY KEY (id,division))
                                            WITH CUSTOM_PROPERTIES={
                                                'capacity_mode':{
                                                        'throughput_mode': 'PROVISIONED', 'read_capacity_units': 10, 'write_capacity_units': 20
                                                    },
                                                'point_in_time_recovery':{'status': 'enabled'},
                                                'encryption_specification':{
                                                        'encryption_type': 'CUSTOMER_MANAGED_KMS_KEY', 
                                                        'kms_key_identifier':'arn:aws:kms:eu-west-1:5555555555555:key/11111111-1111-111-1111-111111111111'
                                                    }
                                            }
                                            AND CLUSTERING ORDER BY (division ASC) 
                                            AND TAGS={'key1':'val1', 'key2':'val2'}
                                            AND default_time_to_live = 3024000;

在使用聚类列的表中，可以在表定义中将非聚类列声明为静态列。有关静态列的更多信息，请参阅 Amazon Keyspaces 中的静态列。

示例

CREATE TABLE "my_keyspace".my_table (
                                            id int,
                                            name text,
                                            region text,
                                            division text,
                                            project text STATIC,
                                            PRIMARY KEY (id,division));

ALTER TABLE

使用 ALTER TABLE 语句可添加新列、添加标签或更改表的自定义属性。

语法

alter_table_statement ::=  ALTER TABLE table_name    
 
        [ ADD ( column_definition | column_definition_list)  ] 
        [[ADD | DROP] TAGS {'key1':'val1', 'key2':'val2'}]            
        [ WITH table_options [ , ... ] ] ;
        
column_definition      ::=  column_name cql_type

其中：

  • table_name 是要更改的表的名称。

  • column_definition 是要添加的列和数据类型的名称。

  • column_definition_list 是放在括号内的列的逗号分隔列表。

  • table_options 包含以下各项：

    • CUSTOM_PROPERTIES：特定于 Amazon Keyspaces 的设置的映射。

      • capacity_mode：指定表的读/写吞吐容量模式。选项为 throughput_mode:PAY_PER_REQUEST 和 throughput_mode:PROVISIONED。预置容量模式要求将 read_capacity_units 和 write_capacity_units 作为输入。默认值为 throughput_mode:PAY_PER_REQUEST。

      • client_side_timestamps：指定为表启用还是禁用客户端时间戳。选项为 {'status': 'enabled'} 和 {'status': 'disabled'}。如果未指定，则默认为 status:disabled。为表启用客户端时间戳后便无法禁用该设置。

      • encryption_specification：为静态加密指定加密选项。选项为 encryption_type:AWS_OWNED_KMS_KEY 和 encryption_type:CUSTOMER_MANAGED_KMS_KEY。加密选项客户自主管理型密钥要求输入 Amazon 资源名称 (ARN) 格式的 AWS KMS 密钥作为输入：kms_key_identifier:ARN。

      • point_in_time_recovery：指定是启用还是禁用表的 point-in-time 还原。选项为 status:enabled 和 status:disabled。默认值为 status:disabled。

      • replica_updates：指定多区域表的 AWS 区域 特定设置。对于多区域表，您可以根据不同的方式配置表的读取容量。 AWS 区域您可以通过配置以下参数来做到这一点。有关更多信息以及示例，请参阅 更新多区域表 (CQL) 的预配置容量和 auto scaling 设置。

        • region— 具有以下设置 AWS 区域 的表副本的：

          • read_capacity_units

      • ttl：为表启用存活时间自定义设置。要启用，请使用 status:enabled。默认值为 status:disabled。为表启用 ttl 后便无法禁用该设置。

    • AUTOSCALING_SETTINGS包括已配置表的可选 auto Scaling 设置。有关语法和详细说明，请参见CREATE TABLE。有关示例，请参阅使用 CQL 在现有表上启用自动缩放。

  • default_time_to_live：表的默认存活时间设置（以秒为单位）。

  • TAGS 是要附加到资源的键/值对标签的列表。

注意

使用 ALTER TABLE 时，您只能更改单个自定义属性。您无法在同一语句中组合多个 ALTER TABLE 命令。

示例

以下语句展示如何将列添加到现有表。

ALTER TABLE mykeyspace.mytable ADD (ID int);

此语句展示如何将两个集合列添加到现有表：

  • 包含嵌套冻结集合的冻结集合列 col_frozen_list

  • 包含嵌套冻结集合的非冻结集合列 col_map

ALTER TABLE my_Table ADD(col_frozen_list FROZEN<LIST<FROZEN<SET<TEXT>>>>, col_map MAP<INT, FROZEN<SET<INT>>>);

要更改表的容量模式并指定读取和写入容量单位，可以使用以下语句。

ALTER TABLE mykeyspace.mytable WITH CUSTOM_PROPERTIES={'capacity_mode':{'throughput_mode': 'PROVISIONED', 'read_capacity_units': 10, 'write_capacity_units': 20}};

以下语句为表指定客户自主管理型 KMS 密钥。

ALTER TABLE mykeyspace.mytable WITH CUSTOM_PROPERTIES={     
              'encryption_specification':{ 
                      'encryption_type': 'CUSTOMER_MANAGED_KMS_KEY', 
                      'kms_key_identifier':'arn:aws:kms:eu-west-1:5555555555555:key/11111111-1111-111-1111-111111111111'     
                  } 
         };

要为表启用 point-in-time 还原，可以使用以下语句。

ALTER TABLE mykeyspace.mytable WITH CUSTOM_PROPERTIES={'point_in_time_recovery': {'status': 'enabled'}};

要为表设置默认存活时间值（以秒为单位），可以使用以下语句。

ALTER TABLE my_table WITH default_time_to_live = 2592000;

此语句为表启用自定义存活时间设置。

ALTER TABLE mytable WITH CUSTOM_PROPERTIES={'ttl':{'status': 'enabled'}};

RESTORE TABLE

使用 RESTORE TABLE 语句可将表恢复到某个时间点。此语句要求在表上启用 point-in-time 恢复。有关更多信息，请参阅 Amazon Keyspaces（Apache Cassandra 兼容）的时间点故障恢复。

语法

restore_table_statement ::=  
    RESTORE TABLE restored_table_name FROM TABLE source_table_name 
                    [ WITH table_options [ , ... ] ];

其中：

  • restored_table_name 是已恢复的表的名称。

  • source_table_name 是源表的名称。

  • table_options 包含以下各项：

    • restore_timestamp 是 ISO 8601 格式的恢复点时间。如果未指定，则使用当前时间戳。

    • CUSTOM_PROPERTIES：特定于 Amazon Keyspaces 的设置的映射。

      • capacity_mode：指定表的读/写吞吐容量模式。选项为 throughput_mode:PAY_PER_REQUEST 和 throughput_mode:PROVISIONED。预置容量模式要求将 read_capacity_units 和 write_capacity_units 作为输入。默认值为源表中的当前设置。

      • encryption_specification：为静态加密指定加密选项。选项为 encryption_type:AWS_OWNED_KMS_KEY 和 encryption_type:CUSTOMER_MANAGED_KMS_KEY。加密选项客户托管密钥要求输入亚马逊资源名称 (ARN) 格式的 AWS KMS 密钥作为输入：。kms_key_identifier:ARN要将使用客户托管密钥加密的表恢复到使用加密的表 AWS 拥有的密钥，Amazon Keyspaces 需要访问源表的 AWS KMS 密钥。

      • point_in_time_recovery：指定是启用还是禁用表的 point-in-time 还原。选项为 status:enabled 和 status:disabled。与创建新表时不同，已恢复的表的默认状态为 status:enabled，因为该设置继承自源表。要对已恢复的表禁用 PITR，必须显式设置 status:disabled。

      • replica_updates：指定多区域表的 AWS 区域 特定设置。对于多区域表，您可以根据不同的方式配置表的读取容量。 AWS 区域您可以通过配置以下参数来做到这一点。

        • region— 具有以下设置 AWS 区域 的表副本的：

          • read_capacity_units

    • AUTOSCALING_SETTINGS包括已配置表的可选 auto Scaling 设置。有关详细语法和说明，请参阅CREATE TABLE。

    • TAGS 是要附加到资源的键/值对标签的列表。

注意

已删除的表只能恢复到删除时的状态。

示例

RESTORE TABLE mykeyspace.mytable_restored from table mykeyspace.my_table 
WITH restore_timestamp = '2020-06-30T04:05:00+0000'
AND custom_properties = {'point_in_time_recovery':{'status':'disabled'}, 'capacity_mode':{'throughput_mode': 'PROVISIONED', 'read_capacity_units': 10, 'write_capacity_units': 20}}
AND TAGS={'key1':'val1', 'key2':'val2'};

DROP TABLE

使用 DROP TABLE 语句可从键空间中删除表。

语法

drop_table_statement ::=  
    DROP TABLE [ IF EXISTS ] table_name

其中：

  • IF EXISTS 防止 DROP TABLE 在表不存在的情况下失败。（可选）

  • table_name 是要删除的表的名称。

示例

DROP TABLE "myGSGKeyspace".employees_tbl;