# Exemplo do Amazon Data Firehose
<a name="partition-projection-kinesis-firehose-example"></a>

Quando você usa o Firehose para entregar dados ao Amazon S3, a configuração padrão grava objetos com chaves semelhantes ao seguinte exemplo:

```
s3://amzn-s3-demo-bucket/prefix/yyyy/MM/dd/HH/file.extension
```

Para criar uma tabela do Athena que encontre as partições automaticamente no momento da consulta, em vez de precisar adicioná-las ao AWS Glue Data Catalog à medida que novos dados chegam, você pode usar a projeção de partições.

O exemplo de `CREATE TABLE` a seguir usa a configuração padrão do Firehose.

```
CREATE EXTERNAL TABLE my_ingested_data (
 ...
)
...
PARTITIONED BY (
 datehour STRING
)
LOCATION "s3://amzn-s3-demo-bucket/prefix/"
TBLPROPERTIES (
 "projection.enabled" = "true",
 "projection.datehour.type" = "date",
 "projection.datehour.format" = "yyyy/MM/dd/HH",
 "projection.datehour.range" = "2021/01/01/00,NOW",
 "projection.datehour.interval" = "1",
 "projection.datehour.interval.unit" = "HOURS",
 "storage.location.template" = "s3://amzn-s3-demo-bucket/prefix/${datehour}/"
)
```

A cláusula `TBLPROPERTIES` na instrução `CREATE TABLE` diz ao Athena o seguinte:
+ Usar projeção de partições ao consultar a tabela
+ A chave de partição `datehour` é do tipo `date` (que inclui um horário opcional)
+ Como as datas são formatadas
+ O intervalo dos períodos de datas. Observe que os valores devem ser separados por uma vírgula, não por um hífen.
+ Onde encontrar os dados no Amazon S3.

Quando você consulta a tabela, o Athena calcula os valores para `datehour` e usa o modelo de local de armazenamento para gerar uma lista de locais de partição.

**Topics**
+ [Como usar o tipo `date`.](partition-projection-kinesis-firehose-example-using-the-date-type.md)
+ [Como escolher chaves de partição](partition-projection-kinesis-firehose-example-choosing-partition-keys.md)
+ [Como usar prefixos personalizados e particionamento dinâmico](partition-projection-kinesis-firehose-example-using-custom-prefixes-and-dynamic-partitioning.md)

# Como usar o tipo `date`.
<a name="partition-projection-kinesis-firehose-example-using-the-date-type"></a>

Quando você usa o tipo `date` para a chave de partição projetada, deve especificar um intervalo. Como não há dados para datas antes da criação do fluxo de entrega do Firehose, você pode usar a data de criação como o início. E como você não tem dados para datas no futuro, pode usar o token especial `NOW` como fim.

No exemplo `CREATE TABLE`, a data de início é especificada como 1º de janeiro de 2021 à meia-noite UTC.

**nota**  
Configure um intervalo que corresponda o mais exatamente possível aos seus dados para que o Athena procure apenas partições existentes.

Quando uma consulta é executada na tabela de amostra, o Athena usa as condições na chave de partição `datehour` em combinação com o intervalo para gerar valores. Considere a seguinte consulta:

```
SELECT *
FROM my_ingested_data
WHERE datehour >= '2020/12/15/00'
AND datehour < '2021/02/03/15'
```

A primeira condição na consulta `SELECT` usa uma data antes do início do intervalo de datas especificado pela instrução `CREATE TABLE`. Como a configuração de projeção de partições não especifica nenhuma partição para datas antes de 1º de janeiro de 2021, o Athena procura dados somente nos locais a seguir e ignora as datas anteriores na consulta.

```
s3://amzn-s3-demo-bucket/prefix/2021/01/01/00/
s3://amzn-s3-demo-bucket/prefix/2021/01/01/01/
s3://amzn-s3-demo-bucket/prefix/2021/01/01/02/
...
s3://amzn-s3-demo-bucket/prefix/2021/02/03/12/
s3://amzn-s3-demo-bucket/prefix/2021/02/03/13/
s3://amzn-s3-demo-bucket/prefix/2021/02/03/14/
```

Da mesma forma, se a consulta fosse executada em uma data e hora antes de 3 de fevereiro de 2021 às 15:00, a última partição refletiria a data e a hora atuais, não a data e a hora na condição da consulta.

Se você quiser consultar os dados mais recentes, pode aproveitar o fato de que Athena não gera datas futuras e especificar apenas uma `datehour` de início, como no exemplo a seguir.

```
SELECT *
FROM my_ingested_data
WHERE datehour >= '2021/11/09/00'
```

# Como escolher chaves de partição
<a name="partition-projection-kinesis-firehose-example-choosing-partition-keys"></a>

Você pode especificar como a projeção de partições mapeia os locais de partição para chaves de partição. No exemplo da seção anterior para `CREATE TABLE`, a data e o horário foram combinados em uma chave de partição chamada “datehour”, mas outros esquemas são possíveis. Por exemplo, você também pode configurar uma tabela com chaves de partição separadas por ano, mês, dia e hora. 

No entanto, dividir datas em ano, mês e dia significa que o tipo de projeção de partição `date` não pode ser usado. Uma alternativa é separar a data do horário para ainda aproveitar o tipo de projeção da partição `date`, mas facilitar a leitura das consultas que especificam intervalos de horas.

Com isso em mente, o exemplo `CREATE TABLE` a seguir separa a data da hora. Como `date` é uma palavra reservada em SQL, o exemplo usa `day` como nome da chave de partição que representa a data.

```
CREATE EXTERNAL TABLE my_ingested_data2 (
 ...
)
...
PARTITIONED BY (
 day STRING,
 hour INT
)
LOCATION "s3://amzn-s3-demo-bucket/prefix/"
TBLPROPERTIES (
 "projection.enabled" = "true",
 "projection.day.type" = "date",
 "projection.day.format" = "yyyy/MM/dd",
 "projection.day.range" = "2021/01/01,NOW",
 "projection.day.interval" = "1",
 "projection.day.interval.unit" = "DAYS",
 "projection.hour.type" = "integer",
 "projection.hour.range" = "0,23",
 "projection.hour.digits" = "2",
 "storage.location.template" = "s3://amzn-s3-demo-bucket/prefix/${day}/${hour}/"
)
```

No exemplo de instrução `CREATE TABLE`, a hora é uma chave de partição separada, configurada como um inteiro. A configuração para a chave de partição de hora especifica o intervalo de 0 a 23 e que a hora deverá ser formatada com dois dígitos quando o Athena gerar os locais de partições.

Uma consulta para a tabela `my_ingested_data2` poderia ser semelhante a esta:

```
SELECT *
FROM my_ingested_data2
WHERE day = '2021/11/09'
AND hour > 3
```

## Noções básicas de chave de partição e tipos de dados de projeção de partições
<a name="partition-projection-kinesis-firehose-example-partition-key-types-and-partition-projection-types"></a>

Observe que a chave `datehour` no primeiro exemplo de `CREATE TABLE` é configurada como `date` na configuração de projeção de partições, mas o tipo de chave de partição é `string`. O mesmo vale para `day` no segundo exemplo. Os tipos na configuração de projeção de partições apenas dizem ao Athena como formatar os valores quando ele gera os locais de partição. Os tipos especificados não alteram o tipo da chave de partição. Em consultas, `datehour` e `day` são do tipo `string`.

Quando uma consulta inclui uma condição como `day = '2021/11/09'`, o Athena analisa a sequência do lado direito da expressão usando o formato de data especificado na configuração de projeção de partições. Depois que o Athena verifica se a data está dentro do intervalo configurado, ele usa o formato de data novamente para inserir a data como uma sequência no modelo de local de armazenamento.

Da mesma forma, para uma condição de consulta como `day > '2021/11/09'`, o Athena analisa o lado direito e gera uma lista de todas as datas correspondentes dentro do intervalo configurado. Em seguida, ele usa o formato de data para inserir cada data no modelo de local de armazenamento para criar a lista de locais de partição.

Escrever a mesma condição que `day > '2021-11-09'` ou `day > DATE '2021-11-09'` não funciona. No primeiro caso, o formato de data não corresponde (observe os hifens em vez de barras) e, no segundo caso, os tipos de dados não correspondem.

# Como usar prefixos personalizados e particionamento dinâmico
<a name="partition-projection-kinesis-firehose-example-using-custom-prefixes-and-dynamic-partitioning"></a>

É possível configurar o Firehose com [prefixos personalizados](https://docs.aws.amazon.com/firehose/latest/dev/s3-prefixes.html) e [particionamento dinâmico](https://docs.aws.amazon.com/firehose/latest/dev/dynamic-partitioning.html). Usando esses recursos, você pode configurar as chaves do Amazon S3 e configurar esquemas de particionamento que suportem melhor seu caso de uso. Você também pode usar a projeção de partições com esses esquemas de particionamento e configurá-los de acordo.

Por exemplo, você pode usar o recurso de prefixo personalizado para obter chaves do Amazon S3 com datas em formato ISO em vez do esquema padrão de `yyyy/MM/dd/HH`.

Você também pode combinar prefixos personalizados com particionamento dinâmico para extrair uma propriedade como `customer_id` das mensagens do Firehose, como no exemplo a seguir.

```
prefix/!{timestamp:yyyy}-!{timestamp:MM}-!{timestamp:dd}/!{partitionKeyFromQuery:customer_id}/
```

Com esse prefixo do Amazon S3, o fluxo de entrega do Firehose gravaria objetos em chaves como `s3://amzn-s3-demo-bucket/prefix/2021-11-01/customer-1234/file.extension`. Para uma propriedade como `customer_id`, na qual os valores podem não ser conhecidos com antecedência, você pode usar o tipo de projeção de partições `injected` e usar uma instrução `CREATE TABLE` como a seguinte:

```
CREATE EXTERNAL TABLE my_ingested_data3 (
 ...
)
...
PARTITIONED BY (
 day STRING,
 customer_id STRING
)
LOCATION "s3://amzn-s3-demo-bucket/prefix/"
TBLPROPERTIES (
 "projection.enabled" = "true",
 "projection.day.type" = "date",
 "projection.day.format" = "yyyy-MM-dd",
 "projection.day.range" = "2021-01-01,NOW",
 "projection.day.interval" = "1",
 "projection.day.interval.unit" = "DAYS",
 "projection.customer_id.type" = "injected",
 "storage.location.template" = "s3://amzn-s3-demo-bucket/prefix/${day}/${customer_id}/"
)
```

Quando você consulta uma tabela que tem uma chave de partição do tipo `injected`, sua consulta deve incluir um valor para essa chave de partição. Uma consulta para a tabela `my_ingested_data3` poderia ser semelhante a esta:

```
SELECT *
FROM my_ingested_data3
WHERE day BETWEEN '2021-11-01' AND '2021-11-30'
AND customer_id = 'customer-1234'
```

## Usar o tipo DATE para a chave de partição do dia
<a name="partition-projection-kinesis-firehose-example-iso-formatted-dates"></a>

Como os valores para chave de partição `day` são em formato ISO, você também pode usar o tipo `DATE`, em vez de `STRING`, para a chave de partição de dia, como no exemplo a seguir:

```
PARTITIONED BY (day DATE, customer_id STRING)
```

Quando você consulta, essa estratégia permite que você use funções de data na chave de partição sem análise ou conversão, como no exemplo a seguir:

```
SELECT *
FROM my_ingested_data3
WHERE day > CURRENT_DATE - INTERVAL '7' DAY
AND customer_id = 'customer-1234'
```

**nota**  
A especificação de uma chave de partição do tipo `DATE` pressupõe que você usou o atributo [custom prefix](https://docs.aws.amazon.com/firehose/latest/dev/s3-prefixes.html) para criar chaves do Amazon S3 que tenham datas no formato ISO. Caso esteja usando o formato padrão de `yyyy/MM/dd/HH` do Firehose, você deverá especificar a chave de partição com o tipo `string`, mesmo que a propriedade da tabela correspondente seja do tipo `date`, como no seguinte exemplo:  

```
PARTITIONED BY ( 
  `mydate` string)
TBLPROPERTIES (
  'projection.enabled'='true', 
   ...
  'projection.mydate.type'='date',
  'storage.location.template'='s3://amzn-s3-demo-bucket/prefix/${mydate}')
```