# Formatos de dados e mapeamento de tipos
<a name="aurora-analytics-type-mapping"></a>

Ao criar uma tabela estrangeira, a extensão mapeia os tipos de dados do Parquet ou do Iceberg para tipos de dados do PostgreSQL. Esta seção descreve como o Aurora PostgreSQL realiza o mapeamento de tipos e quais tipos de dados do PostgreSQL são compatíveis.

**Topics**
+ [Mapeamento automático de tipos de dados](#aurora-analytics-type-mapping-automatic)
+ [Tipos não compatíveis com a inferência automática de esquemas](#aurora-analytics-type-mapping-unsupported-inference)
+ [Tipos de dados para colunas de tabelas estrangeiras](#aurora-analytics-type-mapping-column-types)

## Mapeamento automático de tipos de dados
<a name="aurora-analytics-type-mapping-automatic"></a>

Ao criar uma tabela estrangeira sem especificar definições de colunas (usando parênteses vazios), o Aurora PostgreSQL infere automaticamente os nomes das colunas e os tipos de dados com base na fonte de dados remota.

A tabela a seguir mostra como são inferidos os tipos de origem existentes tanto no Parquet quanto no Iceberg.


**Inferência de tipos para tipos de origem do Parquet e do Iceberg**  

| Tipo do Parquet | Tipo do Iceberg | Tipo de PostgreSQL | 
| --- | --- | --- | 
| BOOLEAN | boolean | boolean | 
| INT32 | int | integer | 
| INT64 | long | bigint | 
| FLOAT | float | real | 
| DOUBLE | double | double precision | 
| DECIMAL(p,s) | decimal(p,s) | numeric(p,s) | 
| BYTE\_ARRAY | binary | bytea | 
| FIXED\_LEN\_BYTE\_ARRAY | fixed(L) | bytea | 
| STRING (UTF-8) | string | text | 
| UUID | uuid | uuid | 
| DATE | date | date | 
| TIME (milissegundos/microssegundos, isAdjustedToUTC = false) | time | time | 
| TIMESTAMP (microssegundos/milissegundos, isAdjustedToUTC = false) | timestamp | timestamp | 
| TIMESTAMP (nanossegundos, isAdjustedToUTC = false) | timestamp\_ns | timestamp | 
| TIMESTAMP (microssegundos/milissegundos, isAdjustedToUTC = true) | timestamptz | timestamptz | 
| TIMESTAMP (nanossegundos, isAdjustedToUTC = true) | timestamptz\_ns | timestamptz | 

Os seguintes tipos adicionais do Parquet não têm equivalentes no Iceberg e são inferidos conforme mostrado.


**Inferência de tipos para tipos de origem exclusivos do Parquet**  

| Tipo do Parquet | Tipo de PostgreSQL | 
| --- | --- | 
| INT\_8 (inteiro de 1 byte) | smallint | 
| INT16 | smallint | 
| UNSIGNED INT8 | smallint | 
| UNSIGNED INT16 | integer | 
| UNSIGNED INT32 | bigint | 
| UNSIGNED INT64 | numeric(20,0) | 
| ENUM (lógico) | varchar | 
| JSON | json | 
| TIME (milissegundos/microssegundos, isAdjustedToUTC = true) | timetz | 
| Carimbo de data/hora legado (nanossegundos) | timestamp | 
| INTERVAL | interval | 
| BIT | varbit | 

## Tipos não compatíveis com a inferência automática de esquemas
<a name="aurora-analytics-type-mapping-unsupported-inference"></a>

Os seguintes tipos da fonte remota não podem ser inferidos automaticamente. Ao criar uma tabela estrangeira com uma lista de colunas vazia e a fonte contém um desses tipos, `CREATE FOREIGN TABLE` retorna um erro:
+ `STRUCT`
+ `MAP`
+ `LIST`
+ `GEOMETRY`
+ `GEOGRAPHY`

É possível lidar com essas colunas de duas maneiras:
+ **Ignorá-las:** defina `aurora_analytics.skip_unsupported_columns` como `true` para que a inferência automática de esquemas ignore as colunas incompatíveis e crie a tabela estrangeira com as colunas restantes. Uma notificação é emitida para cada coluna ignorada.
+ **Defini-las manualmente:** especifique a lista de colunas explicitamente e declare as colunas do tipo struct, map ou lista aninhada como `json` (ou `varchar` para uma representação de texto nativa). O Aurora PostgreSQL retorna os dados em formato JSON padrão.

```
CREATE FOREIGN TABLE my_table (
    id integer,
    name text,
    struct_col json,
    map_col json,
    list_of_struct json
)
SERVER aurora_analytics_server
OPTIONS (location 's3://my-bucket/data/', format 'parquet');
```

## Tipos de dados para colunas de tabelas estrangeiras
<a name="aurora-analytics-type-mapping-column-types"></a>

Todos os tipos de dados do PostgreSQL funcionam em consultas a tabelas estrangeiras (em expressões, resultados e junções), assim como em qualquer consulta do PostgreSQL. As seções a seguir tratam de uma questão mais específica: quais tipos podem ser definidos para uma coluna de tabela estrangeira e em quais tipos o mecanismo de analytics pode ler uma coluna do Parquet ou do Iceberg. Um tipo que não é compatível neste contexto não pode ser usado como tipo de coluna de uma tabela estrangeira, mas ainda pode ser usado livremente em outras partes da mesma consulta.

### Tipos totalmente compatíveis
<a name="aurora-analytics-type-mapping-fully-supported"></a>

Os seguintes tipos de dados do PostgreSQL são totalmente compatíveis como tipos de coluna de tabelas estrangeiras: `BOOLEAN`, `BYTEA`, `INTEGER`, `SMALLINT`, `BIGINT``REAL`, `DOUBLE PRECISION`, `TEXT`, `JSON`, `DATE` e `UUID`.

### Tipos parcialmente compatíveis
<a name="aurora-analytics-type-mapping-partially-supported"></a>

Os seguintes tipos de dados do PostgreSQL são compatíveis com algumas limitações.


**Tipos de coluna de tabela estrangeira parcialmente compatíveis**  

| Tipo de PostgreSQL | Limitação | 
| --- | --- | 
| VARCHAR, BPCHAR | As restrições de comprimento não são compatíveis (por exemplo, VARCHAR(n) ou CHAR(n)). | 
| NUMERIC, DECIMAL | A precisão (P) e a escala (S) devem ser definidas explicitamente. P deve estar entre 1 e 38. S deve estar entre 0 e P. | 
| TIME, TIMETZ | Só há suporte para precisão máxima (6). | 
| TIMESTAMP, TIMESTAMPTZ | Só há suporte para precisão máxima (6). | 
| BIT, VARBIT | As restrições de comprimento não são compatíveis (por exemplo, BIT(n) ou VARBIT(n)). | 
| INTERVAL | Só há suporte para precisão máxima (6). Os valores especiais inf, -inf e NaN não são compatíveis. | 

### Tipos não compatíveis com colunas de tabelas estrangeiras
<a name="aurora-analytics-type-mapping-not-supported"></a>

Os seguintes tipos de dados do PostgreSQL não podem ser usados como tipos de coluna de tabelas estrangeiras. Se uma coluna de tabela estrangeira for definida como um desses tipos (ou se uma coluna de origem for mapeada para um deles durante a inferência do esquema), `CREATE FOREIGN TABLE` retornará um erro. Ainda é possível usar esses tipos em outras partes de uma consulta (por exemplo, criando um valor `JSONB` na lista `SELECT` ou filtrando com um array), pois a restrição se aplica à definição da coluna, não ao uso nas consultas.


**Tipos de coluna de tabela estrangeira incompatíveis**  

| Tipo de PostgreSQL | Observações | 
| --- | --- | 
| JSONB | — | 
| SMALLSERIAL, SERIAL, BIGSERIAL | — | 
| Tipos de array | Por exemplo, INTEGER[], TEXT[]. | 
| ENUM | — | 
| INET, CIDR, MACADDR, MACADDR8 | — | 
| MONEY | — | 
| Tipos de intervalo | Por exemplo, INT4RANGE, TSRANGE, DATERANGE. | 
| Tipos geométricos | Por exemplo, POINT, LINE, POLYGON, CIRCLE. | 
| TSVECTOR, TSQUERY | — | 
| XML | — | 

**nota**  
Quando o Aurora PostgreSQL infere automaticamente o esquema de uma tabela estrangeira e a fonte contém colunas que não podem ser mapeadas, ocorre um erro por padrão. Defina o parâmetro `aurora_analytics.skip_unsupported_columns` como `true` para ignorar essas colunas e criar a tabela estrangeira com as colunas compatíveis restantes.