# S3 y httpfs

> Consulta Amazon S3 y almacenamiento compatible con S3 desde DuckLocal con httpfs de DuckDB: configura credenciales, explora buckets y ejecuta SQL en archivos remotos.

Source: https://ducklocal.app/docs/es/s3

DuckLocal puede leer objetos de S3 y de almacenamiento compatible con S3 mediante la
extensión `httpfs` de DuckDB. Configúralo desde el botón **S3** de la barra de título.

## Configura las credenciales

El diálogo tiene cuatro campos:

| Campo | Predeterminado | Notas |
| --- | --- | --- |
| Endpoint | `s3.amazonaws.com` | Se respeta `http://`; en caso contrario se usa HTTPS |
| Región | `us-east-1` | Se envía tal como se escribe |
| Access Key ID | — | Obligatorio |
| Secret Access Key | — | Obligatorio, enmascarado, con un botón para mostrarlo |

Al confirmar se ejecuta el equivalente a:

```sql
INSTALL httpfs; LOAD httpfs;
CREATE OR REPLACE SECRET ducklocal_s3 (
  TYPE s3, PROVIDER config,
  KEY_ID '…', SECRET '…',
  REGION '…', ENDPOINT '…'
);
```

**Las credenciales duran solo la sesión.** No se escriben en disco y se borran cuando
abres o cambias de base de datos, así que tienes que volver a configurarlas después. No hay
otra forma de borrarlas que volver a configurar.

## Explora

Una vez configurado, aparece una raíz **S3** en la barra lateral. Su contenido se carga solo al
desplegarla: la raíz lista los buckets, y cada bucket o prefijo lista sus objetos. Los buckets y los prefijos
están ordenados, y los objetos muestran un tamaño legible. Usa el botón de actualizar para recargar
un nivel o reintentar tras un error.

El listado se limita a **1000 entradas por nivel**, incluso cuando la respuesta dice que
hay más disponibles. No hay paginación más profunda, ni cuadro de filtro por prefijo, ni
búsqueda: un bucket con más de mil objetos en un nivel parecerá
completo cuando no lo está.

## Consulta objetos

Al hacer clic en un objeto cuya clave tiene una extensión de archivo de datos, se rellena el editor activo
con:

```sql
SELECT *
FROM 's3://bucket/key'
LIMIT 100;
```

Eso es una consulta normal: la lectura pasa por `httpfs`, así que se aplica el comportamiento de
`read_parquet` / `read_csv_auto` de DuckDB, incluido el pushdown: los
filtros y la selección de columnas se empujan a la lectura del archivo. La consulta sustituye
lo que tuviera la pestaña activa.

Solo se pueden pulsar las claves reconocidas como archivos de datos. Las extensiones reconocidas
son las mismas que para los archivos locales; consulta [Fuentes de datos](data-sources.md#supported-file-formats).

## Limitaciones

- **La exploración es de solo lectura.** El explorador no tiene acciones de subir, descargar a un archivo,
  borrar, copiar ni crear buckets. Las consultas sí descargan datos remotos.
- **Sin tokens de sesión.** Nunca se envía la cabecera `X-Amz-Security-Token`, así que
  las credenciales temporales de STS no funcionarán: usa claves de larga duración, o un
  endpoint que acepte solo clave y secreto.
- **El estilo de endpoint es casi siempre automático.** Las URL de S3 pueden direccionar un bucket de dos
  formas: direccionamiento virtual-hosted o estilo de ruta. Se usa el direccionamiento virtual-hosted
  cuando el host contiene `amazonaws.com`, y el estilo de ruta en caso contrario. Para
  pasarelas autoalojadas esto suele ser lo que quieres; para una que necesite el
  otro estilo, no hay forma de forzarlo.
- Una región equivocada se reintenta una vez, usando la región que DuckDB devuelve. Si
  eso también falla, el error se muestra tal cual.
- Se necesita red: `INSTALL httpfs` descarga la extensión en el primer uso.
  La exploración envía solicitudes HTTP o HTTPS al endpoint configurado (`http://`
  selecciona HTTP; en caso contrario se usa HTTPS). Estas solicitudes envían metadatos
  como nombres de bucket y prefijos de clave, además de información de autenticación en cabeceras
  firmadas; la exploración no sube archivos de base de datos locales ni resultados de consultas.
  Las consultas sobre objetos remotos descargan datos a tu máquina mediante `httpfs`.

## Solución de problemas

| Síntoma | Causa probable |
| --- | --- |
| La exploración falla justo después de configurar | Región o endpoint incorrectos; revisa el mensaje que aparece en la barra lateral |
| Errores en un endpoint autoalojado | Estilo de direccionamiento incorrecto, o un endpoint que exige un token de sesión |
| Error de instalación de `httpfs` | Sin red, o un proxy que bloquea la descarga de la extensión |
| Las credenciales parecen olvidarse | Se abrió o se cambió de base de datos, lo que las borra por diseño |

Cuando DuckLocal se empaqueta como una app firmada, cargar la extensión `httpfs`
necesita el entitlement `com.apple.security.cs.disable-library-validation`; el
script de empaquetado incluido ya lo lleva.
