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

> Este motor proporciona integración con el ecosistema Apache Hadoop al permitir gestionar datos en HDFS a través de ClickHouse. Este motor es similar a los motores File y URL, pero ofrece funcionalidades específicas de Hadoop.

# Motor de tabla 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>
            No es compatible con ClickHouse Cloud
        </div>;
};

Este motor proporciona integración con el ecosistema de [Apache Hadoop](https://en.wikipedia.org/wiki/Apache_Hadoop) al permitir gestionar datos en [HDFS](https://hadoop.apache.org/docs/current/hadoop-project-dist/hadoop-hdfs/HdfsDesign.html) a través de ClickHouse. Este motor es similar a los motores [File](/es/reference/engines/table-engines/special/file) y [URL](/es/reference/engines/table-engines/special/url), pero ofrece funcionalidades específicas de Hadoop.

Esta funcionalidad no cuenta con soporte de los ingenieros de ClickHouse y se sabe que su calidad es irregular. Si surge algún problema, tendrás que solucionarlo por tu cuenta y enviar un pull request.

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

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

**Parámetros del motor**

* `URI` - URI completa del archivo en HDFS. La parte de la ruta de `URI` puede contener globs. En ese caso, la tabla sería de solo lectura.
* `format` - especifica uno de los formatos de archivo disponibles. Para realizar
  consultas `SELECT`, el formato debe admitir entrada, y para realizar
  consultas `INSERT`, salida. Los formatos disponibles se enumeran en la
  sección [Formatos](/es/reference/formats/index#formats-overview).
* \[PARTITION BY expr]

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

`PARTITION BY` — Opcional. En la mayoría de los casos, no se necesita una clave de partición y, si hace falta, por lo general no debe ser más granular que por mes. La partición no acelera las consultas (a diferencia de la expresión ORDER BY). Nunca debe usar una partición demasiado granular. No particione sus datos por identificadores o nombres de clientes (en su lugar, haga que el identificador o el nombre del cliente sea la primera columna de la expresión ORDER BY).

Para particionar por mes, use la expresión `toYYYYMM(date_column)`, donde `date_column` es una columna con una fecha del tipo [Date](/es/reference/data-types/date). Aquí, los nombres de las particiones tienen el formato `"YYYYMM"`.

**Ejemplo:**

**1.** Configure la tabla `hdfs_engine_table`:

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

**2.** Complete el archivo:

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

**3.** Consulta los datos:

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

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

<div id="implementation-details">
  ## Detalles de implementación
</div>

* Las lecturas y escrituras pueden ser paralelas.
* No se admiten:
  * Las operaciones `ALTER` y `SELECT...SAMPLE`.
  * Los índices.
  * La [replicación zero-copy](/es/concepts/features/configuration/server-config/storing-data#zero-copy) es posible, pero no se recomienda.

<Info>
  **La replicación zero-copy no está lista para producción**

  La replicación zero-copy está deshabilitada de forma predeterminada en ClickHouse versión 22.8 y posteriores. Esta función no se recomienda para uso en producción.
</Info>

**Globs en la ruta**

Varios componentes de la ruta pueden contener globs. Para que un archivo se procese, debe existir y coincidir con el patrón completo de la ruta. La lista de archivos se determina durante `SELECT` (no en el momento de `CREATE`).

* `*` — Sustituye cualquier cantidad de caracteres, excepto `/`, incluida la cadena vacía.
* `?` — Sustituye cualquier carácter individual.
* `{some_string,another_string,yet_another_one}` — Sustituye cualquiera de las cadenas `'some_string', 'another_string', 'yet_another_one'`.
* `{N..M}` — Sustituye cualquier número en el intervalo de N a M, incluidos ambos extremos.

Las construcciones con `{}` son similares a la función de tabla [remote](/es/reference/functions/table-functions/remote).

**Ejemplo**

1. Supongamos que tenemos varios archivos en formato TSV con los siguientes URI en 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. Hay varias formas de crear una tabla compuesta por los seis archivos:

```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')
```

Otra forma:

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

La tabla se compone de todos los archivos de ambos directorios (todos los archivos deben cumplir el formato y el esquema descritos en la consulta):

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

<Note>
  Si la lista de archivos contiene rangos numéricos con ceros a la izquierda, use la sintaxis con llaves para cada dígito por separado o use `?`.
</Note>

**Ejemplo**

Cree una tabla con archivos llamados `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">
  ## Configuración
</div>

Al igual que GraphiteMergeTree, el motor HDFS admite una configuración ampliada mediante el archivo de configuración de ClickHouse. Puede usar dos claves de configuración: una global (`hdfs`) y otra a nivel de usuario (`hdfs_*`). Primero se aplica la configuración global y, después, la configuración a nivel de usuario (si existe).

```xml theme={null}
<!-- Opciones de configuración global para el 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>

<!-- Configuración específica para el usuario "root" -->
<hdfs_root>
  <hadoop_kerberos_principal>root@TEST.CLICKHOUSE.TECH</hadoop_kerberos_principal>
</hdfs_root>
```

<div id="configuration-options">
  ### Opciones de configuración
</div>

<div id="supported-by-libhdfs3">
  #### Compatible con libhdfs3
</div>

| **parámetro**                                         | **valor predeterminado** |
| ----------------------------------------------------- | ------------------------ |
| 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                             | ""                       |

La [referencia de configuración de HDFS](https://hawq.apache.org/docs/userguide/2.3.0.0-incubating/reference/HDFSConfigurationParameterReference.html) puede aclarar algunos parámetros.

<div id="clickhouse-extras">
  #### Opciones adicionales de ClickHouse
</div>

| **parámetro**               | **valor predeterminado** |
| --------------------------- | ------------------------ |
| hadoop\_kerberos\_keytab    | ""                       |
| hadoop\_kerberos\_principal | ""                       |
| libhdfs3\_conf              | ""                       |

<div id="limitations">
  ### Limitaciones
</div>

* `hadoop_security_kerberos_ticket_cache_path` y `libhdfs3_conf` solo pueden ser globales, no específicos para cada usuario

<div id="kerberos-support">
  ## Compatibilidad con Kerberos
</div>

Si el parámetro `hadoop_security_authentication` tiene el valor `kerberos`, ClickHouse se autentica mediante Kerberos.
Los parámetros están [aquí](#clickhouse-extras), y `hadoop_security_kerberos_ticket_cache_path` puede ser útil.
Tenga en cuenta que, debido a las limitaciones de libhdfs3, solo se admite el enfoque tradicional;
las comunicaciones del datanode no están protegidas mediante SASL (`HADOOP_SECURE_DN_USER` es un indicador fiable de este
enfoque de seguridad). Use `tests/integration/test_storage_kerberized_hdfs/hdfs_configs/bootstrap.sh` como referencia.

Si se especifican `hadoop_kerberos_keytab`, `hadoop_kerberos_principal` o `hadoop_security_kerberos_ticket_cache_path`, se utilizará la autenticación de Kerberos. En este caso, `hadoop_kerberos_keytab` y `hadoop_kerberos_principal` son obligatorios.

<div id="namenode-ha">
  ## Compatibilidad con HDFS NameNode HA
</div>

libhdfs3 admite HA para el NameNode de HDFS.

* Copie `hdfs-site.xml` desde un nodo de HDFS a `/etc/clickhouse-server/`.
* Agregue la siguiente sección al archivo de configuración de ClickHouse:

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

* Luego, usa el valor de la etiqueta `dfs.nameservices` de `hdfs-site.xml` como dirección del namenode en el URI de HDFS. Por ejemplo, sustituye `hdfs://appadmin@192.168.101.11:8020/abc/` por `hdfs://appadmin@my_nameservice/abc/`.

<div id="virtual-columns">
  ## Columnas virtuales
</div>

* `_path` — Ruta del archivo. Tipo: `LowCardinality(String)`.
* `_file` — Nombre del archivo. Tipo: `LowCardinality(String)`.
* `_size` — Tamaño del archivo en bytes. Tipo: `Nullable(UInt64)`. Si se desconoce el tamaño, el valor es `NULL`.
* `_time` — Fecha y hora de la última modificación del archivo. Tipo: `Nullable(DateTime)`. Si se desconoce la hora, el valor es `NULL`.

<div id="storage-settings">
  ## Configuración de almacenamiento
</div>

* [hdfs\_truncate\_on\_insert](/es/reference/settings/session-settings#hdfs_truncate_on_insert) - permite truncar el archivo antes de insertar datos en él. Deshabilitado de forma predeterminada.
* [hdfs\_create\_new\_file\_on\_insert](/es/reference/settings/session-settings#hdfs_create_new_file_on_insert) - permite crear un archivo nuevo en cada inserción si el formato tiene un sufijo. Deshabilitado de forma predeterminada.
* [hdfs\_skip\_empty\_files](/es/reference/settings/session-settings#hdfs_skip_empty_files) - permite omitir archivos vacíos durante la lectura. Deshabilitado de forma predeterminada.

**Véase también**

* [Columnas virtuales](/es/reference/engines/table-engines/index#table_engines-virtual_columns)