As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Referência de idiomas CQL para Amazon Keyspaces (para Apache Cassandra) Depois de se conectar a um endpoint do Amazon Keyspaces, você usa o Cassandra Query Language (CQL) para trabalhar com seu banco de dados. O CQL é semelhante em muitos aspectos ao Structured Query Language (SQL). + **Elementos do CQL**: esta seção abrange os elementos fundamentais do CQL com suporte no Amazon Keyspaces, incluindo identificadores, constantes, termos e tipos de dados. Ele explica conceitos como tipos de sequências de caracteres, tipos numéricos, tipos de coleção e muito mais. + **Data Definition Language (DDL)**: as instruções DDL são usadas para gerenciar estruturas de dados como keyspaces e tabelas no Amazon Keyspaces. Esta seção aborda instruções para criar, alterar e eliminar tabelas e espaços de chave, bem como restaurar tabelas a partir de um backup. point-in-time + **Linguagem de manipulação de dados (DML)**: as instruções DML são usadas para gerenciar dados em tabelas. Esta seção abrange instruções para selecionar, inserir, atualizar e excluir dados. Também explica os recursos avançados de consulta, como o uso do operador do `IN`, os resultados do pedido e a paginação. + **Funções integradas**: o Amazon Keyspaces oferece suporte a uma variedade de funções escalares integradas que você pode usar nas instruções do CQL. Esta seção fornece uma visão geral dessas funções, incluindo exemplos de seu uso. Ao longo deste tópico, você encontrará sintaxe detalhada, exemplos e melhores práticas para usar o CQL de forma eficaz no Amazon Keyspaces. **Topics** + [Elementos do Cassandra Query Language (CQL) no Amazon Keyspaces](cql.elements.md) + [Instruções DDL (linguagem de definição de dados) no Amazon Keyspaces](cql.ddl.md) + [Declarações DML (linguagem de manipulação de dados) no Amazon Keyspaces](cql.dml.md) + [Funções integradas no Amazon Keyspaces](cql.functions.md) # Elementos do Cassandra Query Language (CQL) no Amazon Keyspaces Saiba mais sobre os elementos do Cassandra Query Language (CQL) que são compatíveis com o Amazon Keyspaces, incluindo identificadores, constantes, termos e tipos de dados. **Topics** + [identifier](#cql.elements.identifier) + [constants](#cql.elements.constants) + [term](#cql.elements.term) + [Tipos de dados](#cql.data-types) + [Codificação JSON dos tipos de dados do Amazon Keyspaces](#cql.data-types.JSON) ## Identificadores Identificadores (ou nomes) são usados para identificar tabelas, colunas e outros objetos. Um identificador pode ser citado ou não. O seguinte se aplica. ``` identifier ::= unquoted_identifier | quoted_identifier unquoted_identifier ::= re('[a-zA-Z][a-zA-Z0-9_]*') quoted_identifier ::= '"' (any character where " can appear if doubled)+ '"' ``` ## Constantes As seguintes constantes são definidas. ``` constant ::= string | integer | float | boolean | uuid | blob | NULL string ::= '\'' (any character where ' can appear if doubled)+ '\'' '$$' (any character other than '$$') '$$' integer ::= re('-?[0-9]+') float ::= re('-?[0-9]+(\.[0-9]*)?([eE][+-]?[0-9+])?') | NAN | INFINITY boolean ::= TRUE | FALSE uuid ::= hex{8}-hex{4}-hex{4}-hex{4}-hex{12} hex ::= re("[0-9a-fA-F]") blob ::= '0' ('x' | 'X') hex+ ``` ## Termos Um termo denota o tipo de valores que são compatíveis. Os termos são definidos pelo seguinte. ``` term ::= constant | literal | function_call | arithmetic_operation | type_hint | bind_marker literal ::= collection_literal | tuple_literal function_call ::= identifier '(' [ term (',' term)* ] ')' arithmetic_operation ::= '-' term | term ('+' | '-' | '*' | '/' | '%') term ``` ## Tipos de dados O Amazon Keyspaces é compatível com os seguintes tipos de dados: ### Tipos de string **** | Tipo de dados | Description | | --- | --- | | `ascii` | Representa uma cadeia de caracteres ASCII. | | `text` | Representa uma cadeia de caracteres codificada UTF-8. | | `varchar` | Representa uma string codificada em UTF-8 (`varchar` é um alias para `text`). | ### Tipos numéricos **** | Tipo de dados | Description | | --- | --- | | `bigint` | Representa um comprimento assinado de 64 bits. | | `counter` | Representa um contador de números inteiros assinado de 64 bits. Para obter mais informações, consulte [Contadores](#cql.data-types.numeric.counters). | | `decimal` | Representa um decimal de precisão variável. | | `double` | Representa um ponto flutuante IEEE 754 de 64 bits. | | `float` | Representa um ponto flutuante IEEE 754 de 32 bits. | | `int` | Representa um int assinado de 32 bits. | | `varint` | Representa um valor inteiro dentro do intervalo \$1/- 10^38. | #### Contadores Uma `counter` coluna contém um número inteiro assinado de 64 bits. O valor do contador é incrementado ou diminuído usando a instrução [UPDATE](cql.dml.update.md) e não pode ser definido diretamente. Isso torna as colunas `counter` úteis para rastrear contagens. Por exemplo, você pode usar contadores para rastrear o número de entradas em um arquivo de log ou o número de vezes que uma publicação foi visualizada em uma rede social. As restrições a seguir se aplicam às colunas `counter`: + Uma coluna do tipo `counter` não pode fazer parte do `primary key` de uma tabela. + Em uma tabela que contém uma ou mais colunas do tipo `counter`, todas as colunas dessa tabela devem ser do tipo `counter`. Nos casos em que uma atualização do contador falha (por exemplo, devido ao tempo limite ou à perda de conexão com o Amazon Keyspaces), o cliente não sabe se o valor do contador foi atualizado. Se a atualização for repetida, a atualização do valor do contador poderá ser aplicada pela segunda vez. ### Tipo Blob **** | Tipo de dados | Description | | --- | --- | | `blob` | Representa bytes arbitrários. | ### Tipo booliano **** | Tipo de dados | Description | | --- | --- | | `boolean` | Representa true ou false. | ### Tipos relacionados ao tempo **** | Tipo de dados | Description | | --- | --- | | `date` | Uma string no formato--
. | | `timestamp` | Número inteiro assinado de 64 bits representando a data e a hora desde a época (1º de janeiro de 1970 às 00:00:00 GMT) em milissegundos. | | `timeuuid` | Representa um [UUID da versão 1](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_1_(date-time_and_MAC_address)). | ### Tipos de coleção **** | Tipo de dados | Description | | --- | --- | | `list` | Representa uma coleção ordenada de elementos literais. | | `map` | Representa uma coleção não ordenada de pares de chave-valor. | | `set` | Representa uma coleção não ordenada de um ou mais elementos literais. | Você declara uma coluna de coleta usando o tipo de coleta seguido por outro tipo de dados (por exemplo, `TEXT` ou `INT`) entre parênteses angulares “<>”. Você pode criar uma coluna com um `SET` de `TEXT`, ou você pode criar um par de valor-chave `MAP` de `TEXT` e `INT`, conforme mostrado no exemplo a seguir. ``` SET MAP ``` Uma coleção *não congelada* permite que você faça atualizações em cada elemento individual da coleção. Os carimbos de data e hora do lado do cliente e as configurações de tempo de vida (TTL) são armazenados para elementos individuais. Quando você usa a palavra-chave `FROZEN` em um tipo de coleção, os valores da coleção são serializados em um único valor imutável, e o Amazon Keyspaces os trata como um `BLOB`. Esta é uma coleção *congelada*. Uma declaração `INSERT` ou `UPDATE` sobrescreve toda a coleção congelada. Você não pode fazer atualizações em elementos individuais dentro de uma coleção congelada. Os carimbos de data/hora do lado do cliente e as configurações de tempo de vida (TTL) se aplicam a toda a coleção congelada, não a elementos individuais. Colunas da coleção `Frozen` podem fazer parte de uma tabela de `PRIMARY KEY`. Você pode aninhar coleções congeladas. Por exemplo, você pode definir o `MAP` dentro de um `SET` se `MAP` estiver usando a palavra-chave `FROZEN`, conforme mostrado no exemplo a seguir. ``` SET >> ``` O Amazon Keyspaces suporta o agrupamento de até 8 níveis de coleções congeladas por padrão. Para obter mais informações, consulte [Service Quotas do Amazon Keyspaces](quotas.md#table). Para obter mais informações sobre diferenças funcionais com o Apache Cassandra, consulte [Coleções `FROZEN`](functional-differences.md#functional-differences.frozen-collections). Para obter mais informações sobre sintaxe de CQL, consulte [CRIAR TABELA](cql.ddl.table.md#cql.ddl.table.create) e [ALTER TABLE](cql.ddl.table.md#cql.ddl.table.alter). ### Tipo de tupla O tipo de dados `tuple` representa um grupo limitado de elementos literais. Você pode usar uma tupla como alternativa a `user defined type`. Você não precisa usar a palavra-chave `FROZEN` para tuplas. Isso ocorre porque uma tupla está sempre congelada e você não pode atualizar elementos individualmente. ### Outros tipos **** | Tipo de dados | Description | | --- | --- | | `inet` | Uma string representando um endereço IP, em um IPv4 ou no IPv6 formato. | ### Estático Em uma tabela do Amazon Keyspaces com colunas de clustering, você pode usar a palavra-chave `STATIC` para criar uma coluna estática de qualquer tipo. A instrução a seguir é um exemplo disso. ``` my_column INT STATIC ``` Para obter mais informações sobre trabalho com colunas estáticas, consulte [Estimar o consumo de capacidade para colunas estáticas no Amazon Keyspaces](static-columns.md). ### Tipos definidos pelo usuário () UDTs O Amazon Keyspaces oferece suporte a tipos definidos pelo usuário (). UDTs Você pode usar qualquer tipo de dados válido do Amazon Keyspaces para criar um UDT, incluindo coleções e outros existentes. UDTs Você cria UDTs em um espaço de chave e pode usá-las para definir colunas em qualquer tabela no espaço de chave. Para obter mais informações sobre sintaxe de CQL, consulte [Tipos definidos pelo usuário () UDTs](cql.ddl.type.md). Para obter mais informações sobre como trabalhar com UDTs, consulte[Tipos definidos pelo usuário (UDTs) no Amazon Keyspaces](udts.md). Para analisar quantos UDTs são suportados por espaço de chave, níveis de aninhamento suportados e outros valores e cotas padrão relacionados a UDTs, consulte. [Cotas e valores padrão para tipos definidos pelo usuário (UDTs) no Amazon Keyspaces](quotas.md#quotas-udts) ## Codificação JSON dos tipos de dados do Amazon Keyspaces O Amazon Keyspaces oferece os mesmos mapeamentos de tipos de dados JSON que o Apache Cassandra. A tabela a seguir descreve os tipos de dados que o Amazon Keyspaces aceita em declarações `INSERT JSON` e os tipos de dados que o Amazon Keyspaces usa ao retornar dados com a declaração `SELECT JSON`. Para tipos de dados de campo único como `float`, `int`, `UUID` e`date`, você também pode inserir dados como `string`. Para tipos de dados compostos e coleções, como`tuple`,`map` e`list`, você também pode inserir dados como JSON ou codificados`JSON string`. **** | Tipo de dados do JSON | Tipos de dados aceitos em declarações `INSERT JSON` | Tipos de dados retornados em declarações `SELECT JSON` | Observações | | --- | --- | --- | --- | | `ascii` | string | string | Usa `\u` escape de caracteres JSON. | | `bigint` | integer, string | integer | A string deve ser um número inteiro válido de 64 bits. | | `blob` | string | string | A string deve começar com `0x` seguida por um número par de dígitos hexadecimais. | | `boolean` | boolean, string | boolean | String deve ser `true` ou `false`. | | `date` | string | string | Data em formato`YYYY-MM-DD`, fuso horário UTC. | | `decimal` | integer, float, string | float | Pode exceder a precisão de ponto flutuante IEEE-754 de 32 bits ou 64 bits no decodificador do lado do cliente. | | `double` | integer, float, string | float | A string deve ser um número inteiro ou flutuante válido. | | `float` | integer, float, string | float | A string deve ser um número inteiro ou flutuante válido. | | `inet` | string | string | IPv4 ou IPv6 endereço. | | `int` | integer, string | integer | A string deve ser um número inteiro válido de 32 bits. | | `list` | list, string | list | Usa a representação nativa da lista JSON. | | `map` | map, string | map | Usa a representação nativa do mapa JSON. | | `smallint` | integer, string | integer | A string deve ser um número inteiro válido de 16 bits. | | `set` | list, string | list | Usa a representação nativa da lista JSON. | | `text` | string | string | Usa `\u` escape de caracteres JSON. | | `time` | string | string | Hora do dia em formato `HH-MM-SS[.fffffffff]`. | | `timestamp` | integer, string | string | Um carimbo de data/hora. As constantes de string permitem que você armazene carimbos de data/hora como datas. Os carimbos de data com formato `YYYY-MM-DD HH:MM:SS.SSS` são retornados. | | `timeuuid` | string | string | Tipo 1 UUID. Consulte [constants](#cql.elements.constants) para o formato UUID. | | `tinyint` | integer, string | integer | A string deve ser um número inteiro válido de 8 bits. | | `tuple` | list, string | list | Usa a representação nativa da lista JSON. | | `UDT` | map, string | map | Usa a representação do mapa JSON nativo com nomes de campo como chaves. | | `uuid` | string | string | Consulte [constants](#cql.elements.constants) para o formato UUID. | | `varchar` | string | string | Usa `\u` escape de caracteres JSON. | | `varint` | integer, string | integer | Comprimento variável; pode ultrapassar números inteiros de 32 bits ou 64 bits no decodificador do lado do cliente. | # Instruções DDL (linguagem de definição de dados) no Amazon Keyspaces A *linguagem de definição de dados* (DDL) é o conjunto de instruções do Cassandra Query Language (CQL) que você usa para gerenciar estruturas de dados no Amazon Keyspaces (para Apache Cassandra), como espaços de chaves e tabelas. Você usa o DDL para criar essas estruturas de dados, modificá-las depois de criadas e removê-las quando não estiverem mais em uso. O Amazon Keyspaces executa operações de DDL de forma assíncrona. Para obter mais informações sobre como confirmar se uma operação assíncrona foi concluída, consulte [Criação e exclusão assíncronas de espaços de chave e tabelas](functional-differences.md#functional-differences.table-keyspace-management). As seguintes instruções DLL são compatíveis: + [CRIAR ESPAÇO DE CHAVES](cql.ddl.keyspace.md#cql.ddl.keyspace.create) + [ALTERAR ESPAÇO DE CHAVES](cql.ddl.keyspace.md#cql.ddl.keyspace.alter) + [DESCARTAR ESPAÇO DE CHAVES](cql.ddl.keyspace.md#cql.ddl.keyspace.drop) + [USO](cql.ddl.keyspace.md#cql.ddl.keyspace.use) + [CRIAR TABELA](cql.ddl.table.md#cql.ddl.table.create) + [ALTER TABLE](cql.ddl.table.md#cql.ddl.table.alter) + [RESTAURAR TABELA](cql.ddl.table.md#cql.ddl.table.restore) + [DESCARTAR TABELA](cql.ddl.table.md#cql.ddl.table.drop) + [TIPO DE CRIAÇÃO](cql.ddl.type.md#cql.ddl.type.create) + [TIPO DE GOTA](cql.ddl.type.md#cql.ddl.type.drop) **Topics** + [Keyspaces](cql.ddl.keyspace.md) + [Tabelas](cql.ddl.table.md) + [Tipos definidos pelo usuário () UDTs](cql.ddl.type.md) # Keyspaces Um *espaço de chaves* agrupa tabelas relacionadas que são relevantes para um ou mais aplicativos. Em termos de um sistema de gerenciamento de banco de dados relacional (RDBMS), os espaços de chave são aproximadamente semelhantes aos bancos de dados, espaços de tabela ou construções similares. **nota** No Apache Cassandra, os espaços de chave determinam como os dados são replicados entre vários nós de armazenamento. No entanto, o Amazon Keyspaces é um serviço totalmente gerenciado: os detalhes de sua camada de armazenamento são gerenciados em seu nome. Por esse motivo, os espaços de chave no Amazon Keyspaces são apenas estruturas lógicas e não estão relacionados ao armazenamento físico subjacente. Para informações sobre limites e restrições de cota para os espaços de chaves do Amazon Keyspaces, consulte [Cotas para Amazon Keyspaces (para Apache Cassandra)](quotas.md). **Topics** + [CRIAR ESPAÇO DE CHAVES](#cql.ddl.keyspace.create) + [ALTERAR ESPAÇO DE CHAVES](#cql.ddl.keyspace.alter) + [DESCARTAR ESPAÇO DE CHAVES](#cql.ddl.keyspace.drop) + [USE](#cql.ddl.keyspace.use) ## CRIAR ESPAÇO DE CHAVES Use a instrução `CREATE KEYSPACE` para criar um novo espaço de chaves. **Sintaxe** ``` create_keyspace_statement ::= CREATE KEYSPACE [ IF NOT EXISTS ] keyspace_name WITH options ``` Em que: + `keyspace_name` é o nome do espaço de chaves a ser criado. + *opções* são uma ou mais das seguintes: + `REPLICATION`: um mapa que indica a estratégia de replicação para o espaço de chaves: + `SingleRegionStrategy`: para um espaço de chaves de região única. (Obrigatório) + `NetworkTopologyStrategy`— Especifique pelo menos dois Regiões da AWS. O fator de replicação para cada região é três. (Optional) + `DURABLE_WRITES`: as gravações no Amazon Keyspaces são sempre duráveis, portanto, essa opção não é necessária. No entanto, se especificado, o valor deve ser `true`. + `TAGS`: uma lista de tags de pares de chave-valor a serem anexadas ao recurso ao ser criado. (Optional) **Exemplo** Crie um espaço de chaves da seguinte forma. ``` CREATE KEYSPACE my_keyspace WITH REPLICATION = {'class': 'SingleRegionStrategy'} and TAGS ={'key1':'val1', 'key2':'val2'} ; ``` Para criar um espaço chave multirregional, especifique `NetworkTopologyStrategy` e inclua pelo menos dois. Regiões da AWS O fator de replicação para cada região é três. ``` CREATE KEYSPACE my_keyspace WITH REPLICATION = {'class':'NetworkTopologyStrategy', 'us-east-1':'3', 'ap-southeast-1':'3','eu-west-1':'3'}; ``` ## ALTERAR ESPAÇO DE CHAVES Você pode usar a `ALTER KEYSPACE WITH` declaração para as seguintes *opções*: + `REPLICATION`— Use essa opção para adicionar uma nova Região da AWS réplica a um keyspace. Você pode adicionar uma nova região a uma única região ou a um keyspace multirregional. + `TAGS`— Use essa opção para adicionar ou remover tags de um keyspace. **Sintaxe** ``` alter_keyspace_statement ::= ALTER KEYSPACE keyspace_name WITH options ``` Em que: + `keyspace_name` é o nome do espaço de chaves a ser alterado. + *as opções* são uma das seguintes: + `ADD | DROP TAGS`: uma lista de tags de pares chave-valor a serem adicionadas ou removidas do espaço de chaves. + `REPLICATION`— Um mapa que indica a estratégia de replicação para o keyspace; + `class`— `NetworkTopologyStrategy` define o keyspace como um keyspace multirregional. + `region`— Especifique um adicional Região da AWS para esse espaço de teclas. O fator de replicação para cada região é três. + `CLIENT_SIDE_TIMESTAMPS`— O padrão é`DISABLED`. Você só pode alterar o status para`ENABLED`. **Exemplos** Altere um espaço de teclas conforme mostrado no exemplo a seguir para adicionar tags. ``` ALTER KEYSPACE my_keyspace ADD TAGS {'key1':'val1', 'key2':'val2'}; ``` Para adicionar uma terceira região a um keyspace multirregional, você pode usar a seguinte declaração. ``` ALTER KEYSPACE my_keyspace WITH REPLICATION = { 'class': 'NetworkTopologyStrategy', 'us-east-1': '3', 'us-west-2': '3', 'us-west-1': '3' } AND CLIENT_SIDE_TIMESTAMPS = {'status': 'ENABLED'}; ``` ## DESCARTAR ESPAÇO DE CHAVES Use a instrução `DROP KEYSPACE` para remover um espaço de chaves, incluindo todo o seu conteúdo, como tabelas. **Sintaxe** ``` drop_keyspace_statement ::= DROP KEYSPACE [ IF EXISTS ] keyspace_name ``` Em que: + *keyspace\$1name é o nome* do espaço de chaves a ser eliminado. **Exemplo** ``` DROP KEYSPACE my_keyspace; ``` ## USE Use a `USE` instrução para definir o espaço de teclas atual. Isso permite que você faça referência a objetos vinculados a um espaço de chave específico, por exemplo, tabelas e tipos, sem usar o nome totalmente qualificado que inclui o prefixo do espaço de teclas. **Sintaxe** ``` use_statement ::= USE keyspace_name ``` Em que: + *keyspace\$1name é o nome* do keyspace a ser usado. **Exemplo** ``` USE my_keyspace; ``` # 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 read/write de taxa de transferência de capacidade, consulte[Configurar modos de read/write capacidade no Amazon Keyspaces](ReadWriteCapacityMode.md). 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](autoscaling.configureTable.md). Para informações sobre limites e restrições de cotas para tabelas do Amazon Keyspaces, consulte [Cotas para Amazon Keyspaces (para Apache Cassandra)](quotas.md). **Topics** + [CRIAR TABELA](#cql.ddl.table.create) + [ALTER TABLE](#cql.ddl.table.alter) + [RESTAURAR TABELA](#cql.ddl.table.restore) + [DESCARTAR TABELA](#cql.ddl.table.drop) ## 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 ] | cdc | 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 (consulte[Tipos de dados](cql.elements.md#cql.data-types)). + `FROZEN`— Designa essa coluna definida pelo usuário ou do tipo `collection` (por exemplo, `LIST``SET`, ou`MAP`) 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](cql.elements.md#cql.data-types.collection). + `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. + *`cdc`*— Um booleano que especifica se o Amazon Keyspaces cria um fluxo de captura de dados de alteração (CDC) para a tabela. O padrão é `false`. Para especificar o `view type` ao ativar um fluxo, defina `cdc_specification` com`CUSTOM_PROPERTIES`. + *`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`. + `cdc_specification`: especifica o fluxo `view_type` do CDC. As opções são: + `NEW_AND_OLD_IMAGES`— ambas as versões da linha, antes e depois da alteração. Esse é o padrão. + `NEW_IMAGE`— a versão da linha após a alteração. + `OLD_IMAGE`— a versão da linha antes da alteração. + `KEYS_ONLY`— as chaves de partição e agrupamento da linha que foi alterada. Para obter mais informações sobre fluxos CDC, consulte. [Trabalhando com fluxos de captura de dados de alteração (CDC) no Amazon Keyspaces](cdc.md) Para obter exemplos de código, consulte [Ative um stream do CDC ao criar uma nova tabela no Amazon Keyspaces](keyspaces-enable-cdc-new-table.md). + `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](tables-mrr-create-provisioned.md). + `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](autoscaling.createTable.md). + `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`. (Optional) + `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](https://docs.aws.amazon.com/autoscaling/application/userguide/application-auto-scaling-target-tracking.html) 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. (Optional) + `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. (Optional) + `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. (Optional) + `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`. (Optional) + `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](https://docs.aws.amazon.com/autoscaling/application/userguide/application-auto-scaling-target-tracking.html) 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. (Optional) + `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. (Optional) + `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. (Optional) + `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](tables-mrr-autoscaling.md). + `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`. (Optional) **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](https://docs.aws.amazon.com/autoscaling/application/userguide/application-auto-scaling-target-tracking.html) 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. (Optional) + `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. (Optional) + `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. (Optional) + `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](static-columns.md). **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: + `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](#cql.ddl.table.create). Para obter exemplos, consulte [Configurar o ajuste de escala automático em uma tabela existente](autoscaling.configureTable.md). + *`cdc`*— Um booleano que especifica se o Amazon Keyspaces cria um fluxo de captura de dados de alteração (CDC) para a tabela. O padrão é `false`. Para especificar o `view type` ao ativar um fluxo, defina `cdc_specification` com`CUSTOM_PROPERTIES`. + *`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`. + `cdc_specification`: especifica o fluxo `view_type` do CDC. As opções são: + `NEW_AND_OLD_IMAGES`— ambas as versões da linha, antes e depois da alteração. Esse é o padrão. + `NEW_IMAGE`— a versão da linha após a alteração. + `OLD_IMAGE`— a versão da linha antes da alteração. + `KEYS_ONLY`— as chaves de partição e agrupamento da linha que foi alterada. Para obter mais informações sobre fluxos CDC, consulte. [Trabalhando com fluxos de captura de dados de alteração (CDC) no Amazon Keyspaces](cdc.md) Para obter exemplos de código, consulte [Habilite um stream CDC para uma tabela existente no Amazon Keyspaces](keyspaces-enable-cdc-alter-table.md). + `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](tables-mrr-autoscaling.md). + `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. + `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>>>, col_map MAP>>); ``` 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](PointInTimeRecovery.md). **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](#cql.ddl.table.create). + `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. (Optional) + `table_name` é o nome do banco de dados a ser descartado. **Exemplo** ``` DROP TABLE my_keyspace.my_table; ``` # Tipos definidos pelo usuário () UDTs *UDT* — Um agrupamento de campos e tipos de dados que você pode usar para definir uma única coluna no Amazon Keyspaces. Todos os tipos de dados válidos do Cassandra UDTs são compatíveis com os tipos de dados do Cassandra, incluindo coleções e outros UDTs que você já criou no mesmo keyspace. Para obter mais informações sobre os tipos de dados do Cassandra compatíveis, consulte. [Suporte ao tipo de dados do Cassandra](cassandra-apis.md#cassandra-data-type) ``` user_defined_type::= udt_name udt_name::= [ keyspace_name '.' ] identifier ``` **Topics** + [CREATE TYPE](#cql.ddl.type.create) + [DROP TYPE](#cql.ddl.type.drop) ## CREATE TYPE Use a `CREATE TYPE` instrução para criar um novo tipo. **Sintaxe** ``` create_type_statement ::= CREATE TYPE [ IF NOT EXISTS ] udt_name '('field_definition ( ',' field_definition)* ')' field_definition::= identifier cql_type ``` Em que: + `IF NOT EXISTS``CREATE TYPE`evita que falhe se o tipo já existir. (Optional) + `udt_name`é o nome totalmente qualificado do UDT em formato de tipo, por exemplo. `my_keyspace.my_type` Se você definir o espaço de teclas atual com a `USE` instrução, não precisará especificar o nome do espaço de teclas. + `field_definition`consiste em um nome e um tipo. A tabela a seguir mostra exemplos de nomes de UDT permitidos. A primeira coluna mostra como inserir o nome ao criar o tipo, a segunda coluna mostra como o Amazon Keyspaces formata o nome internamente. O Amazon Keyspaces espera o nome formatado para operações como. `GetType` | Nome inserido | Nome formatado | Observação | | --- | --- | --- | | MY\$1UDT | my\$1udt | Sem aspas duplas, o Amazon Keyspaces converte todos os caracteres maiúsculos em minúsculas. | | "MY\$1UDT" | MY\$1UDT | Com aspas duplas, o Amazon Keyspaces respeita os caracteres maiúsculos e remove as aspas duplas do nome formatado. | | "1234" | 1234 | Com aspas duplas, o nome pode começar com um número, e o Amazon Keyspaces remove as aspas duplas do nome formatado. | | "Special\$1Ch@r@cters<>\$1\$1" | Special\$1Ch@r@cters<>\$1\$1 | Com aspas duplas, o nome pode conter caracteres especiais, e o Amazon Keyspaces remove as aspas duplas do nome formatado. | | "nested""""""quotes" | nested"""quotes | O Amazon Keyspaces remove as aspas duplas externas e as aspas duplas de escape do nome formatado. | **Exemplos** ``` CREATE TYPE my_keyspace.phone ( country_code int, number text ); ``` Você pode aninhar UDTs se o UDT aninhado estiver congelado. Para obter mais informações sobre valores padrão e cotas para tipos, consulte[Cotas de UDT e valores padrão do Amazon Keyspaces](quotas.md#udt-table). ``` CREATE TYPE my_keyspace.user ( first_name text, last_name text, phones FROZEN ); ``` Para obter mais exemplos de código que mostram como criar UDTs, consulte[Tipos definidos pelo usuário (UDTs) no Amazon Keyspaces](udts.md). ## DROP TYPE Use a `DROP TYPE` instrução para excluir um UDT. Você só pode excluir um tipo que não esteja sendo usado por outro tipo ou tabela. **Sintaxe** ``` drop_type_statement ::= DROP TYPE [ IF EXISTS ] udt_name ``` Em que: + `IF EXISTS``DROP TYPE`evita que falhe se o tipo não existir. (Optional) + `udt_name`é o nome totalmente qualificado do UDT em formato de tipo, por exemplo. `my_keyspace.my_type` Se você definir o espaço de teclas atual com a `USE` instrução, não precisará especificar o nome do espaço de teclas. **Exemplo** ``` DROP TYPE udt_name; ``` # Declarações DML (linguagem de manipulação de dados) no Amazon Keyspaces *Linguagem de manipulação de dados* (DML) é o conjunto de instruções Cassandra Query Language (CQL) que você usa para gerenciar dados em tabelas do Amazon Keyspaces (para Apache Cassandra). Você usa instruções DML para adicionar, modificar ou excluir dados em uma tabela. Você também usa instruções DML para consultar dados em uma tabela. (Observe que o CQL não oferece suporte a junções ou subconsultas.) **Topics** + [SELECT](cql.dml.select.md) + [INSERT](cql.dml.insert.md) + [UPDATE](cql.dml.update.md) + [DELETE](cql.dml.delete.md) # SELECT Use uma instrução SELECT para consultar dados. **Sintaxe** ``` select_statement ::= SELECT [ JSON ] ( select_clause | '*' ) FROM table_name [ WHERE 'where_clause' ] [ ORDER BY 'ordering_clause' ] [ LIMIT (integer | bind_marker) ] [ ALLOW FILTERING ] select_clause ::= selector [ AS identifier ] ( ',' selector [ AS identifier ] ) selector ::= column_name | term | CAST '(' selector AS cql_type ')' | function_name '(' [ selector ( ',' selector )* ] ')' where_clause ::= relation ( AND relation )* relation ::= column_name operator term TOKEN operator ::= '=' | '<' | '>' | '<=' | '>=' | IN | CONTAINS | CONTAINS KEY ordering_clause ::= column_name [ ASC | DESC ] ( ',' column_name [ ASC | DESC ] )* ``` **Exemplos** ``` SELECT name, id, manager_id FROM "myGSGKeyspace".employees_tbl ; SELECT JSON name, id, manager_id FROM "myGSGKeyspace".employees_tbl ; ``` Para obter uma tabela que mapeia os tipos de dados codificados em JSON para os tipos de dados do Amazon Keyspaces, consulte [Codificação JSON dos tipos de dados do Amazon Keyspaces](cql.elements.md#cql.data-types.JSON). **Usando a palavra-chave `IN`** A palavra-chave `IN` especifica igualdade para um ou mais valores. Ela pode ser aplicada à chave de partição e à coluna de cluster. Os resultados são retornados na ordem em que as chaves são apresentadas na declaração `SELECT`. **Exemplos** ``` SELECT * from mykeyspace.mytable WHERE primary.key1 IN (1,2) and clustering.key1 = 2; SELECT * from mykeyspace.mytable WHERE primary.key1 IN (1,2) and clustering.key1 <= 2; SELECT * from mykeyspace.mytable WHERE primary.key1 = 1 and clustering.key1 IN (1, 2); SELECT * from mykeyspace.mytable WHERE primary.key1 <= 2 and clustering.key1 IN (1, 2) ALLOW FILTERING; ``` Para obter mais informações sobre a palavra-chave `IN` e como o Amazon Keyspaces processa a declaração, consulte [Como usar o operador `IN` com a Instrução `SELECT` em uma consulta no Amazon Keyspaces](in.select.md). **Como ordenar resultados** A cláusula `ORDER BY` especifica a ordem de classificação dos resultados retornados. Ela usa como argumentos uma lista de nomes de colunas junto com a ordem de classificação de cada coluna. Você só pode especificar colunas de cluster nas cláusulas de ordenação. Colunas sem cluster não são permitidas. As opções de ordem de classificação são `ASC` para ordem de classificação crescente e `DESC` para decrescente. Se a ordem de classificação for omitida, a ordem padrão da coluna de cluster será usada. Para possíveis ordens de classificação, consulte [Ordenar resultados com `ORDER BY` no Amazon Keyspaces](ordering-results.md). **Exemplo** ``` SELECT name, id, division, manager_id FROM "myGSGKeyspace".employees_tbl WHERE id = '012-34-5678' ORDER BY division; ``` Ao usar `ORDER BY` com a palavra-chave `IN`, os resultados são ordenados em uma página. A reordenação completa com paginação desativada não é compatível. **TOKEN** Você pode aplicar a função `TOKEN` à coluna `PARTITION KEY` nas cláusulas `SELECT` e `WHERE`. Com a função `TOKEN`, o Amazon Keyspaces retorna linhas com base no valor do token mapeado do `PARTITION_KEY` e não no valor do `PARTITION KEY`. As relações `TOKEN` não são compatíveis com a palavra-chave `IN`. **Exemplos** ``` SELECT TOKEN(id) from my_table; SELECT TOKEN(id) from my_table WHERE TOKEN(id) > 100 and TOKEN(id) < 10000; ``` **Função TTL** Você pode usar a função `TTL` com a instrução `SELECT` para recuperar o tempo de expiração em segundos armazenado em uma coluna. Se nenhum valor de um conjunto for `TTL`, a função retorna `null`. **Exemplo** ``` SELECT TTL(my_column) from my_table; ``` A função `TTL` não pode ser usada em colunas com várias células, como coleções. **Função do WRITETIME** Você pode usar a função `WRITETIME` com a instrução `SELECT` para recuperar o carimbo de data/hora armazenado como metadados para o valor de uma coluna somente se a tabela usar carimbos de data e hora do lado do cliente. Para obter mais informações, consulte [Carimbos de data/hora do lado do cliente no Amazon Keyspaces](client-side-timestamps.md). ``` SELECT WRITETIME(my_column) from my_table; ``` A função `WRITETIME` não pode ser usada em colunas com várias células, como coleções. **nota** Para compatibilidade com o comportamento estabelecido do driver Cassandra, as políticas de autorização baseadas em tags não são aplicadas quando você executa operações em tabelas do sistema usando chamadas de API do Cassandra Query Language (CQL) por meio de drivers e ferramentas de desenvolvedor do Cassandra. Para obter mais informações, consulte [Acesso a recursos do Amazon Keyspaces com base em tags](security_iam_id-based-policy-examples.md#security_iam_id-based-policy-examples-tags). # INSERT Use a instrução `INSERT` para adicionar uma linha a uma tabela. **Sintaxe** ``` insert_statement ::= INSERT INTO table_name ( names_values | json_clause ) [ IF NOT EXISTS ] [ USING update_parameter ( AND update_parameter )* ] names_values ::= names VALUES tuple_literal json_clause ::= JSON string [ DEFAULT ( NULL | UNSET ) ] names ::= '(' column_name ( ',' column_name )* ')' ``` **Exemplo** ``` INSERT INTO "myGSGKeyspace".employees_tbl (id, name, project, region, division, role, pay_scale, vacation_hrs, manager_id) VALUES ('012-34-5678','Russ','NightFlight','US','Engineering','IC',3,12.5, '234-56-7890') ; ``` **Atualizar parâmetros** `INSERT` compatível com os seguintes valores como `update_parameter`: + `TTL`: um valor de tempo em segundos. O valor máximo configurável é 630.720.000 segundos, o que equivale a 20 anos. + `TIMESTAMP`: um valor `bigint` que representa o número de microssegundos desde a hora base padrão conhecida como epoch: 1º de janeiro de 1970 às 00:00:00 GMT. Um carimbo de data/hora no Amazon Keyspaces deve estar entre o intervalo de 2 dias no passado e 5 minutos no futuro. **Exemplo** ``` INSERT INTO my_table (userid, time, subject, body, user) VALUES (B79CB3BA-745E-5D9A-8903-4A02327A7E09, 96a29100-5e25-11ec-90d7-b5d91eceda0a, 'Message', 'Hello','205.212.123.123') USING TTL 259200; ``` **Suporte para JSON** Para obter uma tabela que mapeia os tipos de dados codificados em JSON para os tipos de dados do Amazon Keyspaces, consulte [Codificação JSON dos tipos de dados do Amazon Keyspaces](cql.elements.md#cql.data-types.JSON). Você pode usar a palavra-chave `JSON` para inserir um mapa codificado em `JSON` como uma única linha. Para colunas que existem na tabela, mas são omitidas na instrução de inserção do JSON, use `DEFAULT UNSET` para preservar os valores existentes. Use `DEFAULT NULL` para gravar um valor NULL em cada linha de colunas omitidas e sobrescrever os valores existentes (taxas de gravação padrão se aplicam). `DEFAULT NULL`é a opção padrão. **Exemplo** ``` INSERT INTO "myGSGKeyspace".employees_tbl JSON '{"id":"012-34-5678", "name": "Russ", "project": "NightFlight", "region": "US", "division": "Engineering", "role": "IC", "pay_scale": 3, "vacation_hrs": 12.5, "manager_id": "234-56-7890"}'; ``` Se os dados JSON contiverem chaves duplicadas, o Amazon Keyspaces armazenará o último valor da chave (semelhante ao Apache Cassandra). No exemplo a seguir, onde está a chave duplicada `id`, o valor `234-56-7890` é usado. **Exemplo** ``` INSERT INTO "myGSGKeyspace".employees_tbl JSON '{"id":"012-34-5678", "name": "Russ", "project": "NightFlight", "region": "US", "division": "Engineering", "role": "IC", "pay_scale": 3, "vacation_hrs": 12.5, "id": "234-56-7890"}'; ``` # UPDATE Use a instrução `UPDATE` para modificar uma linha em uma tabela. **Sintaxe** ``` update_statement ::= UPDATE table_name [ USING update_parameter ( AND update_parameter )* ] SET assignment ( ',' assignment )* WHERE where_clause [ IF ( EXISTS | condition ( AND condition )*) ] update_parameter ::= ( integer | bind_marker ) assignment ::= simple_selection '=' term | column_name '=' column_name ( '+' | '-' ) term | column_name '=' list_literal '+' column_name simple_selection ::= column_name | column_name '[' term ']' | column_name '.' `field_name condition ::= simple_selection operator term ``` **Exemplo** ``` UPDATE "myGSGKeyspace".employees_tbl SET pay_scale = 5 WHERE id = '567-89-0123' AND division = 'Marketing' ; ``` Para incrementar um `counter`, use a sintaxe a seguir. Para obter mais informações, consulte [Contadores](cql.elements.md#cql.data-types.numeric.counters). ``` UPDATE ActiveUsers SET counter = counter + 1 WHERE user = A70FE1C0-5408-4AE3-BE34-8733E5K09F14 AND action = 'click'; ``` **Atualizar parâmetros** `UPDATE` compatível com os seguintes valores como `update_parameter`: + `TTL`: um valor de tempo em segundos. O valor máximo configurável é 630.720.000 segundos, o que equivale a 20 anos. + `TIMESTAMP`: um valor `bigint` que representa o número de microssegundos desde a hora base padrão conhecida como epoch: 1º de janeiro de 1970 às 00:00:00 GMT. Um carimbo de data/hora no Amazon Keyspaces deve estar entre o intervalo de 2 dias no passado e 5 minutos no futuro. **Exemplo** ``` UPDATE my_table (userid, time, subject, body, user) VALUES (B79CB3BA-745E-5D9A-8903-4A02327A7E09, 96a29100-5e25-11ec-90d7-b5d91eceda0a, 'Message', 'Hello again','205.212.123.123') USING TIMESTAMP '2022-11-03 13:30:54+0400'; ``` # DELETE Use a instrução `DELETE` para remover uma linha de uma tabela. **Sintaxe** ``` delete_statement ::= DELETE [ simple_selection ( ',' simple_selection ) ] FROM table_name [ USING update_parameter ( AND update_parameter )* ] WHERE where_clause [ IF ( EXISTS | condition ( AND condition )*) ] simple_selection ::= column_name | column_name '[' term ']' | column_name '.' `field_name condition ::= simple_selection operator term ``` Em que: + `table_name` é a tabela que contém a linha a ser excluída. **Exemplo** ``` DELETE manager_id FROM "myGSGKeyspace".employees_tbl WHERE id='789-01-2345' AND division='Executive' ; ``` `DELETE` suporta o seguinte valor como `update_parameter`: + `TIMESTAMP`: um valor `bigint` que representa o número de microssegundos desde a hora base padrão conhecida como epoch: 1º de janeiro de 1970 às 00:00:00 GMT. # Funções integradas no Amazon Keyspaces O Amazon Keyspaces (para Apache Cassandra) oferece suporte a uma variedade de funções incorporadas que você pode usar nas instruções do Cassandra Query Language (CQL). **Topics** + [Funções escalares](#cql.functions.scalar) ## Funções escalares Uma *função escalar* executa um cálculo em um único valor e retorna o resultado como um valor único. O Amazon Keyspaces oferece suporte às seguintes funções escalares. **** | Função | Description | | --- | --- | | `blobAsType` | Retorna um valor do tipo de dados especificado. | | `cast` | Converte um tipo de dados nativo em outro tipo de dados nativo. | | `currentDate` | Retorna o atual date/time como uma data. | | `currentTime` | Retorna a corrente date/time como uma hora. | | `currentTimestamp` | Retorna a corrente date/time como um carimbo de data/hora. | | `currentTimeUUID` | Retorna a corrente date/time como timeuuid a. | | `fromJson` | Converte a string JSON no tipo de dados da coluna selecionada. | | `maxTimeuuid` | Retorna o maior timeuuid possível para carimbo de data/hora ou string de data. | | `minTimeuuid` | Retorna o menor timeuuid possível para carimbo de data/hora ou string de data. | | `now` | Retorna um novo timeuuid exclusivo. | | `toDate` | Converte um timeuuid ou carimbo de data/hora em um tipo de data. | | `toJson` | Retorna o valor da coluna selecionada no formato JSON. | | `token` | Retorna o valor de hash da chave de partição. | | `toTimestamp` | Converte um timeuuid ou uma data em um carimbo de data/hora. | | `TTL` | Retorna o tempo de expiração em segundos para uma coluna. | | `typeAsBlob` | Converte o tipo de dados especificado em um blob. | | `toUnixTimestamp` | Converte um timeuuid ou carimbo de data/hora em um bigInt. | | `uuid` | Retorna um UUID randomizado da versão 4. | | `writetime` | Retorna o carimbo de data/hora do valor da coluna especificada. | | `dateOf` | (Obsoleto) Extrai o carimbo de data/hora de um timeuuid e retorna o valor como uma data. | | `unixTimestampOf` | (Obsoleto) Extrai o carimbo de data/hora de um timeuuid e retorna o valor como um carimbo de data/hora inteiro bruto de 64 bits. |