> ## 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.
> Conecte fácilmente su almacenamiento de objetos a ClickHouse Cloud.
# Integración de Amazon S3 con ClickHouse Cloud
export const Image = ({img, alt, size}) => {
return
;
};
S3 ClickPipe ofrece una forma totalmente gestionada y robusta de ingestar datos desde Amazon S3 y almacenes de objetos compatibles con S3 en ClickHouse Cloud. Admite tanto la **ingestión única** como la **ingestión continua**, con semántica de exactly-once.
Los S3 ClickPipes pueden desplegarse y gestionarse manualmente mediante la UI de ClickPipes, así como de forma programática con [OpenAPI](/es/integrations/clickpipes/programmatic-access/openapi) y [Terraform](/es/integrations/clickpipes/programmatic-access/terraform).
## Fuentes de datos compatibles
| Nombre | Logo | Detalles |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Amazon S3** | 
| La ingestión continua requiere [orden lexicográfico](#continuous-ingestion-lexicographical-order) de forma predeterminada, pero puede configurarse para [ingestar archivos en cualquier orden](#continuous-ingestion-any-order). |
| **Cloudflare R2**
*Compatible con S3* | 
| La ingestión continua requiere [orden lexicográfico](#continuous-ingestion-lexicographical-order). El modo no ordenado no es compatible. |
| **DigitalOcean Spaces**
*Compatible con S3* | 
| La ingestión continua requiere [orden lexicográfico](#continuous-ingestion-lexicographical-order). El modo no ordenado no es compatible. |
| **OVH Object Storage**
*Compatible con S3* | 
| La ingestión continua requiere [orden lexicográfico](#continuous-ingestion-lexicographical-order). El modo no ordenado no es compatible. |
Debido a las diferencias en los formatos de URL y las implementaciones de API entre los proveedores de servicios de almacenamiento de objetos, no todos los servicios compatibles con S3 son compatibles de inmediato. Si tienes problemas con un servicio que no aparece en la lista anterior, [ponte en contacto con nuestro equipo](https://clickhouse.com/company/contact?loc=clickpipes).
## Formatos compatibles
* [JSON](/es/reference/formats/JSON/JSON)
* [CSV](/es/reference/formats/CSV/CSV)
* [TSV](/es/reference/formats/TabSeparated/TabSeparated)
* [Parquet](/es/reference/formats/Parquet/Parquet)
* [Avro](/es/reference/formats/Avro/Avro)
## Funciones
### Ingestión única
De forma predeterminada, el S3 ClickPipe carga todos los archivos que coinciden con un patrón del bucket especificado en la tabla de destino de ClickHouse en una sola operación por lotes. Una vez completada la tarea de ingestión, el ClickPipe se detiene automáticamente. Este modo de ingestión única ofrece semántica exactly-once, lo que garantiza que cada archivo se procese de forma fiable y sin duplicados.
### Ingestión continua
Cuando la ingestión continua está habilitada, ClickPipes ingesta datos continuamente desde la ruta especificada. Para determinar el orden de ingestión, S3 ClickPipe se basa, de forma predeterminada, en el [orden lexicográfico](#continuous-ingestion-lexicographical-order) implícito de los archivos. También puede configurarse para ingestar archivos en [cualquier orden](#continuous-ingestion-any-order) mediante una cola de [Amazon SQS](https://aws.amazon.com/sqs/) conectada al bucket.
#### Orden lexicográfico
De forma predeterminada, el S3 ClickPipe asume que los archivos se añaden a un bucket en orden lexicográfico y se basa en ese orden implícito para ingestar los archivos de forma secuencial. Esto significa que cualquier archivo nuevo **debe** ser lexicográficamente mayor que el último archivo ingestado. Por ejemplo, los archivos llamados `file1`, `file2` y `file3` se ingestarán secuencialmente, pero si se añade un nuevo `file 0` al bucket, se **ignorará** porque el nombre del archivo no es lexicográficamente mayor que el del último archivo ingestado.
En este modo, el S3 ClickPipe realiza una carga inicial de **todos los archivos** de la ruta especificada y luego consulta periódicamente si hay archivos nuevos en un intervalo configurable (de forma predeterminada, 30 segundos). **No es posible** iniciar la ingestión desde un archivo específico o un momento concreto: ClickPipes siempre cargará todos los archivos de la ruta especificada.
#### En cualquier orden
Consulta [Configurar el modo no ordenado para la ingestión continua](/es/integrations/clickpipes/object-storage/amazon-s3/unordered-mode) para ver instrucciones paso a paso.
Es posible configurar un S3 ClickPipe para ingestar archivos que no tengan un orden implícito mediante la configuración de una cola de [Amazon SQS](https://aws.amazon.com/sqs/) conectada al bucket, opcionalmente con [Amazon EventBridge](https://aws.amazon.com/eventbridge/) como enrutador de eventos. Esto permite que ClickPipes escuche eventos de creación de objetos e ingeste archivos nuevos independientemente de la convención de nomenclatura.
El modo no ordenado **solo** es compatible con Amazon S3 y **no** es compatible con buckets públicos ni con servicios compatibles con S3. Requiere configurar una cola de [Amazon SQS](https://aws.amazon.com/sqs/) conectada al bucket, opcionalmente con [Amazon EventBridge](https://aws.amazon.com/eventbridge/) como enrutador de eventos.
En este modo, el S3 ClickPipe realiza una carga inicial de **todos los archivos** de la ruta seleccionada y luego escucha eventos `ObjectCreated:*` en la cola que coincidan con la ruta especificada. Cualquier mensaje de un archivo ya visto, de un archivo que no coincida con la ruta o de un evento de otro tipo se **ignorará**.
Configurar un prefijo/sufijo para los eventos es opcional. Si lo haces, asegúrate de que coincida con la ruta configurada para el ClickPipe. S3 no permite múltiples reglas de notificación superpuestas para los mismos tipos de eventos.
Los archivos se ingieren cuando se alcanza el umbral configurado en `max insert bytes` o `max file count`, o después de un intervalo configurable (30 segundos de forma predeterminada). **No es posible** iniciar la ingestión desde un archivo específico o un momento determinado: ClickPipes siempre cargará todos los archivos de la ruta seleccionada. Si se configura una DLQ, los mensajes fallidos se volverán a encolar y se reprocesarán hasta el número de veces configurado en el parámetro `maxReceiveCount` de la DLQ.
Recomendamos encarecidamente configurar una **Dead-Letter-Queue (DLQ)** para la cola de SQS, para facilitar la depuración y el reintento de mensajes fallidos.
##### De EventBridge a SQS
También es posible enviar notificaciones de eventos de S3 a SQS a través de [Amazon EventBridge](https://aws.amazon.com/eventbridge/). Este es el enfoque recomendado para la mayoría de los casos de uso, ya que EventBridge permite un filtrado de eventos más avanzado, la distribución a múltiples destinos y no está sujeto a la limitación de S3 de una sola regla de notificación por tipo de evento y prefijo. Consulta [Configuración del modo no ordenado para la ingestión continua](/es/integrations/clickpipes/object-storage/amazon-s3/unordered-mode) para obtener instrucciones paso a paso.
##### SNS a SQS
También es posible enviar notificaciones de eventos de S3 a SQS a través de un tema de SNS. Esto puede resultar útil si te encuentras con alguna de las limitaciones de la integración directa de S3 → SQS. En este caso, tendrás que habilitar la opción de [entrega de mensajes sin formato](https://docs.aws.amazon.com/sns/latest/dg/sns-large-payload-raw-message-delivery.html).
### Coincidencia de patrones de archivos
Object Storage ClickPipes siguen el estándar POSIX para la coincidencia de patrones de archivos. Todos los patrones son **sensibles a mayúsculas y minúsculas** y coinciden con la **ruta completa** después del nombre del bucket. Para mejorar el rendimiento, use el patrón más específico posible (p. ej., `data-2024-*.csv` en lugar de `*.csv`).
#### Patrones compatibles
| Patrón | Descripción | Ejemplo | Coincidencias |
| --------------------- | --------------------------------------------------------------------------------------------------------- | ------------------- | ----------------------------------------------------------------- |
| `?` | Coincide con exactamente **un** carácter (excepto `/`) | `data-?.csv` | `data-1.csv`, `data-a.csv`, `data-x.csv` |
| `*` | Coincide con **cero o más** caracteres (excepto `/`) | `data-*.csv` | `data-1.csv`, `data-001.csv`, `data-report.csv`, `data-.csv` |
| `**`
Recursivo | Coincide con **cero o más** caracteres (incluido `/`). Permite el **recorrido recursivo de directorios**. | `logs/**/error.log` | `logs/error.log`, `logs/2024/error.log`, `logs/2024/01/error.log` |
**Ejemplos:**
* `https://bucket.s3.amazonaws.com/folder/*.csv`
* `https://bucket.s3.amazonaws.com/logs/**/data.json`
* `https://bucket.s3.amazonaws.com/file-?.parquet`
* `https://bucket.s3.amazonaws.com/data-2024-*.csv.gz`
#### Patrones no admitidos
| Patrón | Descripción | Ejemplo | Alternativas |
| ----------- | --------------------------- | ---------------------- | ---------------------------------------------- |
| `{abc,def}` | Expansión entre llaves. | `{logs,data}/file.csv` | Cree ClickPipes independientes para cada ruta. |
| `{N..M}` | Expansión de rango numérico | `file-{1..100}.csv` | Use `file-*.csv` o `file-?.csv`. |
**Ejemplos:**
* `https://bucket.s3.amazonaws.com/{documents-01,documents-02}.json`
* `https://bucket.s3.amazonaws.com/file-{1..100}.csv`
* `https://bucket.s3.amazonaws.com/{logs,metrics}/data.parquet`
### Semántica de exactly-once
Pueden producirse varios tipos de fallos al ingestar grandes conjuntos de datos, lo que puede dar lugar a inserciones parciales o datos duplicados. Object Storage ClickPipes es resiliente ante fallos de inserción y proporciona semántica de exactly-once. Esto se consigue mediante tablas temporales de "staging". Los datos se insertan primero en las tablas de staging. Si algo sale mal durante esta inserción, la tabla de staging puede truncarse y la inserción puede reintentarse desde un estado limpio. Solo cuando una inserción se completa correctamente, las particiones de la tabla de staging se mueven a la tabla de destino. Para obtener más información sobre esta estrategia, consulta [esta entrada del blog](https://clickhouse.com/blog/supercharge-your-clickhouse-data-loads-part3).
### Columnas virtuales
Para hacer un seguimiento de qué archivos se han ingerido, incluya la columna virtual `_file` en la lista de asignación de columnas. La columna virtual `_file` contiene el nombre de archivo del objeto de origen, que puede utilizarse para consultar qué archivos se han procesado.
## Control de acceso
### Permisos
El S3 ClickPipe admite buckets públicos y privados. Los buckets con [Requester Pays](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RequesterPaysBuckets.html) **no** son compatibles.
#### Bucket de S3
Los buckets deben permitir las siguientes acciones en la política del bucket:
* [`s3:GetObject`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html)
* [`s3:ListBucket`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html)
#### Cola de SQS
Al usar el [modo no ordenado](#continuous-ingestion-any-order), SQS debe permitir las siguientes acciones en la política de la cola:
* [`sqs:ReceiveMessage`](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ReceiveMessage.html)
* [`sqs:DeleteMessage`](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_DeleteMessage.html)
* [`sqs:GetQueueAttributes`](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_GetQueueAttributes.html)
* [`sqs:ListQueues`](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ListQueues.html)
### Autenticación
#### Credenciales de IAM
Para usar [claves de acceso](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) para autenticarse, selecciona `Credentials` en **Método de autenticación** al configurar tu conexión de ClickPipe. Luego, introduce el ID de la clave de acceso (por ejemplo, `AKIAIOSFODNN7EXAMPLE`) y la clave de acceso secreta (por ejemplo, `wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY`) en `Access key` y `Secret key`, respectivamente.
#### IAM role
Para usar [acceso basado en roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) para autenticarse, selecciona `IAM role` en **Método de autenticación** al configurar tu conexión de ClickPipe.
Sigue [esta guía](/es/products/cloud/guides/data-sources/accessing-s3-data-securely) para [crear un rol](/es/products/cloud/guides/data-sources/accessing-s3-data-securely#option-2-manually-create-iam-role) con la política de confianza necesaria para acceder a S3. Luego, indica el ARN del rol de IAM en `IAM role ARN`.
### Acceso de red
Los ClickPipes de S3 usan dos rutas de red distintas para el descubrimiento de metadatos y la ingestión de datos: el servicio ClickPipes y el servicio ClickHouse Cloud, respectivamente. Si desea configurar una capa adicional de seguridad de red (por ejemplo, por motivos de cumplimiento normativo), el acceso de red **debe configurarse para ambas rutas**.
* Para el **control de acceso basado en IP**, la política del bucket de S3 debe permitir las IP estáticas de la región del servicio ClickPipes indicadas [aquí](/es/integrations/clickpipes/home#list-of-static-ips), así como las [IP estáticas](/es/products/cloud/guides/data-sources/cloud-endpoints-api) del servicio ClickHouse Cloud. Para obtener las IP estáticas de su región de ClickHouse Cloud, abra una terminal y ejecute:
```bash theme={null}
# Reemplace por su región de ClickHouse Cloud
curl -s https://api.clickhouse.cloud/static-ips.json | jq -r '.aws[] | select(.region == "") | .egress_ips[]'
```
* Para el **control de acceso basado en endpoints de VPC**, el bucket de S3 debe estar en la misma región que el servicio ClickHouse Cloud y restringir las operaciones `GetObject` a los ID de los endpoints de VPC del servicio ClickHouse Cloud. Para obtener los endpoints de VPC de su región de ClickHouse Cloud, abra una terminal y ejecute:
```bash theme={null}
# Reemplace por su región de ClickHouse Cloud
curl -s https://api.clickhouse.cloud/static-ips.json | jq -r '.aws[] | select(.region == "") | .s3_endpoints[]'
```
## Configuración avanzada
ClickPipes ofrece valores predeterminados adecuados para cubrir los requisitos de la mayoría de los casos de uso. Si su caso de uso requiere un ajuste más fino, puede modificar la siguiente configuración:
| Configuración | Valor predeterminado | Descripción |
| ------------------------------------ | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Max insert bytes` | 10GB | Número de bytes que se procesan en un único lote de inserción. |
| `Max file count` | 100 | Número máximo de archivos que se procesan en un único lote de inserción. |
| `Max threads` | auto(3) | [Número máximo de hilos concurrentes](/es/reference/settings/session-settings#max_threads) para el procesamiento de archivos. |
| `Max insert threads` | 1 | [Número máximo de hilos de inserción concurrentes](/es/reference/settings/session-settings#max_insert_threads) para el procesamiento de archivos. |
| `Min insert block size bytes` | 1GB | [Tamaño mínimo, en bytes, del bloque](/es/reference/settings/session-settings#min_insert_block_size_bytes) que se puede insertar en una tabla. |
| `Max download threads` | 4 | [Número máximo de hilos de descarga concurrentes](/es/reference/settings/session-settings#max_download_threads). |
| `Object storage polling interval` | 30s | Configura el período máximo de espera antes de insertar datos en el clúster de ClickHouse. |
| `Parallel distributed insert select` | 2 | [Configuración de inserción distribuida paralela con select](/es/reference/settings/session-settings#parallel_distributed_insert_select). |
| `Parallel view processing` | false | Indica si se habilita el envío a vistas adjuntas [de forma concurrente en lugar de secuencial](/es/reference/settings/session-settings#parallel_view_processing). |
| `Use cluster function` | true | Indica si los archivos se procesan en paralelo en varios nodos. |
### Escalado
Object Storage ClickPipes se escalan en función del tamaño mínimo del servicio de ClickHouse determinado por la [configuración del escalado automático vertical](/es/products/cloud/features/autoscaling/vertical#configuring-vertical-auto-scaling). El tamaño del ClickPipe se determina cuando se crea el pipe. Los cambios posteriores en la configuración del servicio de ClickHouse no afectarán al tamaño del ClickPipe.
Para aumentar el rendimiento en trabajos de ingesta de gran volumen, recomendamos escalar el servicio de ClickHouse antes de crear el ClickPipe.
## Limitaciones conocidas
### Tamaño del archivo
ClickPipes solo intentará ingestar objetos de **10GB o menos**. Si un archivo supera los 10GB, se añadirá un error a la tabla de errores dedicada de ClickPipes.
### Compatibilidad
Aunque son compatibles con S3, algunos servicios usan una estructura de URL distinta que S3 ClickPipe podría no ser capaz de interpretar (por ejemplo, Backblaze B2), o requieren integración con servicios de cola específicos del proveedor para una ingestión continua y sin orden. Si tiene problemas con un servicio que no aparece en [Fuentes de datos compatibles](#supported-data-sources), [póngase en contacto con nuestro equipo](https://clickhouse.com/company/contact?loc=clickpipes).
### Compatibilidad con vistas
También se admiten vistas materializadas sobre la tabla de destino. ClickPipes creará tablas de staging no solo para la tabla de destino, sino también para cualquier vista materializada dependiente.
No creamos tablas de staging para vistas no materializadas. Esto significa que, si tiene una tabla de destino con una o más vistas materializadas aguas abajo, esas vistas materializadas deben evitar seleccionar datos a través de una vista sobre la tabla de destino. De lo contrario, es posible que falten datos en la vista materializada.