# Criar índices de partição
<a name="partition-indexes"></a>

Ao longo do tempo, centenas de milhares de partições são adicionadas a uma tabela. A [API GetPartitions](https://docs.aws.amazon.com/glue/latest/webapi/API_GetPartitions.html) é usada para buscar as partições na tabela. A API retorna partições que correspondem à expressão fornecida na solicitação.

Vamos usar como exemplo uma tabela *dados\$1vendas* que é particionada pelas chaves *País*, *Categoria*, *Ano*, *Mês* e *creationDate*. Para obter os dados de vendas para todos os itens vendidos da categoria *Livros* no ano de 2020 após *15/8/2020*, será necessário fazer uma solicitação `GetPartitions` com a expressão "Categoria = 'Livros' e creationDate > '2020-08-15'" ao Catálogo de Dados.

Se nenhum índice de partição estiver presente na tabela, o AWS Glue carrega todas as partições da tabela e, em seguida, filtra as partições carregadas usando a expressão de consulta fornecida pelo usuário na solicitação `GetPartitions`. A consulta leva mais tempo para ser executada à medida que o número de partições aumenta em uma tabela sem índices. Com um índice, a consulta `GetPartitions` tentará buscar um subconjunto das partições em vez de carregar todas as partições na tabela.

**Topics**
+ [Sobre índices de partição](#partition-index-1)
+ [Criar uma tabela com índices de partição](#partition-index-creating-table)
+ [Adicionar um índice de partição a uma tabela existente](#partition-index-existing-table)
+ [Descrever índices de partição em uma tabela](#partition-index-describing)
+ [Limitações no uso de índices de partição](#partition-index-limitations)
+ [Usar índices para uma chamada GetPartitions otimizada](#partition-index-getpartitions)
+ [Integração com mecanismos](#partition-index-integration-engines)

## Sobre índices de partição
<a name="partition-index-1"></a>

Ao criar um índice de partição, você especifica uma lista de chaves de partição que já existem em uma tabela específica. O índice de partição é uma sublista de chaves de partição definidas na tabela. Um índice de partição pode ser criado em qualquer permutação de chaves de partição definidas na tabela. Para a tabela *dados\$1vendas* acima os índices possíveis são (país, categoria, creationDate), (país, categoria, ano), (país, categoria), (país), (categoria, país, ano, mês), e assim por diante.

O Data Catalog concatenará os valores de partição na ordem fornecida no momento da criação do índice. O índice é criado consistentemente à medida que as partições são adicionadas à tabela. É possível criar índices para tipos de colunas string (string, char e varchar), numérico (int, bigint, long, tinyint e smallint) e data (aaaa-MM-dd). 

**Tipos de dados compatíveis**
+ Data: uma data no formato ISO, como `YYYY-MM-DD`. Por exemplo, data `2020-08-15`. O formato usa hífens (‐) para separar o ano, o mês e o dia. O intervalo permitido para datas de indexação se estende de `0000-01-01` até `9999-12-31`.
+ String: um literal de string entre aspas simples ou duplas. 
+ Char: dados de caractere de comprimento fixo, com um comprimento especificado entre 1 e 255, por exemplo, char(10).
+ Varchar: dados de caracteres de comprimento variável com um tamanho especificado entre 1 e 65535, como varchar(10).
+ Numérico: int, bigint, long, tinyint e smallint

Índices em dados dos tipos Numérico, String e Data são compatíveis com os operadores =, >, >=, <, <= e “between” (entre). Atualmente, a solução de indexação oferece suporte somente ao operador lógico `AND`. Subexpressões com os operadores “LIKE”, “IN”, “OR” e “NOT” são ignoradas na expressão para filtragem usando um índice. A filtragem da subexpressão ignorada é feita nas partições obtidas após a aplicação da filtragem de índice.

Para cada partição adicionada a uma tabela, há um item de índice correspondente criado. Para uma tabela com “n” partições , um índice de partição resultará em “n” itens de índice de partição. O índice de partição “m” na mesma tabela resultará em “m\$1n” itens de índice de partição. Cada item de índice de partição será cobrado de acordo com a política de preços AWS Glue para armazenamento no catálogo de dados. Para obter detalhes sobre o preço do objeto de armazenamento, consulte [Preço do AWS Glue](https://aws.amazon.com/glue/pricing/).

## Criar uma tabela com índices de partição
<a name="partition-index-creating-table"></a>

Você pode criar um índice de partição durante a criação da tabela. O `CreateTable` solicita uma lista de [objetos `PartitionIndex`](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-api-catalog-tables.html#aws-glue-api-catalog-tables-PartitionIndex) como uma entrada. Um máximo de três índices de partição pode ser criado em uma determinada tabela. Cada índice de partição requer um nome e uma lista de `partitionKeys` definidos para a tabela. Os índices criados em uma tabela podem ser obtidos usando a [API `GetPartitionIndexes`](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-api-catalog-tables.html#aws-glue-api-catalog-tables-GetPartitionIndexes)

## Adicionar um índice de partição a uma tabela existente
<a name="partition-index-existing-table"></a>

Para adicionar um índice de partição a uma tabela existente, use a operação `CreatePartitionIndex`. Você só pode criar um `PartitionIndex` por operação `CreatePartitionIndex`. Adicionar um índice não afeta a disponibilidade de uma tabela, pois a tabela continua disponível enquanto os índices estão sendo criados.

O status do índice de uma partição adicionada é definido como CREATING (Criando) e a criação dos dados do índice é iniciada. Se o processo para criar os índices for bem-sucedido, indexStatus (status do índice) é atualizado para ACTIVE (Ativo) e, para um processo malsucedido, o status do índice é atualizado para FAILED (Falhou). A criação do índice pode falhar por vários motivos, e você pode usar a operação `GetPartitionIndexes` para recuperar os detalhes da falha. As possíveis falhas são:
+ ENCRYPTED\$1PARTITION\$1ERROR (Erro de partição criptografada): a criação de índice em uma tabela com partições criptografadas não é suportada.
+ INVALID\$1PARTITION\$1TYPE\$1DATA\$1ERROR (Erro de dados de tipo de partição inválidos): exibido quando o valor da `partitionKey` não é válido para o valor do tipo de dados da `partitionKey` correspondente. Por exemplo, uma `partitionKey` com o tipo de dados “int” tem um valor “foo”.
+ MISSING\$1PARTITION\$1VALUE\$1ERROR (Erro de valor de partição ausente): exibido quando o `partitionValue` para uma `indexedKey` não está presente. Isso pode acontecer quando uma tabela não é particionada de forma consistente.
+ UNSUPPORTED\$1PARTITION\$1CHARACTER\$1ERROR (Erro de caractere de partição não suportado): exibido quando o valor de uma chave de partição indexada contém os caracteres \$1u0000, \$1u0001 ou \$1u0002
+ INTERNAL\$1ERROR (Erro interno): ocorreu um erro interno enquanto os índices eram criados. 

## Descrever índices de partição em uma tabela
<a name="partition-index-describing"></a>

Para buscar os índices de partição criados em uma tabela, use a operação `GetPartitionIndexes`. A resposta retorna todos os índices na tabela, juntamente com o status atual de cada índice (o `IndexStatus`).

O `IndexStatus` para um índice de partição será um dos seguintes:
+ `CREATING`: o índice está sendo criado e ainda não está disponível para uso.
+ `ACTIVE`: o índice está pronto para uso. As solicitações podem usar o índice para executar uma consulta otimizada.
+ `DELETING`: o índice está sendo excluído e não pode mais ser usado. Um índice no estado ativo pode ser excluído usando a solicitação `DeletePartitionIndex`, que move o status de ACTIVE (Ativo) para DELETING (Excluindo).
+ `FAILED`: falha na criação do índice em uma tabela existente. Cada tabela armazena os últimos dez índices com falha.

As possíveis transições de estado para índices criados em uma tabela existente são:
+ CREATING → ACTIVE → DELETING
+ CREATING → FAILED

## Limitações no uso de índices de partição
<a name="partition-index-limitations"></a>

Depois de criar um índice de partição, observe estas alterações na funcionalidade da tabela e da partição:

**Criação de uma nova partição (após a adição do índice)**  
Depois que um índice de partição é criado em uma tabela, todas as novas partições adicionadas à tabela serão validadas para as verificações de tipo de dados para chaves indexadas. O valor da partição das chaves indexadas será validado para o formato do tipo de dados. Se a verificação do tipo de dados falhar, a operação de criação de partição falhará. Para a tabela *dados\$1de\$1venda*, se um índice for criado para chaves (categoria, ano) em que a categoria é do tipo `string` e ano do tipo `int`, a criação da nova partição com um valor de ANO como “foo” falhará.

Depois que os índices estiverem habilitados, a adição de partições com valores de chave indexados com os caracteres U\$10000, U\$100001 e U\$10002 passará a falhar.

**Atualizações de tabelas**  
Depois que um índice de partição é criado em uma tabela, você não pode modificar os nomes de chave de partição para chaves de partição existentes e não pode alterar o tipo, ou ordem, das chaves registradas com o índice.

## Usar índices para uma chamada GetPartitions otimizada
<a name="partition-index-getpartitions"></a>

Quando você chama `GetPartitions` em uma tabela com um índice, pode incluir uma expressão e, se aplicável, o Data Catalog usará um índice, se possível. A primeira chave do índice deve ser inserida na expressão para os índices a serem usados na filtragem. A otimização de índice na filtragem é aplicada como um melhor esforço. O Data Catalog tenta usar a otimização de índice tanto quanto possível, mas no caso de um índice ausente, ou operador não suportado, ele volta para a implantação existente de carregamento de todas as partições. 

Para a tabela *dados\$1de\$1venda* anterior, vamos adicionar o índice [País, Categoria, Ano]. Se “País” não for inserido na expressão, o índice registrado não poderá filtrar partições usando índices. Você pode adicionar até três índices para suportar vários padrões de consulta.

Vamos pegar algumas expressões de exemplo e ver como os índices funcionam nelas:


| Expressões | Como o índice será usado | 
| --- | --- | 
|  País = 'EUA'  |  O índice será usado para filtrar partições.  | 
|  País = 'EUA' and Categoria = 'Sapatos'  |  O índice será usado para filtrar partições.  | 
|  Categoria = 'Sapatos'  |  Os índices não serão usados, pois “país” não foi fornecido na expressão. Todas as partições serão carregadas para retornar uma resposta.  | 
|  País = 'EUA' and Categoria = 'Sapatos' and Ano > '2018'  |  O índice será usado para filtrar partições.  | 
|  País = 'EUA' and Categoria = 'Sapatos' and Ano > '2018' and mês = 2  |  O índice será usado para buscar todas as partições com país = “EUA” e categoria = “sapatos” e ano > 2018. Em seguida, a filtragem com a expressão mês será realizada.  | 
|  País = 'EUA' AND Categoria = 'Sapatos' OR Ano > '2018'  |  Os índices não serão usados, pois há um operador `OR` na expressão.  | 
|  País = 'EUA' AND Categoria = 'Sapatos' AND (Ano = '2017' OR Ano = '2018')  |  O índice será usado para buscar todas as partições com país = “US” e categoria = “sapatos” e, em seguida, a filtragem com a expressão ano será realizada.  | 
|  País in ('EUA', 'Reino Unido') AND Categoria = 'Sapatos'  |  Os índices não serão usados para filtrar, pois o operador `IN` não é suportado no momento.  | 
|  País = 'EUA' AND Categoria in ('Sapatos', 'Livros')  |  O índice será usado para buscar todas as partições com país = “EUA”. A filtragem com a expressão Categoria será realizada em seguida.  | 
|  País = 'EUA' AND Categoria in ('Sapatos', 'Livros') AND (creationDate > '2023-9-01')  |  O índice será usado para buscar todas as partições com país = "EUA" e creationDate > "2023-9-01". A filtragem com a expressão Categoria será realizada em seguida.  | 

## Integração com mecanismos
<a name="partition-index-integration-engines"></a>

Redshift Spectrum, Amazon EMR e AWS Glue ETL Spark DataFrames são capazes de utilizar índices para buscar partições depois que os índices estiverem em um estado ACTIVE (Ativo) no AWS Glue. [Athena](https://docs.aws.amazon.com/athena/latest/ug/glue-best-practices.html#glue-best-practices-partition-index) e [AWS Glue ETL Dynamic frames](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-programming-etl-partitions.html#aws-glue-programming-etl-partitions-cat-predicates) exigem que você siga etapas adicionais a fim de utilizar índices para melhorar consultas.

### Habilitar filtragem de partições
<a name="enable-partition-filtering-athena"></a>

Para ativar a filtragem de partições no Athena, é necessário atualizar as propriedades da tabela da seguinte forma:

1. No console do AWS Glue, escolha **Tabelas** em **Catálogo de Dados**.

1. Escolha uma tabela.

1. Em **Ações**, escolha **Editar tabela**.

1. Em **Propriedades da tabela**, adicione o seguinte:
   + Chave: `partition_filtering.enabled`
   + Valor: `true`

1. Escolha **Aplicar**.

Como alternativa, é possível definir esse parâmetro executando uma consulta [ALTER TABLE SET PROPERTIES](https://docs.aws.amazon.com/athena/latest/ug/alter-table-set-tblproperties.html) no Athena.

```
ALTER TABLE partition_index.table_with_index
SET TBLPROPERTIES ('partition_filtering.enabled' = 'true')
```