Tabelas

As tabelas são as principais estruturas de dados no Amazon Keyspaces. Os dados em uma tabela são organizados em linhas e colunas. Um subconjunto dessas colunas é usado para determinar o particionamento (e, em última análise, o posicionamento dos dados) por meio da especificação de uma chave de partição.

Outro conjunto de colunas pode ser definido em colunas de cluster, o que significa que elas podem participar como predicados na execução da consulta.

Por padrão, novas tabelas são criadas com capacidade de throughput sob demanda. Você pode alterar o modo de capacidade de tabelas novas e existentes. Para obter mais informações sobre os modos de throughput da capacidade de leitura/gravação, consulte Configurar modos de capacidade de leitura/gravação no Amazon Keyspaces.

Para tabelas no modo provisionado, você pode configurar AUTOSCALING_SETTINGS opcionais. Para obter mais informações sobre o ajuste de escala automático do Amazon Keyspaces e as opções disponíveis, consulte Configurar o ajuste de escala automático em uma tabela existente.

Para informações sobre limites e restrições de cotas para tabelas do Amazon Keyspaces, consulte Cotas para Amazon Keyspaces (para Apache Cassandra).

CRIAR TABELA

Use a instrução do CREATE TABLE para criar uma nova tabela.

Sintaxe

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) )*

Em que:

• table_name é o nome da tabela a ser criada. O nome totalmente qualificado inclui o prefixo keyspace. Como alternativa, você pode definir o espaço de teclas atual com a instrução USE keyspace.

• column_definition consiste no seguinte:

  • column_name: o nome da coluna.

  • cql_type: um tipo de dados do Amazon Keyspaces (consulteTipos de dados).

  • FROZEN— Designa essa coluna definida pelo usuário ou do tipo collection (por exemplo, LISTSET, ouMAP) como congelada. Uma coleção congelada é serializada em um único valor imutável e tratada como a BLOB. Para obter mais informações, consulte Tipos de coleção.

  • STATIC: designa essa coluna como estática. As colunas estáticas armazenam valores que são compartilhados por todas as linhas na mesma partição.

  • PRIMARY KEY: designa essa coluna como a chave primária da tabela.

• primary_key consiste no seguinte:

  • partition_key

  • clustering_columns

• partition_key:

  • A chave de partição pode ser uma única coluna ou um valor composto formado por duas ou mais colunas. A parte da chave de partição da chave primária é necessária e determina como o Amazon Keyspaces armazena seus dados.

• clustering_columns:

  • A parte opcional da coluna de cluster da sua chave primária determina como os dados são agrupados e classificados em cada partição.

• table_options consiste no seguinte:

  • CLUSTERING ORDER BY: a ORDEM DE CLUSTER padrão em uma tabela é composta por suas chaves de cluster na direção de classificação ASC (ascendente). Especifique-o para substituir o comportamento de classificação padrão.

  • CUSTOM_PROPERTIES: um mapa de configurações específicas do Amazon Keyspaces.

    • capacity_mode: especifica o modo de capacidade de throughput de leitura/gravação da tabela. As opções são throughput_mode:PAY_PER_REQUEST e throughput_mode:PROVISIONED. O modo de capacidade provisionada requer read_capacity_units e write_capacity_units como entradas. O padrão é throughput_mode:PAY_PER_REQUEST.

    • client_side_timestamps: especifica se os carimbos de data/hora do lado do cliente estão habilitados ou desabilitados para a tabela. As opções são {'status': 'enabled'} e {'status': 'disabled'}. Se não especificado, o padrão será status:disabled. Depois que os carimbos de data/hora do lado do cliente forem habilitados para uma tabela, essa configuração não poderá ser desativada.

    • encryption_specification: especifica as opções de criptografia para criptografia em repouso. Se não especificado, o padrão será encryption_type:AWS_OWNED_KMS_KEY. A opção de criptografia chave gerenciada pelo cliente exige a AWS KMS chave no formato Amazon Resource Name (ARN) como entrada::kms_key_identifier:ARN. kms_key_identifier:ARN

    • point_in_time_recovery: especifica se a point-in-time restauração está ativada ou desativada para a tabela. As opções são status:enabled e status:disabled. Se não especificado, o padrão será status:disabled.

    • replica_updates: especifica as configurações de uma tabela multirregional que são específicas de uma Região da AWS. Para uma tabela multirregional, você pode configurar a capacidade de leitura da tabela de forma diferente por Região da AWS. Para isso, você pode fazer isso configurando os parâmetros a seguir. Para ter mais informações e exemplos, consulte Criar uma tabela multirregional no modo provisionado com ajuste de escala automático no Amazon Keyspaces.

      • region— A réplica Região da AWS da tabela com as seguintes configurações:

        • read_capacity_units

    • TTL: habilita as configurações personalizadas de tempo de vida para a tabela. Para habilitá-la, use status:enabled. O padrão é status:disabled. Depois de habilitado o TTL, você não poderá desabilitá-lo para a tabela.

  • AUTOSCALING_SETTINGS inclui as seguintes configurações opcionais para tabelas no modo provisionado. Para ter mais informações e exemplos, consulte Crie uma nova tabela com dimensionamento automático.

    • provisioned_write_capacity_autoscaling_update:

      • autoscaling_disabled: para ativar o ajuste de escala automático para capacidade de gravação, defina o valor como false. O padrão é true. (Opcional)

      • minimum_units: o nível mínimo de throughput de gravação para o qual a tabela deve estar sempre pronta para dar suporte. O valor deve estar entre 1 e a cota máxima de throughput por segundo da sua conta (40.000 por padrão).

      • maximum_units: o nível máximo de throughput de gravação para o qual a tabela deve estar sempre pronta para dar suporte. O valor deve estar entre 1 e a cota máxima de throughput por segundo da sua conta (40.000 por padrão).

      • scaling_policy: o Amazon Keyspaces oferece suporte à política de rastreamento de alvos. A meta do ajuste de escala automático é a capacidade de gravação provisionada da tabela.

        • target_tracking_scaling_policy_configuration: para definir a política de rastreamento de metas, você deve definir o valor alvo. Para obter mais informações sobre rastreamento de destino e período de espera, consulte Target Tracking Scaling Policies no Guia do usuário do Application Auto Scaling.

          • target_value: a taxa de utilização alvo da tabela. O ajuste de escala automático do Amazon Keyspaces garante que o índice de capacidade consumida para capacidade provisionada permaneça nesse valor ou próximo a ele. Você define target_value como uma porcentagem. Um duplo entre 20 e 90. (Obrigatória)

          • scale_in_cooldown: um período de espera em segundos entre as atividades de ajuste de escala permite que a tabela se estabilize antes que outra atividade de reduzir a escala horizontalmente comece. Se nenhum valor for fornecido, o valor padrão será 0. (Opcional)

          • scale_out_cooldown: um período de espera em segundos entre as atividades de ajuste de escala permite que a tabela se estabilize antes que outra atividade de aumentar a escala horizontalmente comece. Se nenhum valor for fornecido, o valor padrão será 0. (Opcional)

          • disable_scale_in: um boolean que especifica se scale-in está desativado ou ativado para a tabela. Por padrão, esse parâmetro é desabilitado. Para ativar scale-in, defina o valor de boolean como FALSE. Isso significa que a capacidade é reduzida automaticamente para uma tabela em seu nome. (Opcional)

    • provisioned_read_capacity_autoscaling_update:

      • autoscaling_disabled: para ativar o ajuste de escala automático da capacidade de leitura, defina o valor como false. O padrão é true. (Opcional)

      • minimum_units: o nível mínimo de throughput que a tabela deve estar sempre pronta para suportar. O valor deve estar entre 1 e a cota máxima de throughput por segundo da sua conta (40.000 por padrão).

      • maximum_units: o nível máximo de throughput para o qual a tabela deve estar sempre pronta para dar suporte. O valor deve estar entre 1 e a cota máxima de throughput por segundo da sua conta (40.000 por padrão).

      • scaling_policy: o Amazon Keyspaces oferece suporte à política de rastreamento de alvos. A meta do ajuste de escala automático é a capacidade de leitura provisionada da tabela.

        • target_tracking_scaling_policy_configuration: para definir a política de rastreamento de metas, você deve definir o valor alvo. Para obter mais informações sobre rastreamento de destino e período de espera, consulte Target Tracking Scaling Policies no Guia do usuário do Application Auto Scaling.

          • target_value: a taxa de utilização alvo da tabela. O ajuste de escala automático do Amazon Keyspaces garante que o índice de capacidade consumida para capacidade provisionada permaneça nesse valor ou próximo a ele. Você define target_value como uma porcentagem. Um duplo entre 20 e 90. (Obrigatória)

          • scale_in_cooldown: um período de espera em segundos entre as atividades de ajuste de escala permite que a tabela se estabilize antes que outra atividade de reduzir a escala horizontalmente comece. Se nenhum valor for fornecido, o valor padrão será 0. (Opcional)

          • scale_out_cooldown: um período de espera em segundos entre as atividades de ajuste de escala permite que a tabela se estabilize antes que outra atividade de aumentar a escala horizontalmente comece. Se nenhum valor for fornecido, o valor padrão será 0. (Opcional)

          • disable_scale_in: um boolean que especifica se scale-in está desativado ou ativado para a tabela. Por padrão, esse parâmetro é desabilitado. Para ativar scale-in, defina o valor de boolean como FALSE. Isso significa que a capacidade é reduzida automaticamente para uma tabela em seu nome. (Opcional)

    • replica_updates: especifica as configurações Região da AWS específicas de escalonamento automático de uma tabela multirregional. Para uma tabela multirregional, você pode configurar a capacidade de leitura da tabela de forma diferente por Região da AWS. Para isso, você pode fazer isso configurando os parâmetros a seguir. Para ter mais informações e exemplos, consulte Atualize a capacidade provisionada e as configurações de ajuste de escala automático para uma tabela multirregional no Amazon Keyspaces.

      • region— A réplica Região da AWS da tabela com as seguintes configurações:

        • provisioned_read_capacity_autoscaling_update

          • autoscaling_disabled: para ativar o ajuste de escala automático para a capacidade de leitura da tabela, defina o valor como false. O padrão é true. (Opcional)

            nota

            O ajuste de escala automático de uma tabela multirregional precisa estar ativado ou desativado para todas as réplicas da tabela.

          • minimum_units: o nível mínimo de throughput de leitura para o qual a tabela deve estar sempre pronta para dar suporte. O valor deve estar entre 1 e a cota máxima de throughput por segundo da sua conta (40.000 por padrão).

          • maximum_units: o nível máximo de throughput de leitura para o qual a tabela deve estar sempre pronta para dar suporte. O valor deve estar entre 1 e a cota máxima de throughput por segundo da sua conta (40.000 por padrão).

          • scaling_policy: o Amazon Keyspaces oferece suporte à política de rastreamento de alvos. A meta do ajuste de escala automático é a capacidade de leitura provisionada da tabela.

            • target_tracking_scaling_policy_configuration: para definir a política de rastreamento de metas, você deve definir o valor alvo. Para obter mais informações sobre rastreamento de destino e período de espera, consulte Target Tracking Scaling Policies no Guia do usuário do Application Auto Scaling.

              • target_value: a taxa de utilização alvo da tabela. O ajuste de escala automático do Amazon Keyspaces garante que o índice de capacidade de leitura consumida para capacidade provisionada de leitura permaneça nesse valor ou próximo a ele. Você define target_value como uma porcentagem. Um duplo entre 20 e 90. (Obrigatória)

              • scale_in_cooldown: um período de espera em segundos entre as atividades de ajuste de escala permite que a tabela se estabilize antes que outra atividade de reduzir a escala horizontalmente comece. Se nenhum valor for fornecido, o valor padrão será 0. (Opcional)

              • scale_out_cooldown: um período de espera em segundos entre as atividades de ajuste de escala permite que a tabela se estabilize antes que outra atividade de aumentar a escala horizontalmente comece. Se nenhum valor for fornecido, o valor padrão será 0. (Opcional)

              • disable_scale_in: um boolean que especifica se scale-in está desativado ou ativado para a tabela. Por padrão, esse parâmetro é desabilitado. Para ativar scale-in, defina o valor de boolean como FALSE. Isso significa que a capacidade de leitura é reduzida automaticamente para uma tabela em seu nome. (Opcional)

  • default_time_to_live: a configuração padrão de tempo de vida em segundos para a tabela.

  • TAGS: uma lista de tags de pares de chave-valor a serem anexadas ao recurso ao ser criado.

• clustering_order consiste no seguinte:

  • column_name: o nome da coluna.

  • ASC | DESC: define o modificador de ordem ascendente (ASC) ou descendente (DESC). Se não especificado, o pedido padrão será ASC.

Exemplo

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;

Em uma tabela que usa colunas de cluster, as colunas sem cluster podem ser declaradas como estáticas na definição da tabela. Para obter mais informações sobre as colunas estáticas, consulte Estimar o consumo de capacidade para colunas estáticas no Amazon Keyspaces.

Exemplo

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

Você pode criar uma tabela com uma coluna que usa um tipo definido pelo usuário (UDT). A primeira instrução nos exemplos cria um tipo, a segunda instrução cria uma tabela com uma coluna que usa o tipo.

Exemplo

CREATE TYPE my_keyspace."udt""N@ME" (my_field int);
CREATE TABLE my_keyspace.my_table (my_col1 int pri key, my_col2 "udt""N@ME");

ALTER TABLE

Use a instrução ALTER TABLE para adicionar novas colunas, adicionar tags ou alterar as propriedades personalizadas da tabela.

Sintaxe

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
                    
                

Em que:

• table_name é o nome da tabela a ser alterada.

• column_definition é o nome da coluna e do tipo de dado a ser adicionado.

• column_definition_list é uma lista de colunas separadas por vírgulas colocadas entre parênteses.

• table_options consiste no seguinte:

  • CUSTOM_PROPERTIES: um mapa de configurações específicas para o Amazon Keyspaces.

    • capacity_mode: especifica o modo de capacidade de throughput de leitura/gravação da tabela. As opções são throughput_mode:PAY_PER_REQUEST e throughput_mode:PROVISIONED. O modo de capacidade provisionada requer read_capacity_units e write_capacity_units como entradas. O padrão é throughput_mode:PAY_PER_REQUEST.

    • client_side_timestamps: especifica se os carimbos de data/hora do lado do cliente estão habilitados ou desabilitados para a tabela. As opções são {'status': 'enabled'} e {'status': 'disabled'}. Se não especificado, o padrão será status:disabled. Depois que os carimbos de data/hora do lado do cliente forem habilitados para uma tabela, essa configuração não poderá ser desativada.

    • encryption_specification: especifica a opção de criptografia para criptografia em repouso. As opções são encryption_type:AWS_OWNED_KMS_KEY e encryption_type:CUSTOMER_MANAGED_KMS_KEY. A opção de criptografia de chave gerenciada pelo cliente exige a chave AWS KMS no formato Nome do Recurso da Amazon (ARN) como entrada: kms_key_identifier:ARN.

    • point_in_time_recovery: especifica se a point-in-time restauração está ativada ou desativada para a tabela. As opções são status:enabled e status:disabled. O padrão é status:disabled.

    • replica_updates: especifica as configurações Região da AWS específicas de uma tabela multirregional. Para uma tabela multirregional, você pode configurar a capacidade de leitura da tabela de forma diferente por Região da AWS. Para isso, você pode fazer isso configurando os parâmetros a seguir. Para ter mais informações e exemplos, consulte Atualize a capacidade provisionada e as configurações de ajuste de escala automático para uma tabela multirregional no Amazon Keyspaces.

      • region— A réplica Região da AWS da tabela com as seguintes configurações:

        • read_capacity_units

    • ttl: habilita as configurações personalizadas de tempo de vida para a tabela. Para habilitá-la, use status:enabled. O padrão é status:disabled. Depois de habilitado o ttl, você não poderá desabilitá-lo para a tabela.

  • AUTOSCALING_SETTINGS inclui as configurações opcionais de ajuste de escala automático para tabelas provisionadas. Para obter descrições detalhadas e de sintaxe, consulte CRIAR TABELA. Para obter exemplos, consulte Configurar o ajuste de escala automático em uma tabela existente.

• default_time_to_live: A configuração padrão de tempo de vida em segundos para a tabela.

• TAGS é uma lista de tags de pares de chave-valor a serem anexadas ao recurso.

nota

Com ALTER TABLE, é possível alterar somente uma propriedade personalizada. Você não pode combinar mais de um comando ALTER TABLE na mesma instrução.

Exemplos

A instrução a seguir mostra como adicionar uma coluna a uma tabela existente.

ALTER TABLE mykeyspace.mytable ADD (ID int);

Essa instrução mostra como adicionar duas colunas de coleção a uma tabela existente:

• Uma coluna de coleção congelada col_frozen_list que contém uma coleção congelada aninhada

• Uma coluna de coleção não congelada col_map que contém uma coleção congelada aninhada

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

O exemplo a seguir mostra como adicionar uma coluna que usa um tipo definido pelo usuário (UDT) a uma tabela.

ALTER TABLE my_keyspace.my_table ADD (my_column, my_udt;);

Para alterar o modo de capacidade de uma tabela e especificar unidades de capacidade de leitura e gravação, você pode usar a seguinte declaração.

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

A declaração a seguir especifica uma chave KMS gerenciada pelo cliente para a tabela.

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'     
                  } 
         };

Para ativar a point-in-time restauração de uma tabela, você pode usar a instrução a seguir.

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

Para definir um valor padrão de tempo de vida em segundos para uma tabela, você pode usar a seguinte declaração.

ALTER TABLE my_table WITH default_time_to_live = 2592000;

Essa instrução habilita configurações personalizadas de tempo de vida para uma tabela.

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

RESTAURAR TABELA

Use a instrução do RESTORE TABLE ou restaure uma tabela para um ponto no tempo. Essa declaração exige que a point-in-time recuperação seja ativada em uma tabela. Para obter mais informações, consulte Faça backup e restaure dados com point-in-time recuperação para Amazon Keyspaces.

Sintaxe

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

Em que:

• restored_table_name é o nome da tabela restaurada.

• source_table_name é o nome da tabela de origem.

• table_options consiste no seguinte:

  • restore_timestamp é a hora do ponto de restauração no formato ISO 8601. Se não for especificado, o carimbo de data/hora atual será usado.

  • CUSTOM_PROPERTIES: um mapa de configurações específicas para o Amazon Keyspaces.

    • capacity_mode: especifica o modo de capacidade de throughput de leitura/gravação da tabela. As opções são throughput_mode:PAY_PER_REQUEST e throughput_mode:PROVISIONED. O modo de capacidade provisionada requer read_capacity_units e write_capacity_units como entradas. O padrão é a configuração atual da tabela de origem.

    • encryption_specification: especifica a opção de criptografia para criptografia em repouso. As opções são encryption_type:AWS_OWNED_KMS_KEY e encryption_type:CUSTOMER_MANAGED_KMS_KEY. A opção de criptografia chave gerenciada pelo cliente exige a AWS KMS chave no formato Amazon Resource Name (ARN) como entrada:. kms_key_identifier:ARN Para restaurar uma tabela criptografada com uma chave gerenciada pelo cliente para uma tabela criptografada com uma Chave pertencente à AWS, o Amazon Keyspaces requer acesso à AWS KMS chave da tabela de origem.

    • point_in_time_recovery: especifica se a point-in-time restauração está ativada ou desativada para a tabela. As opções são status:enabled e status:disabled. Diferentemente de quando você cria novas tabelas, o status padrão das tabelas restauradas é status:enabled porque a configuração é herdada da tabela de origem. Para desativar o PITR para tabelas restauradas, você deve definir status:disabled explicitamente.

    • replica_updates: especifica as configurações Região da AWS específicas de uma tabela multirregional. Para uma tabela multirregional, você pode configurar a capacidade de leitura da tabela de forma diferente por Região da AWS. Para isso, você pode fazer isso configurando os parâmetros a seguir.

      • region— A réplica Região da AWS da tabela com as seguintes configurações:

        • read_capacity_units

  • AUTOSCALING_SETTINGS inclui as configurações opcionais de ajuste de escala automático para tabelas provisionadas. Para obter descrições detalhadas e de sintaxe, consulte CRIAR TABELA.

  • TAGS é uma lista de tags de pares de chave-valor a serem anexadas ao recurso.

nota

As tabelas excluídas só podem ser restauradas até o momento da exclusão.

Exemplo

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'};

DESCARTAR TABELA

Use a instrução DROP TABLE para remover uma tabela do espaço de chaves.

Sintaxe

drop_table_statement ::=  
    DROP TABLE [ IF EXISTS ] table_name

Em que:

• IF EXISTS evita que DROP TABLE falhe se a tabela não existir. (Opcional)

• table_name é o nome do banco de dados a ser descartado.

Exemplo

DROP TABLE my_keyspace.my_table;