# Lidar com atualizações de esquemas Esta seção apresenta orientações de como processar as atualizações de esquema nos vários formatos de dados. O Athena é um mecanismo de consulta “schema-on-read”. Isso significa que, quando você cria uma tabela no Athena, ele aplica esquemas durante a leitura dos dados. Ela não altera nem reescrever os dados subjacentes. Se você antecipar alterações nos esquemas de tabela, considere criá-los em um formato de dados adequado para suas necessidades. Seus objetivos são reutilizar as consultas existentes do Athena nos esquemas em desenvolvimento e evitar erros de incompatibilidade de esquemas ao consultar tabelas com partições. Para atingir essas metas, escolha um formato de dados da tabela com base na tabela no seguinte tópico. **Topics** + [Operações de atualização de esquema com suporte por formato de dados](#summary-of-updates) + [Noções básicas do acesso ao índice para Apache ORC e Apache Parquet](#index-access) + [Fazer atualizações de esquema](make-schema-updates.md) + [Atualizar tabelas com partições](updates-and-partitions.md) ## Operações de atualização de esquema com suporte por formato de dados A tabela a seguir resume os formatos de armazenamento físico de dados e os manuseios do esquema com suporte. Use esta tabela para ajudar a escolher o formato que permitirá que você continue usando as consultas do Athena mesmo que seus esquemas sejam alterados ao longo do tempo. Nessa tabela, observe que o Parquet e ORC são formatos de coluna com diferentes métodos de acesso padrão à coluna. Por padrão, o Parquet acessa colunas por nome e o ORC por índice (valor ordinal). Portanto, o Athena oferece uma propriedade SerDe definida no momento da criação de uma tabela para alternar o método de acesso padrão a colunas, o que permite maior flexibilidade com o desenvolvimento do esquema. Para o Parquet, a propriedade `parquet.column.index.access` pode ser definida como `true`, que define que o método de acesso à coluna usará o número ordinal da coluna. Definir essa propriedade como `false` fará com que o método de acesso à coluna use o nome da coluna. Da mesma forma, para ORC, use a propriedade `orc.column.index.access` para controlar o método de acesso à coluna. Para obter mais informações, consulte [Noções básicas do acesso ao índice para Apache ORC e Apache Parquet](#index-access). Os formatos CSV e TSV permitem que você faça todos os manuseios do esquema, exceto a reorganização de colunas ou a adição de colunas ao início da tabela. Por exemplo, se a evolução do seu esquema requer apenas a renomeação de colunas, mas não a remoção delas, você pode optar por criar suas tabelas nos formatos CSV ou TSV. Se você precisar remover colunas, não use os formatos CSV ou TSV. Em vez disso, use qualquer um dos outros formatos compatíveis, de preferência um formato de coluna, como Parquet ou ORC. **Atualizações de esquema e formatos de dados no Athena** | Tipo esperado de atualização de esquema | Resumo | CSV (com e sem cabeçalhos) e TSV | JSON | AVRO | PARQUET: leitura por nome (padrão) | PARQUET: leitura por índice | ORC: leitura por índice (padrão) | ORC: leitura por nome | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | [Renomear colunas](updates-renaming-columns.md) | Armazene seus dados em CSV e TSV, ou em ORC e Parquet se eles são lidos por índice. | S | N | N | N | S | S | N | | [Adicionar colunas no início ou no meio da tabela](updates-add-columns-beginning-middle-of-table.md) | Armazene seus dados em JSON e AVRO, ou em Parquet e ORC se eles são lidos por nome. Não use CSV e TSV. | N | S | S | S | N | N | S | | [Adicionar colunas no final da tabela](updates-add-columns-end-of-table.md) | Armazene seus dados em CSV ou TSV, JSON, AVRO, ORC ou Parquet. | S | S | S | S | S | S | S | | [Remover colunas](updates-removing-columns.md) | Armazene seus dados em JSON e AVRO, ou em Parquet e ORC se eles são lidos por nome. Não use CSV e TSV. | N | S | S | S | N | N | S | | [Reclassificar colunas](updates-reordering-columns.md) | Armazene seus dados em AVRO, JSON ou em Parquet e ORC se eles são lidos por nome. | N | S | S | S | N | N | S | | [Alterar o tipo de dados de uma coluna](updates-changing-column-type.md) | Armazene seus dados em qualquer formato, mas faça o teste da consulta no Athena para garantir que os tipos de dados sejam compatíveis. No Parquet e no ORC, a alteração de um tipo de dados funciona apenas para tabelas particionadas. | S | S | S | S | S | S | S | ## Noções básicas do acesso ao índice para Apache ORC e Apache Parquet PARQUET e ORC são formatos de coluna para armazenamento físico de dados que podem ser lidos por índice ou por nome. O armazenamento dos dados em qualquer um desses formatos permite que você execute todas as operações nos esquemas e execute as consultas do Athena sem erros de incompatibilidade de esquemas. + Por padrão, o Athena *lê o ORC por índice*, conforme definido em `SERDEPROPERTIES ( 'orc.column.index.access'='true')`. Para obter mais informações, consulte [ORC: leitura por índice](#orc-read-by-index). + O Athena lê *Parquet por nome, por padrão*, conforme definido em `SERDEPROPERTIES ( 'parquet.column.index.access'='false')`. Para obter mais informações, consulte [Parquet: leitura por nome](#parquet-read-by-name). Uma vez que essas leituras são padrão, a especificação das propriedades SerDe em suas consultas `CREATE TABLE` é opcional; elas são usadas implicitamente. Quando são usadas, elas permitem que você execute algumas operações de atualização de esquema enquanto impedem outras operações semelhantes. Para habilitar essas operações, execute outra consulta `CREATE TABLE` e altere as configurações SerDe. **nota** As propriedades SerDe *não* são propagadas automaticamente para cada partição. Use instruções `ALTER TABLE ADD PARTITION` para definir as propriedades SerDe para cada partição. Para automatizar esse processo, escreva um script que execute instruções `ALTER TABLE ADD PARTITION`. As seções a seguir descrevem esses casos em detalhes. ### ORC: leitura por índice Uma tabela no formato *ORC é lida por índice*, por padrão. Isso é definido pela seguinte sintaxe: ``` WITH SERDEPROPERTIES ( 'orc.column.index.access'='true') ``` A *leitura por índice* permite renomear colunas. No entanto, não será mais possível remover colunas nem as adicionar no meio da tabela. Para fazer com que o ORC seja lido por nome, o que permitirá que você adicione colunas no meio da tabela ou remova as colunas em ORC, defina a propriedade `orc.column.index.access` do SerDe como `false` na instrução `CREATE TABLE`. Com essa configuração, não será mais possível renomear colunas. **nota** No mecanismo Athena versão 2, quando as tabelas ORC são definidas para serem lidas por nome, o Athena exige que todos os nomes de coluna dos arquivos ORC estejam em letras minúsculas. Como o Apache Spark não usa nomes de campo em letras minúsculas ao gerar arquivos ORC, o Athena talvez não consiga ler os dados que são gerados. A solução alternativa é renomear as colunas usando letras minúsculas ou usar o mecanismo Athena versão 3. O exemplo a seguir ilustra como alterar o ORC para que ele seja lido por nome: ``` CREATE EXTERNAL TABLE orders_orc_read_by_name ( `o_comment` string, `o_orderkey` int, `o_custkey` int, `o_orderpriority` string, `o_orderstatus` string, `o_clerk` string, `o_shippriority` int, `o_orderdate` string ) ROW FORMAT SERDE 'org.apache.hadoop.hive.ql.io.orc.OrcSerde' WITH SERDEPROPERTIES ( 'orc.column.index.access'='false') STORED AS INPUTFORMAT 'org.apache.hadoop.hive.ql.io.orc.OrcInputFormat' OUTPUTFORMAT 'org.apache.hadoop.hive.ql.io.orc.OrcOutputFormat' LOCATION 's3://amzn-s3-demo-bucket/orders_orc/'; ``` ### Parquet: leitura por nome Uma tabela no formato *Parquet é lida por nome*, por padrão. Isso é definido pela seguinte sintaxe: ``` WITH SERDEPROPERTIES ( 'parquet.column.index.access'='false') ``` *A leitura por nome* permite que você remova colunas ou as adicione no meio da tabela. No entanto, não será mais possível renomeá-las. Para fazer com que o Parquet seja lido por índice, o que permitirá que você renomeie colunas, é necessário criar uma tabela com a propriedade `parquet.column.index.access` do SerDe e defini-la como `true`. # Fazer atualizações de esquema Este tópico descreve algumas alterações que você pode fazer no esquema em instruções `CREATE TABLE` sem alterar os dados de fato. Para atualizar um esquema, em alguns casos é possível usar um comando `ALTER TABLE`, mas em outros casos você não modifica uma tabela existente. Em vez disso, você cria uma tabela com um novo nome que modifica o esquema usado na instrução `CREATE TABLE` original. Dependendo de como você espera que seus esquemas evoluam, para continuar usando as consultas do Athena, escolha um formato de dados compatível. Considere uma aplicação que lê informações de pedidos em uma tabela de `orders` que existe em dois formatos: CSV e Parquet. O exemplo a seguir cria uma tabela em Parquet: ``` CREATE EXTERNAL TABLE orders_parquet ( `orderkey` int, `orderstatus` string, `totalprice` double, `orderdate` string, `orderpriority` string, `clerk` string, `shippriority` int ) STORED AS PARQUET LOCATION 's3://amzn-s3-demo-bucket/orders_ parquet/'; ``` O exemplo a seguir cria a mesma tabela em CSV: ``` CREATE EXTERNAL TABLE orders_csv ( `orderkey` int, `orderstatus` string, `totalprice` double, `orderdate` string, `orderpriority` string, `clerk` string, `shippriority` int ) ROW FORMAT DELIMITED FIELDS TERMINATED BY ',' LOCATION 's3://amzn-s3-demo-bucket/orders_csv/'; ``` Os tópicos a seguir mostram como as atualizações nessas tabelas afetam as consultas do Athena. **Topics** + [Adicionar colunas no início ou no meio da tabela](updates-add-columns-beginning-middle-of-table.md) + [Adicionar colunas no final da tabela](updates-add-columns-end-of-table.md) + [Remover colunas](updates-removing-columns.md) + [Renomear colunas](updates-renaming-columns.md) + [Reclassificar colunas](updates-reordering-columns.md) + [Alteração do tipo de dados de uma coluna](updates-changing-column-type.md) # Adicionar colunas no início ou no meio da tabela A adição de colunas é uma das alterações do esquema mais frequentes. Por exemplo, você pode adicionar uma nova coluna para enriquecer a tabela com novos dados. Ou você poderá adicionar uma nova coluna se a origem para uma coluna existente for alterada e manter a versão anterior deste coluna para ajustar os aplicativos que dependem delas. Para adicionar colunas no início ou no meio da tabela e continuar executando consultas em tabelas existentes, use os formatos AVRO e JSON, bem como Parquet e ORC, se a propriedade do SerDe estiver definida para leitura por nome. Para mais informações, consulte [Noções básicas do acesso ao índice para Apache ORC e Apache Parquet](handling-schema-updates-chapter.md#index-access). Não adicione colunas no início ou no meio da tabela em CSV e TSV, pois esses formatos dependem da classificação. Se uma coluna for adicionada em um desses casos, ocorrerá um erro de incompatibilidade de esquema quando o esquema de partições for alterado. O exemplo a seguir cria uma nova tabela que adiciona uma coluna `o_comment` no meio de uma tabela baseada em dados JSON. ``` CREATE EXTERNAL TABLE orders_json_column_addition ( `o_orderkey` int, `o_custkey` int, `o_orderstatus` string, `o_comment` string, `o_totalprice` double, `o_orderdate` string, `o_orderpriority` string, `o_clerk` string, `o_shippriority` int, ) ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe' LOCATION 's3://amzn-s3-demo-bucket/orders_json/'; ``` # Adicionar colunas no final da tabela Se você criar tabelas em qualquer um dos formatos compatíveis com o Athena, como Parquet, ORC, Avro, JSON, CSV e TSV, poderá usar a instrução `ALTER TABLE ADD COLUMNS` para adicionar colunas após as colunas existentes, mas antes das colunas de partição. O exemplo a seguir adiciona uma coluna `comment` no final da tabela `orders_parquet` antes de qualquer coluna de partição: ``` ALTER TABLE orders_parquet ADD COLUMNS (comment string) ``` **nota** Para ver uma nova coluna de tabela no editor de consultas do Athena depois de executar `ALTER TABLE ADD COLUMNS`, atualize manualmente a lista de tabelas no editor e expanda a tabela outra vez. # Remover colunas Talvez você precise remover colunas de tabelas se elas não contiverem dados ou restringir o acesso aos dados contidos nelas. + Você pode remover colunas de tabelas em JSON, Avro e em ORC e Parquet se elas forem lidas por nome. Para mais informações, consulte [Noções básicas do acesso ao índice para Apache ORC e Apache Parquet](handling-schema-updates-chapter.md#index-access). + Não é recomendável remover colunas das tabelas em CSV e TSV se você deseja reter as tabelas que criou no Athena. A remoção de uma coluna rompe o esquema e requer que você recrie a tabela sem a coluna removida. Neste exemplo, remova uma coluna ``totalprice`` de uma tabela em Parquet e execute uma consulta. No Athena, por padrão o Parquet é lido por nome. É por esse motivo que omitimos a configuração SERDEPROPERTIES que especifica a leitura por nome. Observe que a consulta a seguir é bem-sucedida, mesmo que você altere o esquema: ``` CREATE EXTERNAL TABLE orders_parquet_column_removed ( `o_orderkey` int, `o_custkey` int, `o_orderstatus` string, `o_orderdate` string, `o_orderpriority` string, `o_clerk` string, `o_shippriority` int, `o_comment` string ) STORED AS PARQUET LOCATION 's3://amzn-s3-demo-bucket/orders_parquet/'; ``` # Renomear colunas Talvez você queira renomear colunas em suas tabelas para corrigir ortografia, tornar os nomes das colunas mais descritivos ou reutilizar uma coluna existente para evitar a reclassificação dela. Você pode renomear colunas se armazenar seus dados em CSV e TSV, ou em Parquet e ORC, que são configurados para leitura por índice. Para mais informações, consulte [Noções básicas do acesso ao índice para Apache ORC e Apache Parquet](handling-schema-updates-chapter.md#index-access). O Athena lê os dados em CSV e TSV na ordem das colunas no esquema e os retorna na mesma ordem. Ele não usa os nomes de coluna para mapear os dados para uma coluna. É por esse motivo que você pode renomear as colunas em CSV ou TSV sem interromper as consultas do Athena. Uma estratégia para renomear colunas é criar uma tabela com base nos mesmos dados subjacentes, mas usando novos nomes de coluna. O exemplo a seguir cria uma tabela `orders_parquet` chamada `orders_parquet_column_renamed`. O exemplo altera o nome da coluna ``o_totalprice`` para ``o_total_price`` e executa uma consulta no Athena: ``` CREATE EXTERNAL TABLE orders_parquet_column_renamed ( `o_orderkey` int, `o_custkey` int, `o_orderstatus` string, `o_total_price` double, `o_orderdate` string, `o_orderpriority` string, `o_clerk` string, `o_shippriority` int, `o_comment` string ) STORED AS PARQUET LOCATION 's3://amzn-s3-demo-bucket/orders_parquet/'; ``` No caso da tabela do Parquet, a consulta a seguir é executada. No entanto, a coluna renomeada não exibe dados, porque ela estava sendo acessada por nome (um padrão no Parquet) em vez de por índice: ``` SELECT * FROM orders_parquet_column_renamed; ``` Uma consulta com uma tabela em CSV tem aparência semelhante: ``` CREATE EXTERNAL TABLE orders_csv_column_renamed ( `o_orderkey` int, `o_custkey` int, `o_orderstatus` string, `o_total_price` double, `o_orderdate` string, `o_orderpriority` string, `o_clerk` string, `o_shippriority` int, `o_comment` string ) ROW FORMAT DELIMITED FIELDS TERMINATED BY ',' LOCATION 's3://amzn-s3-demo-bucket/orders_csv/'; ``` No caso da tabela CSV, a consulta a seguir é executada, e os dados são exibidos em todas as colunas, incluindo aquela que foi renomeada: ``` SELECT * FROM orders_csv_column_renamed; ``` # Reclassificar colunas Você pode reordenar colunas apenas em tabelas com dados em formatos de leitura por nome, como JSON ou Parquet, que leem por nome, por padrão. Você também pode fazer com que o ORC leia por nome, se necessário. Para mais informações, consulte [Noções básicas do acesso ao índice para Apache ORC e Apache Parquet](handling-schema-updates-chapter.md#index-access). O exemplo a seguir cria uma tabela com as colunas em uma ordem diferente: ``` CREATE EXTERNAL TABLE orders_parquet_columns_reordered ( `o_comment` string, `o_orderkey` int, `o_custkey` int, `o_orderpriority` string, `o_orderstatus` string, `o_clerk` string, `o_shippriority` int, `o_orderdate` string ) STORED AS PARQUET LOCATION 's3://amzn-s3-demo-bucket/orders_parquet/'; ``` # Alteração do tipo de dados de uma coluna Convém usar outro tipo de coluna quando o tipo existente não puder mais conter a quantidade de informações necessárias. Por exemplo, os valores de uma coluna de ID podem exceder o tamanho do tipo de dados `INT` e exigir o uso do tipo de dados `BIGINT`. ## Considerações Ao planejar usar um tipo de dados diferente para uma coluna, leve em consideração os seguintes pontos: + Na maioria dos casos, você não pode alterar diretamente o tipo de dados de uma coluna. Em vez disso, você recria a tabela do Athena e define a coluna com o novo tipo de dados. + Apenas certos tipos de dados podem ser lidos como outros tipos de dados. Consulte a tabela nesta seção para ver os tipos de dados que podem ser tratados dessa forma. + Para dados em formato Parquet e ORC, você não pode usar um tipo de dados diferente para uma coluna se a tabela não estiver particionada. + Para tabelas particionadas no Parquet e no ORC, o tipo de coluna de uma partição pode ser diferente do tipo de coluna de outra partição, e o Athena aplicará `CAST` ao tipo desejado, se possível. Para mais informações, consulte [Evitar erros de não correspondência de esquema para tabelas com partições](updates-and-partitions.md#partitions-dealing-with-schema-mismatch-errors). + Para tabelas criadas usando o [LazySimpleSerDe](lazy-simple-serde.md) apenas, é possível usar a declaração `ALTER TABLE REPLACE COLUMNS` para substituir colunas existentes por um tipo de dados diferente, mas todas as colunas existentes que você deseja manter também devem ser redefinidas na declaração, caso contrário, elas serão excluídas. Para obter mais informações, consulte [ALTER TABLE REPLACE COLUMNS](alter-table-replace-columns.md). + Para tabelas Apache Iceberg apenas, você pode usar a declaração [ALTER TABLE CHANGE COLUMN](querying-iceberg-alter-table-change-column.md) para alterar o tipo de dados de uma coluna. A declaração `ALTER TABLE REPLACE COLUMNS` não é suportada para tabelas Iceberg. Para obter mais informações, consulte [Evoluir o esquema de tabelas do Iceberg](querying-iceberg-evolving-table-schema.md). **Importante** É altamente recomendável testar e verificar suas consultas antes de executar as conversões de tipo de dados. Se o Athena não puder usar o tipo de dados de destino, a consulta `CREATE TABLE` poderá falhar. ## Usar tipos de dados compatíveis Sempre que possível, use tipos de dados compatíveis. A tabela a seguir lista os tipos de dados que podem ser tratados como outros tipos de dados: | Tipos de dados originais | Tipos de dados de destino disponíveis | | --- | --- | | STRING | BYTE, TINYINT, SMALLINT, INT, BIGINT | | BYTE | TINYINT, SMALLINT, INT, BIGINT | | TINYINT | SMALLINT, INT, BIGINT | | SMALLINT | INT, BIGINT | | INT | BIGINT | | FLOAT | DOUBLE | O exemplo a seguir usa a instrução `CREATE TABLE` da tabela `orders_json` original para criar uma nova tabela chamada `orders_json_bigint`. A nova tabela usa `BIGINT` em vez de `INT` como tipo de dados para a coluna ``o_shippriority``. ``` CREATE EXTERNAL TABLE orders_json_bigint ( `o_orderkey` int, `o_custkey` int, `o_orderstatus` string, `o_totalprice` double, `o_orderdate` string, `o_orderpriority` string, `o_clerk` string, `o_shippriority` BIGINT ) ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe' LOCATION 's3://amzn-s3-demo-bucket/orders_json'; ``` A seguinte consulta é executada com êxito, semelhante à consulta `SELECT` original, antes que o tipo de dados seja alterado: ``` Select * from orders_json LIMIT 10; ``` # Atualizar tabelas com partições No Athena, uma tabela e suas partições devem usar os mesmos formatos de dados, mas os esquemas podem ser diferentes. Quando você cria uma nova partição, essa partição geralmente herda o esquema da tabela. Com o passar do tempo, os esquemas podem começar a ser diferentes. Os motivos para isso incluem: + Se o esquema da tabela é alterado, os esquemas para as partições não são atualizados para permanecer em sincronia com o esquema da tabela. + O Crawler do AWS Glue permite que você descubra dados em partições com esquemas diferentes. Isso significa que, se você criar uma tabela no Athena com o AWS Glue, depois que o crawler concluir o processamento, os esquemas da tabela e suas partições poderão ser diferentes. + Se você adicionar partições diretamente usando uma API da AWS. O Athena processará tabelas com partições com êxito se elas estiverem de acordo com as restrições a seguir. Se essas restrições não forem atendidas, o Athena emitirá um erro HIVE\$1PARTITION\$1SCHEMA\$1MISMATCH. + Cada esquema de partição é compatível com o esquema da tabela. + O formato de dados da tabela permite o tipo de atualização que você deseja executar: adicionar, excluir, reclassificar colunas ou alterar um tipo de dados da coluna. Por exemplo, para os formatos CSV e TSV, você pode renomear colunas, adicionar novas colunas no final da tabela e alterar o tipo de dados de uma coluna se os tipos forem compatíveis, mas você não pode remover colunas. Para outros formatos, você pode adicionar ou remover colunas ou alterar o tipo de dados de uma coluna para outro se os tipos forem compatíveis. Para obter informações, consulte [Resumo: atualizações e formatos de dados no Athena](handling-schema-updates-chapter.md#summary-of-updates). ## Evitar erros de não correspondência de esquema para tabelas com partições No início da execução da consulta, o Athena verifica o esquema da tabela confirmando se cada tipo de dados da coluna é compatível entre a tabela e a partição. + Para os tipos de armazenamento de dados ORC e Parquet, o Athena usa os nomes das colunas para a verificação de esquema com base no nome da coluna. Isso elimina erros `HIVE_PARTITION_SCHEMA_MISMATCH` nas tabelas com partições nos tipos Parquet e ORC. (Isso será verdadeiro no ORC se a propriedade SerDe for definida para acessar o índice por nome: `orc.column.index.access=FALSE`. Por padrão, o Parquet lê o índice por nome). + Para CSV, JSON e AVRO, o Athena usa uma verificação de esquema com base no índice. Isso significa que, se você encontrar um erro de incompatibilidade de esquema, deverá descartar a partição que está causando essa incompatibilidade e recriá-la, de modo que o Athena possa consultá-la sem falhas. O Athena compara o esquema da tabela com os esquemas da partição. Se você criar uma tabela em CSV, JSON e AVRO no Athena com o crawler do AWS Glue, depois que o crawler concluir o processamento, os esquemas da tabela e suas partições poderão ser diferentes. Se houver incompatibilidade entre os esquemas da tabela e da partição, haverá falha nas consultas no Athena devido a um erro de verificação de esquema semelhante a este: 'crawler\$1test.click\$1avro' is declared as type 'string', but partition 'partition\$10=2017-01-17' declared column 'col68' as type 'double'. Uma solução comum para esses erros é eliminar a partição que está causando o erro e recriá-la. Para obter mais informações, consulte [ALTER TABLE DROP PARTITION](alter-table-drop-partition.md) e [ALTER TABLE ADD PARTITION](alter-table-add-partition.md).