`.
Nota: al usar la estrategia de partición `HIVE`, la configuración `use_hive_partitioning` no tiene efecto.
Ejemplo de la estrategia de partición `HIVE`:
```sql theme={null}
arthur :) CREATE TABLE t_03363_parquet (year UInt16, country String, counter UInt8)
ENGINE = S3(s3_conn, filename = 't_03363_parquet', format = Parquet, partition_strategy='hive')
PARTITION BY (year, country);
arthur :) INSERT INTO t_03363_parquet VALUES
(2022, 'USA', 1),
(2022, 'Canada', 2),
(2023, 'USA', 3),
(2023, 'Mexico', 4),
(2024, 'France', 5),
(2024, 'Germany', 6),
(2024, 'Germany', 7),
(1999, 'Brazil', 8),
(2100, 'Japan', 9),
(2024, 'CN', 10),
(2025, '', 11);
arthur :) select _path, * from t_03363_parquet;
┌─_path──────────────────────────────────────────────────────────────────────┬─year─┬─country─┬─counter─┐
1. │ test/t_03363_parquet/year=2100/country=Japan/7329604473272971264.parquet │ 2100 │ Japan │ 9 │
2. │ test/t_03363_parquet/year=2024/country=France/7329604473323302912.parquet │ 2024 │ France │ 5 │
3. │ test/t_03363_parquet/year=2022/country=Canada/7329604473314914304.parquet │ 2022 │ Canada │ 2 │
4. │ test/t_03363_parquet/year=1999/country=Brazil/7329604473289748480.parquet │ 1999 │ Brazil │ 8 │
5. │ test/t_03363_parquet/year=2023/country=Mexico/7329604473293942784.parquet │ 2023 │ Mexico │ 4 │
6. │ test/t_03363_parquet/year=2023/country=USA/7329604473319108608.parquet │ 2023 │ USA │ 3 │
7. │ test/t_03363_parquet/year=2025/country=/7329604473327497216.parquet │ 2025 │ │ 11 │
8. │ test/t_03363_parquet/year=2024/country=CN/7329604473310720000.parquet │ 2024 │ CN │ 10 │
9. │ test/t_03363_parquet/year=2022/country=USA/7329604473298137088.parquet │ 2022 │ USA │ 1 │
10. │ test/t_03363_parquet/year=2024/country=Germany/7329604473306525696.parquet │ 2024 │ Germany │ 6 │
11. │ test/t_03363_parquet/year=2024/country=Germany/7329604473306525696.parquet │ 2024 │ Germany │ 7 │
└────────────────────────────────────────────────────────────────────────────┴──────┴─────────┴─────────┘
```
### Consulta de datos particionados
Este ejemplo usa la [receta de Docker Compose](https://github.com/ClickHouse/examples/tree/5fdc6ff72f4e5137e23ea075c88d3f44b0202490/docker-compose-recipes/recipes/ch-and-minio-S3), que integra ClickHouse y MinIO. Debería poder reproducir las mismas consultas con S3 sustituyendo los valores de endpoint y autenticación.
Tenga en cuenta que el endpoint de S3 en la configuración de `ENGINE` usa el token de parámetro `{_partition_id}` como parte del objeto de S3 (nombre de archivo), y que las consultas SELECT se hacen sobre los nombres de objeto resultantes (por ejemplo, `test_3.csv`).
Como se muestra en el ejemplo, por el momento no se admite directamente consultar tablas de S3
particionadas, pero puede hacerse consultando las particiones individuales
mediante la función de tabla S3.
El principal caso de uso de escribir
datos particionados en S3 es facilitar la transferencia de esos datos a otro
sistema ClickHouse (por ejemplo, migrar de sistemas on-prem a ClickHouse
Cloud). Dado que los datasets de ClickHouse suelen ser muy grandes y que la
fiabilidad de la red no siempre es perfecta, tiene sentido transferir los datasets
en subconjuntos; de ahí la escritura particionada.
#### Crear la tabla
```sql highlight={8} theme={null}
CREATE TABLE p
(
`column1` UInt32,
`column2` UInt32,
`column3` UInt32
)
ENGINE = S3(
'http://minio:10000/clickhouse//test_{_partition_id}.csv',
'minioadmin',
'minioadminpassword',
'CSV')
PARTITION BY column3
```
#### Insertar datos
```sql theme={null}
INSERT INTO p VALUES (1, 2, 3), (3, 2, 1), (78, 43, 45)
```
#### Seleccionar desde la partición 3
Esta consulta usa la función de tabla S3
```sql theme={null}
SELECT *
FROM s3('http://minio:10000/clickhouse//test_3.csv', 'minioadmin', 'minioadminpassword', 'CSV')
```
```response theme={null}
┌─c1─┬─c2─┬─c3─┐
│ 1 │ 2 │ 3 │
└────┴────┴────┘
```
#### Seleccionar desde la partición 1
```sql theme={null}
SELECT *
FROM s3('http://minio:10000/clickhouse//test_1.csv', 'minioadmin', 'minioadminpassword', 'CSV')
```
```response theme={null}
┌─c1─┬─c2─┬─c3─┐
│ 3 │ 2 │ 1 │
└────┴────┴────┘
```
#### Seleccionar desde la partición 45
```sql theme={null}
SELECT *
FROM s3('http://minio:10000/clickhouse//test_45.csv', 'minioadmin', 'minioadminpassword', 'CSV')
```
```response theme={null}
┌─c1─┬─c2─┬─c3─┐
│ 78 │ 43 │ 45 │
└────┴────┴────┘
```
#### Limitación
Es normal que intentes `Select * from p`, pero, como se indicó antes, esta consulta fallará; usa la consulta anterior.
```sql theme={null}
SELECT * FROM p
```
```response theme={null}
Received exception from server (version 23.4.1):
Code: 48. DB::Exception: Received from localhost:9000. DB::Exception: Reading from a partitioned S3 storage is not implemented yet. (NOT_IMPLEMENTED)
```
## Insertar datos
Tenga en cuenta que las filas solo se pueden insertar en archivos nuevos. No hay ciclos de fusión ni operaciones de división de archivos. Una vez que se escribe un archivo, los insert posteriores fallarán. Para evitarlo, puede usar los ajustes `s3_truncate_on_insert` y `s3_create_new_file_on_insert`. Consulte más detalles [aquí](/es/integrations/connectors/data-ingestion/AWS/integrating-s3-with-clickhouse#inserting-data).
## Columnas virtuales
* `_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` — Hora de la última modificación del archivo. Tipo: `Nullable(DateTime)`. Si se desconoce la hora, el valor es `NULL`.
* `_etag` — ETag del archivo. Tipo: `LowCardinality(String)`. Si se desconoce el etag, el valor es `NULL`.
* `_tags` — Etiquetas del archivo. Tipo: `Map(String, String)`. Si no hay etiquetas, el valor es un mapa vacío \`{}'.
Para obtener más información sobre las columnas virtuales, consulte [aquí](/es/reference/engines/table-engines#table_engines-virtual_columns).
## Detalles de implementación
* Las lecturas y escrituras pueden ejecutarse en paralelo
* No se admiten:
* Las operaciones `ALTER` y `SELECT...SAMPLE`.
* Índices.
* La [replicación zero-copy](/es/concepts/features/configuration/server-config/storing-data#zero-copy) es posible, pero no se admite.
**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 funcionalidad no se recomienda para su uso en producción.
## Comodines en path
El argumento `path` puede especificar varios archivos mediante comodines similares a los de bash. Para que un archivo se procese, debe existir y coincidir con el patrón completo de path. 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 cantidad de caracteres, incluido `/`, 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 rango de N a M, incluidos ambos extremos. N y M pueden tener ceros a la izquierda; por ejemplo, `000..078`.
Las construcciones con `{}` son similares a la [table function](/es/reference/functions/table-functions/remote) [remote](/es/reference/functions/table-functions/remote).
Si la lista de archivos contiene rangos numéricos con ceros a la izquierda, use la construcción con llaves para cada dígito por separado o use `?`.
**Ejemplo con comodines 1**
Cree una tabla con archivos llamados `file-000.csv`, `file-001.csv`, ... , `file-999.csv`:
```sql theme={null}
CREATE TABLE big_table (name String, value UInt32)
ENGINE = S3('https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/my_folder/file-{000..999}.csv', 'CSV');
```
**Ejemplo con comodines 2**
Supongamos que tenemos varios archivos en formato CSV con las siguientes URI en S3:
* '[https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/some\_folder/some\_file\_1.csv\'](https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/some\_folder/some\_file\_1.csv\');
* '[https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/some\_folder/some\_file\_2.csv\'](https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/some\_folder/some\_file\_2.csv\');
* '[https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/some\_folder/some\_file\_3.csv\'](https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/some\_folder/some\_file\_3.csv\');
* '[https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/another\_folder/some\_file\_1.csv\'](https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/another\_folder/some\_file\_1.csv\');
* '[https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/another\_folder/some\_file\_2.csv\'](https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/another\_folder/some\_file\_2.csv\');
* '[https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/another\_folder/some\_file\_3.csv\'](https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/another\_folder/some\_file\_3.csv\');
Hay varias formas de crear una tabla a partir de estos seis archivos:
1. Especifique el intervalo de sufijos de los archivos:
```sql theme={null}
CREATE TABLE table_with_range (name String, value UInt32)
ENGINE = S3('https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/{some,another}_folder/some_file_{1..3}', 'CSV');
```
2. Tome todos los archivos con el prefijo `some_file_` (no debe haber archivos adicionales con ese prefijo en ninguna de las dos carpetas):
```sql theme={null}
CREATE TABLE table_with_question_mark (name String, value UInt32)
ENGINE = S3('https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/{some,another}_folder/some_file_?', 'CSV');
```
3. Tome todos los archivos de ambas carpetas (todos los archivos deben ajustarse al formato y al esquema descritos en la consulta):
```sql theme={null}
CREATE TABLE table_with_asterisk (name String, value UInt32)
ENGINE = S3('https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/{some,another}_folder/*', 'CSV');
```
## Configuración de almacenamiento
* [s3\_truncate\_on\_insert](/es/reference/settings/session-settings#s3_truncate_on_insert) - permite truncar el archivo antes de insertar en él. Deshabilitado de forma predeterminada.
* [s3\_create\_new\_file\_on\_insert](/es/reference/settings/session-settings#s3_create_new_file_on_insert) - permite crear un archivo nuevo en cada inserción si el formato tiene sufijo. Deshabilitado de forma predeterminada.
* [s3\_skip\_empty\_files](/es/reference/settings/session-settings#s3_skip_empty_files) - permite omitir archivos vacíos durante la lectura. Habilitado de forma predeterminada.
## Configuración relacionada con S3
La siguiente configuración puede establecerse antes de ejecutar la consulta o incluirse en el archivo de configuración.
* `s3_max_single_part_upload_size` — El tamaño máximo del objeto que se puede cargar en S3 mediante una carga de una sola parte. El valor predeterminado es `32Mb`.
* `s3_min_upload_part_size` — El tamaño mínimo de la parte que se va a cargar durante una carga multiparte en [S3 Multipart upload](https://docs.aws.amazon.com/AmazonS3/latest/dev/uploadobjusingmpu.html). El valor predeterminado es `16Mb`.
* `s3_max_redirects` — Número máximo de saltos de redirección de S3 permitidos. El valor predeterminado es `10`.
* `s3_single_read_retries` — El número máximo de reintentos durante una lectura individual. El valor predeterminado es `4`.
* `s3_max_put_rps` — Tasa máxima de solicitudes PUT por segundo antes de aplicar limitación. El valor predeterminado es `0` (ilimitado).
* `s3_max_put_burst` — Número máximo de solicitudes que pueden emitirse simultáneamente antes de alcanzar el límite de solicitudes por segundo. De forma predeterminada (valor `0`), es igual a `s3_max_put_rps`.
* `s3_max_get_rps` — Tasa máxima de solicitudes GET por segundo antes de aplicar limitación. El valor predeterminado es `0` (ilimitado).
* `s3_max_get_burst` — Número máximo de solicitudes que pueden emitirse simultáneamente antes de alcanzar el límite de solicitudes por segundo. De forma predeterminada (valor `0`), es igual a `s3_max_get_rps`.
* `s3_upload_part_size_multiply_factor` - Multiplica `s3_min_upload_part_size` por este factor cada vez que se hayan cargado `s3_multiply_parts_count_threshold` partes en una sola escritura en S3. El valor predeterminado es `2`.
* `s3_upload_part_size_multiply_parts_count_threshold` - Cada vez que se cargue este número de partes en S3, `s3_min_upload_part_size` se multiplica por `s3_upload_part_size_multiply_factor`. El valor predeterminado es `500`.
* `s3_max_inflight_parts_for_one_file` - Limita la cantidad de solicitudes PUT que pueden ejecutarse de forma concurrente para un objeto. Este número debe limitarse. El valor `0` significa ilimitado. El valor predeterminado es `20`. Cada parte en curso tiene un búfer de tamaño `s3_min_upload_part_size` para las primeras `s3_upload_part_size_multiply_factor` partes, y uno mayor cuando el archivo es lo suficientemente grande; consulte `upload_part_size_multiply_factor`. Con la configuración predeterminada, un archivo cargado consume como máximo `320Mb` si el archivo es menor de `8G`. El consumo es mayor para archivos más grandes.
Consideración de seguridad: si un usuario malicioso puede especificar URL de S3 arbitrarias, `s3_max_redirects` debe establecerse en cero para evitar ataques [SSRF](https://en.wikipedia.org/wiki/Server-side_request_forgery); como alternativa, debe especificarse `remote_host_filter` en la configuración del servidor.
## Configuración basada en endpoints
Las siguientes configuraciones pueden especificarse en el archivo de configuración para un endpoint determinado (que coincidirá con el prefijo exacto de una URL):
* `endpoint` — Especifica el prefijo de un endpoint. Obligatorio.
* `access_key_id` y `secret_access_key` — Especifican las credenciales que se usarán con el endpoint indicado. Opcional.
* `use_environment_credentials` — Si se establece en `true`, el cliente de S3 intentará obtener las credenciales de las variables de entorno y de los metadatos de [Amazon EC2](https://en.wikipedia.org/wiki/Amazon_Elastic_Compute_Cloud) para el endpoint indicado. Opcional; el valor predeterminado es `false`.
* `region` — Especifica el nombre de la región de S3. Opcional.
* `use_insecure_imds_request` — Si se establece en `true`, el cliente de S3 usará una solicitud IMDS no segura al obtener credenciales de los metadatos de Amazon EC2. Opcional; el valor predeterminado es `false`.
* `expiration_window_seconds` — Período de gracia para comprobar si las credenciales con vencimiento ya han caducado. Opcional; el valor predeterminado es `120`.
* `no_sign_request` - Ignora todas las credenciales para que las solicitudes no se firmen. Es útil para acceder a buckets públicos.
* `header` — Añade la cabecera HTTP especificada a una solicitud para el endpoint indicado. Opcional; puede especificarse varias veces.
* `access_header` - Añade la cabecera HTTP especificada a una solicitud para el endpoint indicado cuando no hay otras credenciales procedentes de otra fuente.
* `server_side_encryption_customer_key_base64` — Si se especifica, se establecerán las cabeceras necesarias para acceder a objetos S3 con cifrado SSE-C. Opcional.
* `server_side_encryption_kms_key_id` - Si se especifica, se establecerán las cabeceras necesarias para acceder a objetos S3 con [cifrado SSE-KMS](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html). Si se especifica una cadena vacía, se usará la clave de S3 administrada por AWS. Opcional.
* `server_side_encryption_kms_encryption_context` - Si se especifica junto con `server_side_encryption_kms_key_id`, se establecerá la cabecera del contexto de cifrado indicado para SSE-KMS. Opcional.
* `server_side_encryption_kms_bucket_key_enabled` - Si se especifica junto con `server_side_encryption_kms_key_id`, se establecerá la cabecera para habilitar las claves de bucket de S3 para SSE-KMS. Opcional; puede ser `true` o `false`; de forma predeterminada no se establece nada (coincide con la configuración a nivel de bucket).
* `max_single_read_retries` — Número máximo de intentos durante una sola lectura. El valor predeterminado es `4`. Opcional.
* `max_put_rps`, `max_put_burst`, `max_get_rps` y `max_get_burst` - Configuraciones de limitación de velocidad (consulte la descripción anterior) que se usarán para un endpoint específico en lugar de por consulta. Opcional.
**Ejemplo:**
```xml theme={null}
https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/
```
## Trabajar con archivos comprimidos
Supongamos que tenemos varios archivos comprimidos con los siguientes URI en S3:
* '[https://s3-us-west-1.amazonaws.com/umbrella-static/top-1m-2018-01-10.csv.zip\'](https://s3-us-west-1.amazonaws.com/umbrella-static/top-1m-2018-01-10.csv.zip\');
* '[https://s3-us-west-1.amazonaws.com/umbrella-static/top-1m-2018-01-11.csv.zip\'](https://s3-us-west-1.amazonaws.com/umbrella-static/top-1m-2018-01-11.csv.zip\');
* '[https://s3-us-west-1.amazonaws.com/umbrella-static/top-1m-2018-01-12.csv.zip\'](https://s3-us-west-1.amazonaws.com/umbrella-static/top-1m-2018-01-12.csv.zip\');
Es posible extraer datos de estos archivos comprimidos mediante ::. Se pueden usar patrones glob tanto en la parte de la URL como en la parte posterior a :: (que corresponde al nombre de un archivo dentro del archivo comprimido).
```sql theme={null}
SELECT *
FROM s3(
'https://s3-us-west-1.amazonaws.com/umbrella-static/top-1m-2018-01-1{0..2}.csv.zip :: *.csv'
);
```
ClickHouse admite tres formatos de archivo:
ZIP
TAR
7Z
Aunque se puede acceder a los archivos ZIP y TAR desde cualquier ubicación de almacenamiento compatible, los archivos 7Z solo pueden leerse desde el sistema de archivos local donde está instalado ClickHouse.
## Acceso a buckets públicos
ClickHouse intenta obtener credenciales de muchos tipos de fuentes diferentes.
A veces, esto puede ocasionar problemas al acceder a algunos buckets públicos, lo que hace que el cliente devuelva el código de error `403`.
Este problema puede evitarse usando la palabra clave `NOSIGN`, que obliga al cliente a ignorar todas las credenciales y a no firmar las solicitudes.
```sql theme={null}
CREATE TABLE big_table (name String, value UInt32)
ENGINE = S3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/aapl_stock.csv', NOSIGN, 'CSVWithNames');
```
## Optimización del rendimiento
Para obtener más información sobre cómo optimizar el rendimiento de la función s3, consulta [nuestra guía detallada](/es/integrations/connectors/data-ingestion/AWS/performance).
## Acceso basado en roles
En ClickHouse Cloud, puede utilizar el acceso basado en roles para autenticarse con S3 en lugar de usar claves de acceso. Consulte [Secure S3](/es/products/cloud/guides/data-sources/accessing-s3-data-securely) para conocer los pasos de configuración.
Una vez configurado, se puede pasar un `roleARN` mediante el parámetro `extra_credentials`:
```sql theme={null}
CREATE TABLE my_s3_table(name String, value UInt32)
ENGINE = S3('https://my-bucket.s3.amazonaws.com/data/*.csv', extra_credentials(role_arn = 'arn:aws:iam::111111111111:role/ClickHouseAccessRole-001'), 'CSV')
```
## Vea también
* [función de tabla S3](/es/reference/functions/table-functions/s3)
* [Integración de S3 con ClickHouse](/es/integrations/connectors/data-ingestion/AWS/integrating-s3-with-clickhouse)