> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Documentação do formato HiveText

# HiveText

| Entrada | Saída | Alias |
| ------- | ----- | ----- |
| ✔       | ✔     |       |

<div id="description">
  ## Descrição
</div>

`HiveText` lê e grava o formato de serialização de texto usado pelas tabelas do [Apache Hive](https://hive.apache.org/)
(o formato gerado pelo `LazySimpleSerDe` do Hive). É um formato de texto delimitado,
semelhante ao [`CSV`](/pt-BR/reference/formats/CSV/CSV), em que os campos são
separados pelo delimitador padrão do Hive `\x01` (Ctrl-A). O delimitador de campos pode ser
configurado por meio de [`input_format_hive_text_fields_delimiter`](#format-settings).

Quando usado como formato de entrada, os dados não têm linha de cabeçalho: os valores são
mapeados por posição para as colunas da tabela de destino, portanto os nomes e tipos das colunas
são obtidos da tabela (ou de uma estrutura fornecida
explicitamente), em vez de serem inferidos a partir dos dados. Durante a leitura, o ClickHouse analisa
datas e horas no modo best effort (consulte [`date_time_input_format`](/pt-BR/reference/settings/formats/date-time#date_time_input_format)),
preenche campos finais omitidos com os valores padrão das colunas e ignora campos que não
reconhece.

Dentro de um campo, os valores são analisados usando as mesmas regras de escape do `CSV`, em vez
dos delimitadores aninhados do Hive. Em particular, uma coluna do tipo
[`Array`](/pt-BR/reference/data-types/array) é lida a partir da representação
entre colchetes (por exemplo, `"['a','b','c']"`), e não de valores separados pelo
delimitador de coleção do Hive `\x02`.

<Info>
  **As configurações de delimitadores aninhados não têm efeito na entrada**

  As configurações [`input_format_hive_text_collection_items_delimiter`](#format-settings) e
  [`input_format_hive_text_map_keys_delimiter`](#format-settings) são
  aceitas por compatibilidade, mas atualmente não são usadas durante a análise. No entanto, elas são
  usadas ao gravar valores aninhados na saída.
</Info>

Por padrão, as linhas podem ter um número variável de campos (consulte
[`input_format_hive_text_allow_variable_number_of_columns`](#format-settings)):
linhas com menos campos do que a tabela têm as colunas ausentes preenchidas com
valores padrão, e linhas com campos extras no final têm esses campos extras ignorados.

<div id="example-usage">
  ## Exemplo de uso
</div>

Os exemplos abaixo substituem o delimitador de campos padrão por uma vírgula (`,`) usando
[`input_format_hive_text_fields_delimiter`](#format-settings), para facilitar a leitura dos arquivos de entrada.

<div id="reading-data">
  ### Leitura de um arquivo HiveText
</div>

Dado o arquivo `hive_data.txt`, com campos separados por vírgulas:

```text title="hive_data.txt" theme={null}
1,3
3,5,9
```

Criamos uma tabela que define os nomes e os tipos das colunas e inserimos nela o arquivo com `FORMAT HiveText`:

```sql title="Query" theme={null}
CREATE TABLE test_tbl (a UInt16, b UInt32, c UInt32) ENGINE = MergeTree ORDER BY a;

INSERT INTO test_tbl FROM INFILE 'hive_data.txt'
SETTINGS input_format_hive_text_fields_delimiter = ','
FORMAT HiveText;

SELECT * FROM test_tbl;
```

```response title="Response" theme={null}
┌─a─┬─b─┬─c─┐
│ 1 │ 3 │ 0 │
│ 3 │ 5 │ 9 │
└───┴───┴───┘
```

Observe que a primeira linha, `1,3`, tem apenas dois campos, então a coluna ausente `c`
é preenchida com o valor padrão `0`.

<div id="variable-number-of-columns">
  ### Número variável de colunas
</div>

Com o padrão `input_format_hive_text_allow_variable_number_of_columns = 1`,
as linhas que têm mais campos do que a tabela simplesmente têm os campos
adicionais ao final ignorados:

```text title="hive_extras.txt" theme={null}
1,2,3,4,5
6,7,8
```

```sql title="Query" theme={null}
CREATE TABLE test_extras (a UInt16, b UInt32, c UInt32) ENGINE = MergeTree ORDER BY a;

INSERT INTO test_extras FROM INFILE 'hive_extras.txt'
SETTINGS input_format_hive_text_fields_delimiter = ','
FORMAT HiveText;

SELECT * FROM test_extras ORDER BY a;
```

```response title="Response" theme={null}
┌─a─┬─b─┬─c─┐
│ 1 │ 2 │ 3 │
│ 6 │ 7 │ 8 │
└───┴───┴───┘
```

Em vez disso, definir `input_format_hive_text_allow_variable_number_of_columns = 0`
impõe uma contagem estrita de campos, e uma linha com menos campos do que a tabela gera
uma exceção de análise.

<div id="output">
  ## Saída
</div>

Quando usado como formato de saída, o `HiveText` grava cada linha sem delimitação:
os campos de nível superior são separados pelo delimitador de campos (`\x01` por padrão), e
as linhas são separadas pelo delimitador de linhas (`\n` por padrão, configurável por meio de
[`format_hive_text_rows_delimiter`](#format-settings)). Os valores de tipos aninhados
([`Array`](/pt-BR/reference/data-types/array), [`Map`](/pt-BR/reference/data-types/map)
e [`Tuple`](/pt-BR/reference/data-types/tuple)) são gravados sem colchetes e
separados pelo separador do Hive correspondente ao nível de aninhamento, da mesma forma que o
`LazySimpleSerDe` do Hive. Os três primeiros separadores são o delimitador de campos configurável,
[`input_format_hive_text_collection_items_delimiter`](#format-settings)
(`\x02` por padrão, usado para elementos de array, entradas de map e elementos de tupla) e
[`input_format_hive_text_map_keys_delimiter`](#format-settings) (`\x03` por padrão,
usado entre uma chave de map e seu valor); níveis mais profundos usam, por padrão, caracteres de controle
consecutivos (`\x04`, `\x05` e assim por diante, até oito níveis). Uma árvore de tipos aninhada
com profundidade suficiente para exigir um separador além desses oito níveis é rejeitada com uma
exceção `NOT_IMPLEMENTED`, pois o `LazySimpleSerDe` do Hive também não dispõe de separador para
isso. Tipos de dados que não têm uma representação textual natural no
Hive não têm suporte como saída e geram uma exceção
`NOT_IMPLEMENTED`. Isso inclui `AggregateFunction`, `Dynamic`,
`Variant`, `LowCardinality` e `Object`, bem como os tipos
numéricos `Enum`, `Time`, `Time64` e `Interval` — o Hive não tem um tipo correspondente para estes
últimos, portanto eles são rejeitados em vez de serem gravados como seus
valores numéricos subjacentes brutos. Os tipos numéricos de maior largura `Int128`, `UInt128`, `Int256` e `UInt256`
são rejeitados pelo mesmo motivo: o maior tipo inteiro do Hive é `BIGINT` (64 bits),
e nem mesmo o `DECIMAL` do Hive, com sua precisão máxima de 38, consegue comportar seu
intervalo de valores. Da mesma forma, valores `Decimal` com precisão acima de 38 (isto é,
`Decimal256`) excedem a precisão máxima de `DECIMAL` do Hive e são rejeitados.
Da mesma forma, as chaves de `Map` devem ser de um tipo primitivo: o Hive declara maps
como `MAP<primitive_type, data_type>`, portanto um `Map` cujo tipo de chave seja `Array`,
`Map` ou `Tuple` (o que o ClickHouse permite) é rejeitado com uma
exceção `NOT_IMPLEMENTED`, pois nenhum esquema do Hive poderia ler esses valores
novamente. O literal de map vazio `map()` é rejeitado pelo mesmo motivo: seu tipo
é `Map(Nothing, Nothing)`, e `Nothing` não é um tipo que uma declaração
`MAP<key_type, data_type>` do Hive possa especificar. Todas essas verificações são aplicadas antecipadamente aos tipos de coluna declarados, antes que
qualquer linha seja gravada: uma consulta cujo cabeçalho contenha um tipo sem suporte em qualquer ponto
da árvore de tipos é rejeitada mesmo quando os valores reais nunca alcançariam a
serialização sem suporte (por exemplo, um `Nullable` de um tipo sem suporte
contendo apenas valores `NULL`, ou um `Array`/`Map` vazio de um tipo de elemento sem suporte),
pois o esquema declarado do arquivo ainda não poderia pertencer a nenhuma tabela do
Hive.

`Date`, `Date32`, `DateTime` e `DateTime64` são sempre gravados no formato de texto simples de
data e timestamp do Hive (`yyyy-MM-dd` e `yyyy-MM-dd HH:mm:ss[.fffffffff]`),
independentemente da configuração [`date_time_output_format`](/pt-BR/reference/settings/formats/date-time#date_time_output_format),
para que a saída permaneça analisável pelo Hive mesmo quando essa configuração for
`unix_timestamp` ou `iso`.

Pelo mesmo motivo, os valores `Bool` são sempre gravados como `true`/`false`,
independentemente das configurações [`bool_true_representation`](/pt-BR/reference/settings/formats/bool#bool_true_representation)
e [`bool_false_representation`](/pt-BR/reference/settings/formats/bool#bool_false_representation),
e os valores `NULL` são sempre gravados como a sequência nula padrão do Hive,
`\N`, independentemente da configuração [`format_csv_null_representation`](/pt-BR/reference/settings/formats/format-csv#format_csv_null_representation).
Isso mantém a saída legível pelo `LazySimpleSerDe` do Hive, independentemente
dessas configurações genéricas de texto. De forma correspondente, o formato de entrada `HiveText` sempre
lê `\N` como `NULL`, também independentemente da
configuração [`format_csv_null_representation`](/pt-BR/reference/settings/formats/format-csv#format_csv_null_representation);
portanto, a ida e volta de escalares de nível superior não depende dela.

Valores não finitos de `Float32` e `Float64` são gravados usando as grafias Java do Hive
`NaN`, `Infinity` e `-Infinity`, em vez dos tokens usuais `nan`/`inf`/`-inf` do ClickHouse,
para que o analisador de `FLOAT`/`DOUBLE` do Hive os leia novamente como os mesmos valores,
em vez de `NULL`.

<Info>
  **Saída compatível com o Hive, não um round-trip completo pelo formato de entrada**

  A saída é destinada ao `LazySimpleSerDe` padrão do Hive e não é simétrica ao
  formato de entrada `HiveText` do próprio ClickHouse:

  * Valores aninhados de [`Array`](/pt-BR/reference/data-types/array), [`Map`](/pt-BR/reference/data-types/map)
    e [`Tuple`](/pt-BR/reference/data-types/tuple) são gravados com os separadores aninhados do Hive
    (sem colchetes), mas o formato de entrada analisa cada campo usando regras de
    `CSV`/colchetes e ignora
    [`input_format_hive_text_collection_items_delimiter`](#format-settings) /
    [`input_format_hive_text_map_keys_delimiter`](#format-settings). Portanto, uma saída aninhada como
    `SELECT [1, 2] FORMAT HiveText` **não** é lida novamente por
    `INSERT ... FORMAT HiveText` — apenas campos escalares de nível superior fazem round-trip, e somente com
    o delimitador de linha `\n` padrão (consulte o próximo item).
  * O round-trip também exige o delimitador de linha `\n` padrão. Quando
    [`format_hive_text_rows_delimiter`](#format-settings) é alterado, a saída separa as
    linhas usando o byte configurado, mas a entrada continua sendo baseada em nova linha no
    `CSVRowInputFormat`, e não há um `input_format_hive_text_rows_delimiter` correspondente. Portanto,
    uma saída escalar com várias linhas, como
    `SELECT number FROM numbers(3) FORMAT HiveText SETTINGS format_hive_text_rows_delimiter=';'`
    (que produz `0;1;2;`), **não** é lida novamente por `INSERT ... FORMAT HiveText` como três linhas.
  * Apenas o subconjunto padrão de `LazySimpleSerDe`, sem escape, é implementado. Os campos são gravados
    sem escape (não há equivalente ao opcional `ROW FORMAT DELIMITED ...
    ESCAPED BY` do Hive), e `NULL` é sempre gravado como `\N` (não há equivalente a
    `NULL DEFINED AS`). Portanto, uma `String` que contenha um separador ativo de campo, linha ou aninhado
    é gravada literalmente e será interpretada incorretamente ao ser analisada novamente — isso
    corresponde ao comportamento do próprio Hive com uma serde sem escape. Pelo mesmo motivo, uma
    `String` cujo valor seja literalmente `\N` (por exemplo,
    `SELECT '\\N'::String FORMAT HiveText`) é gravada com os mesmos dois bytes que um
    `NULL` real; portanto, os dois são indistinguíveis no Hive.
</Info>

```sql title="Query" theme={null}
SELECT '20240305', tuple(123567, 'e01001', map('action1', 33333, 'act2', 5555)) FORMAT HiveText;
```

<div id="format-settings">
  ## Configurações de formato
</div>

| Configuração                                              | Descrição                                                                                                                                                 | Padrão |
| --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| `input_format_hive_text_fields_delimiter`                 | Delimitador entre campos no Hive Text File                                                                                                                | `\x01` |
| `input_format_hive_text_collection_items_delimiter`       | Delimitador entre itens de coleção (array ou map) no Hive Text File. Usado pelo formato de saída; é aceito, mas atualmente não é usado durante a análise. | `\x02` |
| `input_format_hive_text_map_keys_delimiter`               | Delimitador entre um par de chave/valor de map no Hive Text File. Usado pelo formato de saída; é aceito, mas atualmente não é usado durante a análise.    | `\x03` |
| `input_format_hive_text_allow_variable_number_of_columns` | Ignora colunas extras na entrada Hive Text (se o arquivo tiver mais colunas do que o esperado) e trata campos ausentes como valores padrão                | `1`    |
| `format_hive_text_rows_delimiter`                         | Delimitador no final de cada linha na saída Hive Text                                                                                                     | `\n`   |