Skip to main content

​
Descrição

HiveText lê e grava o formato de serialização de texto usado pelas tabelas do Apache Hive (o formato gerado pelo LazySimpleSerDe do Hive). É um formato de texto delimitado, semelhante ao 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. 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), 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 é 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.
As configurações de delimitadores aninhados não têm efeito na entradaAs configurações input_format_hive_text_collection_items_delimiter e input_format_hive_text_map_keys_delimiter 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.
Por padrão, as linhas podem ter um número variável de campos (consulte input_format_hive_text_allow_variable_number_of_columns): 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.

​
Exemplo de uso

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

​
Leitura de um arquivo HiveText

Dado o arquivo hive_data.txt, com campos separados por vírgulas:
hive_data.txt
Criamos uma tabela que define os nomes e os tipos das colunas e inserimos nela o arquivo com FORMAT HiveText:
Query
Response
Observe que a primeira linha, 1,3, tem apenas dois campos, então a coluna ausente c é preenchida com o valor padrão 0.

​
Número variável de colunas

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:
hive_extras.txt
Query
Response
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.

​
Saída

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). Os valores de tipos aninhados (Array, Map e 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 (\x02 por padrão, usado para elementos de array, entradas de map e elementos de tupla) e input_format_hive_text_map_keys_delimiter (\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, 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 e 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. 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; 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.
Saída compatível com o Hive, não um round-trip completo pelo formato de entradaA 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, Map e 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 / input_format_hive_text_map_keys_delimiter. 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 é 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.
Query

​
Configurações de formato

Última modificação em 14 de agosto de 2026