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

> Este motor fornece integração com o ecossistema Apache Hadoop ao permitir o gerenciamento de dados no HDFS via ClickHouse. Este motor é semelhante aos motores File e URL, mas oferece recursos específicos do Hadoop.

# Motor de tabela HDFS

export const CloudNotSupportedBadge = () => {
  return <div className="cloudNotSupportedBadge">
            <div className="cloudNotSupportedIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.5" d="M6.33366 12.6666L12.3739 12.6667C13.6593 12.6667 14.7073 11.6187 14.7073 10.3334C14.7073 9.04804 13.6593 8.00003 12.3739 8.00003C12.3739 8.00003 12.3337 7.66659 12.0003 7.33325M10.667 5.33322C8.00033 2.33325 4.45395 4.78537 4.14195 6.68203C2.55728 6.7627 1.29395 8.06203 1.29395 9.6667C1.29395 11.3234 2.66699 12.6666 4.00033 12.6666" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.5" d="M2.66699 14L12.0003 4.66663" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>

        </div>
            Not supported in ClickHouse Cloud
        </div>;
};

Este motor fornece integração com o ecossistema [Apache Hadoop](https://en.wikipedia.org/wiki/Apache_Hadoop), permitindo gerenciar dados no [HDFS](https://hadoop.apache.org/docs/current/hadoop-project-dist/hadoop-hdfs/HdfsDesign.html) via ClickHouse. Este motor é semelhante aos motores [File](/pt-BR/reference/engines/table-engines/special/file) e [URL](/pt-BR/reference/engines/table-engines/special/url), mas oferece recursos específicos do Hadoop.

Esse recurso não conta com suporte dos engenheiros do ClickHouse e sua qualidade é reconhecidamente duvidosa. Se tiver algum problema, corrija por conta própria e envie um pull request.

<div id="usage">
  ## Uso
</div>

```sql theme={null}
ENGINE = HDFS(URI, format)
```

**Parâmetros do motor**

* `URI` - URI completa do arquivo no HDFS. A parte do caminho da `URI` pode conter globs. Nesse caso, a tabela fica em modo somente leitura.
* `format` - especifica um dos formatos de arquivo disponíveis. Para executar
  consultas `SELECT`, o formato deve ser compatível com entrada e, para executar
  consultas `INSERT` – com saída. Os formatos disponíveis estão listados na
  seção [Formatos](/pt-BR/reference/formats#formats-overview).
* \[PARTITION BY expr]

<div id="partition-by">
  ### PARTITION BY
</div>

`PARTITION BY` — Opcional. Na maioria dos casos, você não precisa de uma chave de partição e, quando ela for necessária, em geral também não precisa ser mais granular do que por mês. O particionamento não acelera as consultas (ao contrário da expressão ORDER BY). Você nunca deve usar um particionamento granular demais. Não particione seus dados por identificadores ou nomes de clientes (em vez disso, use o identificador ou nome do cliente como a primeira coluna na expressão ORDER BY).

Para particionar por mês, use a expressão `toYYYYMM(date_column)`, em que `date_column` é uma coluna com uma data do tipo [Date](/pt-BR/reference/data-types/date). Os nomes das partições aqui têm o formato `"YYYYMM"`.

**Exemplo:**

**1.** Configure a tabela `hdfs_engine_table`:

```sql theme={null}
CREATE TABLE hdfs_engine_table (name String, value UInt32) ENGINE=HDFS('hdfs://hdfs1:9000/other_storage', 'TSV')
```

**2.** Preencha o arquivo:

```sql theme={null}
INSERT INTO hdfs_engine_table VALUES ('one', 1), ('two', 2), ('three', 3)
```

**3.** Consulte os dados:

```sql theme={null}
SELECT * FROM hdfs_engine_table LIMIT 2
```

```text theme={null}
┌─name─┬─value─┐
│ one  │     1 │
│ two  │     2 │
└──────┴───────┘
```

<div id="implementation-details">
  ## Detalhes de implementação
</div>

* Leituras e escritas podem ser paralelas.
* Não há suporte a:
  * operações `ALTER` e `SELECT...SAMPLE`.
  * Índices.
  * A replicação [zero-copy](/pt-BR/concepts/features/configuration/server-config/storing-data#zero-copy) é possível, mas não recomendada.

<Info>
  **A replicação zero-copy não está pronta para produção**

  A replicação zero-copy é desativada por padrão no ClickHouse 22.8 e versões posteriores. Este recurso não é recomendado para uso em produção.
</Info>

**Globs no caminho**

Vários componentes do caminho podem ter globs. Para ser processado, o arquivo deve existir e corresponder ao padrão do caminho completo. A listagem dos arquivos ocorre durante `SELECT` (não no momento de `CREATE`).

* `*` — Corresponde a qualquer quantidade de caracteres, exceto `/`, incluindo a string vazia.
* `?` — Corresponde a qualquer caractere único.
* `{some_string,another_string,yet_another_one}` — Corresponde a qualquer uma das strings `'some_string', 'another_string', 'yet_another_one'`.
* `{N..M}` — Corresponde a qualquer número no intervalo de N a M, incluindo ambos os limites.

As construções com `{}` são semelhantes à função de tabela [remote](/pt-BR/reference/functions/table-functions/remote).

**Exemplo**

1. Suponha que temos vários arquivos no formato TSV com os seguintes URIs no HDFS:

   * 'hdfs\://hdfs1:9000/some\_dir/some\_file\_1'
   * 'hdfs\://hdfs1:9000/some\_dir/some\_file\_2'
   * 'hdfs\://hdfs1:9000/some\_dir/some\_file\_3'
   * 'hdfs\://hdfs1:9000/another\_dir/some\_file\_1'
   * 'hdfs\://hdfs1:9000/another\_dir/some\_file\_2'
   * 'hdfs\://hdfs1:9000/another\_dir/some\_file\_3'

2. Há várias maneiras de criar uma tabela composta pelos seis arquivos:

```sql theme={null}
CREATE TABLE table_with_range (name String, value UInt32) ENGINE = HDFS('hdfs://hdfs1:9000/{some,another}_dir/some_file_{1..3}', 'TSV')
```

Outra maneira:

```sql theme={null}
CREATE TABLE table_with_question_mark (name String, value UInt32) ENGINE = HDFS('hdfs://hdfs1:9000/{some,another}_dir/some_file_?', 'TSV')
```

A tabela é composta por todos os arquivos em ambos os diretórios (todos os arquivos devem atender ao formato e ao esquema descritos na consulta):

```sql theme={null}
CREATE TABLE table_with_asterisk (name String, value UInt32) ENGINE = HDFS('hdfs://hdfs1:9000/{some,another}_dir/*', 'TSV')
```

<Note>
  Se a listagem de arquivos contiver intervalos numéricos com zeros à esquerda, use a sintaxe com chaves para cada dígito separadamente ou use `?`.
</Note>

**Exemplo**

Crie uma tabela com arquivos nomeados `file000`, `file001`, ... , `file999`:

```sql theme={null}
CREATE TABLE big_table (name String, value UInt32) ENGINE = HDFS('hdfs://hdfs1:9000/big_dir/file{0..9}{0..9}{0..9}', 'CSV')
```

<div id="configuration">
  ## Configuração
</div>

Assim como o GraphiteMergeTree, o mecanismo HDFS oferece suporte a configuração estendida usando o arquivo de configuração do ClickHouse. Há duas chaves de configuração que você pode usar: global (`hdfs`) e no nível do usuário (`hdfs_*`). A configuração global é aplicada primeiro e, em seguida, a configuração no nível do usuário é aplicada (se existir).

```xml theme={null}
<!-- Opções de configuração global para o tipo de motor HDFS -->
<hdfs>
  <hadoop_kerberos_keytab>/tmp/keytab/clickhouse.keytab</hadoop_kerberos_keytab>
  <hadoop_kerberos_principal>clickuser@TEST.CLICKHOUSE.TECH</hadoop_kerberos_principal>
  <hadoop_security_authentication>kerberos</hadoop_security_authentication>
</hdfs>

<!-- Configuração específica para o usuário "root" -->
<hdfs_root>
  <hadoop_kerberos_principal>root@TEST.CLICKHOUSE.TECH</hadoop_kerberos_principal>
</hdfs_root>
```

<div id="configuration-options">
  ### Opções de configuração
</div>

<div id="supported-by-libhdfs3">
  #### Suportado por libhdfs3
</div>

| **parâmetro**                                         | **valor padrão**         |
| ----------------------------------------------------- | ------------------------ |
| rpc\_client\_connect\_tcpnodelay                      | true                     |
| dfs\_client\_read\_shortcircuit                       | true                     |
| output\_replace-datanode-on-failure                   | true                     |
| input\_notretry-another-node                          | false                    |
| input\_localread\_mappedfile                          | true                     |
| dfs\_client\_use\_legacy\_blockreader\_local          | false                    |
| rpc\_client\_ping\_interval                           | 10  \* 1000              |
| rpc\_client\_connect\_timeout                         | 600 \* 1000              |
| rpc\_client\_read\_timeout                            | 3600 \* 1000             |
| rpc\_client\_write\_timeout                           | 3600 \* 1000             |
| rpc\_client\_socket\_linger\_timeout                  | -1                       |
| rpc\_client\_connect\_retry                           | 10                       |
| rpc\_client\_timeout                                  | 3600 \* 1000             |
| dfs\_default\_replica                                 | 3                        |
| input\_connect\_timeout                               | 600 \* 1000              |
| input\_read\_timeout                                  | 3600 \* 1000             |
| input\_write\_timeout                                 | 3600 \* 1000             |
| input\_localread\_default\_buffersize                 | 1 \* 1024 \* 1024        |
| dfs\_prefetchsize                                     | 10                       |
| input\_read\_getblockinfo\_retry                      | 3                        |
| input\_localread\_blockinfo\_cachesize                | 1000                     |
| input\_read\_max\_retry                               | 60                       |
| output\_default\_chunksize                            | 512                      |
| output\_default\_packetsize                           | 64 \* 1024               |
| output\_default\_write\_retry                         | 10                       |
| output\_connect\_timeout                              | 600 \* 1000              |
| output\_read\_timeout                                 | 3600 \* 1000             |
| output\_write\_timeout                                | 3600 \* 1000             |
| output\_close\_timeout                                | 3600 \* 1000             |
| output\_packetpool\_size                              | 1024                     |
| output\_heartbeat\_interval                           | 10 \* 1000               |
| dfs\_client\_failover\_max\_attempts                  | 15                       |
| dfs\_client\_read\_shortcircuit\_streams\_cache\_size | 256                      |
| dfs\_client\_socketcache\_expiryMsec                  | 3000                     |
| dfs\_client\_socketcache\_capacity                    | 16                       |
| dfs\_default\_blocksize                               | 64 \* 1024 \* 1024       |
| dfs\_default\_uri                                     | "hdfs\://localhost:9000" |
| hadoop\_security\_authentication                      | "simple"                 |
| hadoop\_security\_kerberos\_ticket\_cache\_path       | ""                       |
| dfs\_client\_log\_severity                            | "INFO"                   |
| dfs\_domain\_socket\_path                             | ""                       |

A [referência de configuração do HDFS](https://hawq.apache.org/docs/userguide/2.3.0.0-incubating/reference/HDFSConfigurationParameterReference.html) pode explicar alguns parâmetros.

<div id="clickhouse-extras">
  #### Extras do ClickHouse
</div>

| **parâmetro**               | **valor padrão** |
| --------------------------- | ---------------- |
| hadoop\_kerberos\_keytab    | ""               |
| hadoop\_kerberos\_principal | ""               |
| libhdfs3\_conf              | ""               |

<div id="limitations">
  ### Limitações
</div>

* `hadoop_security_kerberos_ticket_cache_path` e `libhdfs3_conf` só podem ser globais, não específicos por usuário

<div id="kerberos-support">
  ## Suporte ao Kerberos
</div>

Se o parâmetro `hadoop_security_authentication` tiver o valor `kerberos`, o ClickHouse será autenticado via Kerberos.
Os parâmetros estão [aqui](#clickhouse-extras), e `hadoop_security_kerberos_ticket_cache_path` pode ser útil.
Observe que, devido a limitações do libhdfs3, apenas a abordagem antiga é compatível;
as comunicações com o datanode não são protegidas por SASL (`HADOOP_SECURE_DN_USER` é um indicador confiável dessa
abordagem de segurança). Use `tests/integration/test_storage_kerberized_hdfs/hdfs_configs/bootstrap.sh` como referência.

Se `hadoop_kerberos_keytab`, `hadoop_kerberos_principal` ou `hadoop_security_kerberos_ticket_cache_path` forem especificados, a autenticação via Kerberos será usada. Nesse caso, `hadoop_kerberos_keytab` e `hadoop_kerberos_principal` são obrigatórios.

<div id="namenode-ha">
  ## Suporte a HA do NameNode do HDFS
</div>

O libhdfs3 oferece suporte a HA do NameNode do HDFS.

* Copie `hdfs-site.xml` de um nó do HDFS para `/etc/clickhouse-server/`.
* Adicione o trecho a seguir ao arquivo de configuração do ClickHouse:

```xml theme={null}
  <hdfs>
    <libhdfs3_conf>/etc/clickhouse-server/hdfs-site.xml</libhdfs3_conf>
  </hdfs>
```

* Em seguida, use o valor da tag `dfs.nameservices` em `hdfs-site.xml` como o endereço do namenode no URI do HDFS. Por exemplo, substitua `hdfs://appadmin@192.168.101.11:8020/abc/` por `hdfs://appadmin@my_nameservice/abc/`.

<div id="virtual-columns">
  ## Colunas virtuais
</div>

* `_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 for desconhecido, o valor será `NULL`.
* `_time` — Hora da última modificação do arquivo. Tipo: `Nullable(DateTime)`. Se a hora for desconhecida, o valor será `NULL`.

<div id="storage-settings">
  ## Configurações de armazenamento
</div>

* [hdfs\_truncate\_on\_insert](/pt-BR/reference/settings/session-settings#hdfs_truncate_on_insert) - permite truncar o arquivo antes de inserir dados nele. Desativado por padrão.
* [hdfs\_create\_new\_file\_on\_insert](/pt-BR/reference/settings/session-settings#hdfs_create_new_file_on_insert) - permite criar um novo arquivo a cada insert se o formato tiver sufixo. Desativado por padrão.
* [hdfs\_skip\_empty\_files](/pt-BR/reference/settings/session-settings#hdfs_skip_empty_files) - permite ignorar arquivos vazios durante a leitura. Desativado por padrão.

**Veja também**

* [Colunas virtuais](/pt-BR/reference/engines/table-engines#table_engines-virtual_columns)