file

Um motor de tabela que fornece uma interface semelhante a uma tabela para fazer SELECT em arquivos e INSERT neles, semelhante à função de tabela s3. Use file ao trabalhar com arquivos locais e s3 ao trabalhar com buckets em armazenamento de objetos, como S3, GCS ou MinIO.

​

Função de tabela file

Um motor de tabela que fornece uma interface semelhante a uma tabela para fazer SELECT em arquivos e INSERT neles, semelhante à função de tabela s3. Use file ao trabalhar com arquivos locais e s3 ao trabalhar com buckets em armazenamento de objetos, como S3, GCS ou MinIO.

A função file pode ser usada em consultas SELECT e INSERT para ler arquivos ou gravar neles.

​

Sintaxe

file([path_to_archive ::] path [,format] [,structure] [,compression])

Para consultas SELECT, path também pode ser uma expressão que retorna um Array(String):

file(['file1.csv', 'file2.csv'], 'CSV', 'column1 UInt32, column2 UInt32')

​

Argumentos

Parâmetro	Descrição
path	O caminho relativo para o arquivo em user_files_path, ou um Array(String) de caminhos em consultas SELECT. No modo somente leitura, aceita os seguintes globs: *, ?, {abc,def} (em que 'abc' e 'def' são strings) e {N..M} (em que N e M são números).
path_to_archive	O caminho relativo para um arquivo zip/tar/7z. Aceita os mesmos globs que path.
format	O formato do arquivo.
structure	Estrutura da tabela. Formato: 'column1_name column1_type, column2_name column2_type, ...'.
compression	O tipo de compactação existente quando usado em uma consulta SELECT, ou o tipo de compactação desejado quando usado em uma consulta INSERT. Os tipos de compactação compatíveis são gz, br, xz, zst, lz4 e bz2.

Quando o argumento structure é omitido, o ClickHouse infere o esquema a partir do próprio formato. Formatos diferentes geram nomes e tipos de coluna padrão diferentes. Para ver o esquema de um formato específico, use DESC com a função de tabela format.

Por exemplo:

DESC format(LineAsString, 'Hello\nWorld')

┌─name─┬─type───┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐
│ line │ String │              │                    │         │                  │                │
└──────┴────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘

​

Valor retornado

Uma tabela para leitura ou gravação de dados em um arquivo.

​

Exemplos de gravação em um arquivo

​

Gravar em um arquivo TSV

INSERT INTO TABLE FUNCTION
file('test.tsv', 'TSV', 'column1 UInt32, column2 UInt32, column3 UInt32')
VALUES (1, 2, 3), (3, 2, 1), (1, 3, 2)

Como resultado, os dados são gravados no arquivo test.tsv:

# cat /var/lib/clickhouse/user_files/test.tsv
1    2    3
3    2    1
1    3    2

​

Gravação particionada em vários arquivos TSV

Se você especificar uma expressão PARTITION BY ao inserir dados em uma função de tabela do tipo file, será criado um arquivo separado para cada partição. Dividir os dados em arquivos separados ajuda a melhorar o desempenho das operações de leitura.

INSERT INTO TABLE FUNCTION
file('test_{_partition_id}.tsv', 'TSV', 'column1 UInt32, column2 UInt32, column3 UInt32')
PARTITION BY column3
VALUES (1, 2, 3), (3, 2, 1), (1, 3, 2)

Como resultado, os dados são gravados em três arquivos: test_1.tsv, test_2.tsv e test_3.tsv.

# cat /var/lib/clickhouse/user_files/test_1.tsv
3    2    1

# cat /var/lib/clickhouse/user_files/test_2.tsv
1    3    2

# cat /var/lib/clickhouse/user_files/test_3.tsv
1    2    3

​

Exemplos de leitura a partir de um arquivo

​

SELECT a partir de um arquivo CSV

Primeiro, defina user_files_path na configuração do servidor e prepare um arquivo test.csv:

$ grep user_files_path /etc/clickhouse-server/config.xml
    <user_files_path>/var/lib/clickhouse/user_files/</user_files_path>

$ cat /var/lib/clickhouse/user_files/test.csv
    1,2,3
    3,2,1
    78,43,45

Em seguida, carregue os dados de test.csv para uma tabela e selecione as duas primeiras linhas:

SELECT * FROM
file('test.csv', 'CSV', 'column1 UInt32, column2 UInt32, column3 UInt32')
LIMIT 2;

┌─column1─┬─column2─┬─column3─┐
│       1 │       2 │       3 │
│       3 │       2 │       1 │
└─────────┴─────────┴─────────┘

​

Inserindo dados de um arquivo em uma tabela

INSERT INTO FUNCTION
file('test.csv', 'CSV', 'column1 UInt32, column2 UInt32, column3 UInt32')
VALUES (1, 2, 3), (3, 2, 1);

SELECT * FROM
file('test.csv', 'CSV', 'column1 UInt32, column2 UInt32, column3 UInt32');

┌─column1─┬─column2─┬─column3─┐
│       1 │       2 │       3 │
│       3 │       2 │       1 │
└─────────┴─────────┴─────────┘

Lendo dados de table.csv, contido em archive1.zip e/ou archive2.zip:

SELECT * FROM file('user_files/archives/archive{1..2}.zip :: table.csv');

​

Globs no path

Paths podem usar globs. Os arquivos devem corresponder ao pattern do path completo, não apenas ao sufixo ou ao prefixo. Há uma exceção: se o path se referir a um diretório existente e não usar globs, um * será adicionado implicitamente ao path para que todos os arquivos do diretório sejam selecionados.

• * — Representa uma quantidade arbitrária de caracteres, exceto /, incluindo a string vazia.
• ? — Representa um único caractere arbitrário.
• {some_string,another_string,yet_another_one} — Substitui qualquer uma das strings 'some_string', 'another_string', 'yet_another_one'. As strings podem conter o símbolo /.
• {N..M} — Representa qualquer número >= N e <= M.
• ** - Representa todos os arquivos dentro de uma pasta, recursivamente.

Construções com {} são semelhantes às funções de tabela remote e hdfs.

​

Exemplos

Exemplo

Suponha que existam estes arquivos com os seguintes caminhos relativos:

• some_dir/some_file_1
• some_dir/some_file_2
• some_dir/some_file_3
• another_dir/some_file_1
• another_dir/some_file_2
• another_dir/some_file_3

Execute uma consulta para obter o número total de linhas em todos os arquivos:

SELECT count(*) FROM file('{some,another}_dir/some_file_{1..3}', 'TSV', 'name String, value UInt32');

Uma expressão de caminho alternativa que produz o mesmo resultado:

SELECT count(*) FROM file('{some,another}_dir/*', 'TSV', 'name String, value UInt32');

Consulte o número total de linhas em some_dir usando o curinga * implícito:

SELECT count(*) FROM file('some_dir', 'TSV', 'name String, value UInt32');

Se sua lista de arquivos contiver intervalos numéricos com zeros à esquerda, use a construção com chaves para cada dígito separadamente ou use ?.

Exemplo

Consulte o número total de linhas nos arquivos chamados file000, file001, … , file999:

SELECT count(*) FROM file('big_dir/file{0..9}{0..9}{0..9}', 'CSV', 'name String, value UInt32');

Exemplo

Consulte o número total de linhas de todos os arquivos no diretório big_dir/, de forma recursiva:

SELECT count(*) FROM file('big_dir/**', 'CSV', 'name String, value UInt32');

Exemplo

Consulte o número total de linhas de todos os arquivos file002 em qualquer pasta do diretório big_dir/, recursivamente:

SELECT count(*) FROM file('big_dir/**/file002', 'CSV', 'name String, value UInt32');

​

Colunas virtuais

• _path — Caminho do arquivo. Tipo: LowCardinality(String).
• _file — Nome do arquivo. Tipo: LowCardinality(String).
• _size — Tamanho do arquivo em bytes. Tipo: Nullable(UInt64). Se o tamanho do arquivo for desconhecido, o valor será NULL.
• _time — Data e hora da última modificação do arquivo. Tipo: Nullable(DateTime). Se a data e hora forem desconhecidas, o valor será NULL.

​

configuração use_hive_partitioning

Quando a configuração use_hive_partitioning é definida como 1, o ClickHouse detecta o particionamento no estilo Hive no caminho (/name=value/) e permite usar colunas de partição como colunas virtuais na consulta. Essas colunas virtuais terão os mesmos nomes definidos no caminho particionado.

Exemplo

Use a coluna virtual criada com o particionamento no estilo Hive

SELECT * FROM file('data/path/date=*/country=*/code=*/*.parquet') WHERE date > '2020-01-01' AND country = 'Netherlands' AND code = 42;

​

Configurações

Configuração	Descrição
engine_file_empty_if_not_exists	permite retornar dados vazios de um arquivo que não existe. Desativado por padrão.
engine_file_truncate_on_insert	permite truncar o arquivo antes de inserir dados nele. Desativado por padrão.
engine_file_allow_create_multiple_files	permite criar um novo arquivo a cada inserção se o formato tiver sufixo. Desativado por padrão.
engine_file_skip_empty_files	permite ignorar arquivos vazios durante a leitura. Desativado por padrão.
storage_file_read_method	método de leitura de dados do arquivo de armazenamento, um dos seguintes: read, pread, mmap (somente para clickhouse-local). Valor padrão: pread para clickhouse-server, mmap para clickhouse-local.

​

Relacionados

• Colunas virtuais
• Renomear arquivos após o processamento