# S3 e httpfs

> Interroga Amazon S3 e storage compatibili con S3 da DuckLocal con httpfs di DuckDB: configura le credenziali, sfoglia i bucket ed esegui SQL sui file remoti.

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

DuckLocal può leggere oggetti da S3 e da storage compatibili con S3 tramite
l'estensione `httpfs` di DuckDB. Configurala dal pulsante **S3** nella barra del
titolo.

## Configura le credenziali

La finestra di dialogo ha quattro campi:

| Campo | Predefinito | Note |
| --- | --- | --- |
| Endpoint | `s3.amazonaws.com` | `http://` viene rispettato; altrimenti si usa HTTPS |
| Region | `us-east-1` | Inviata così come è scritta |
| Access Key ID | — | Obbligatorio |
| Secret Access Key | — | Obbligatoria, mascherata, con un interruttore per mostrarla |

Confermando viene eseguito l'equivalente di:

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

**Le credenziali valgono solo per la sessione.** Non vengono scritte su disco e
vengono cancellate quando apri o cambi database, quindi dopo devi riconfigurarle.
Non c'è un altro modo per cancellarle se non riconfigurarle.

## Sfoglia

Una volta configurato, nella barra laterale compare una radice **S3**. I suoi
contenuti si caricano solo quando la espandi: la radice elenca i bucket, e ogni
bucket o prefisso elenca i suoi oggetti. Bucket e prefissi sono ordinati, e gli
oggetti mostrano una dimensione leggibile. Usa il pulsante di aggiornamento per
ricaricare un livello o riprovare dopo un errore.

L'elenco si ferma a **1.000 voci per livello**, anche quando la risposta dichiara
che ce ne sono altre. Non c'è paginazione più profonda, né campo di filtro per
prefisso, né ricerca — un bucket con più di mille oggetti allo stesso livello
apparirà completo anche quando non lo è.

## Interroga gli oggetti

Facendo clic su un oggetto la cui chiave ha l'estensione di un file di dati,
l'editor attivo si riempie con:

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

È una query normale: la lettura passa da `httpfs`, quindi vale il comportamento
di `read_parquet` / `read_csv_auto` di DuckDB, compreso il pushdown — filtri e
selezione delle colonne vengono spinti nella lettura del file. La query
sostituisce quello che conteneva la scheda attiva.

Solo le chiavi riconosciute come file di dati sono cliccabili. Le estensioni
riconosciute sono le stesse dei file locali; vedi [Sorgenti di
dati](data-sources.md#supported-file-formats).

## Limiti {#limitations}

- **La navigazione è in sola lettura.** Il browser S3 non offre azioni di
  caricamento, download su file, eliminazione, copia o creazione di bucket. Le
  query scaricano comunque i dati remoti.
- **Nessun token di sessione.** L'intestazione `X-Amz-Security-Token` non viene
  mai inviata, quindi le credenziali temporanee STS non funzionano — usa chiavi
  di lunga durata, oppure un endpoint che accetta solo chiave e secret.
- **Lo stile dell'endpoint è quasi sempre automatico.** Gli URL S3 possono
  indirizzare un bucket in due modi: indirizzamento virtual-hosted o path style.
  L'indirizzamento virtual-hosted viene usato quando l'host contiene
  `amazonaws.com`, altrimenti si usa il path style. Per i gateway self-hosted di
  solito è quello che vuoi; per uno che richiede l'altro stile non c'è modo di
  imporlo.
- Una region sbagliata viene ritentata una volta, usando la region che DuckDB
  riporta. Se anche quel tentativo fallisce, l'errore viene mostrato così com'è.
- La rete è necessaria: `INSTALL httpfs` scarica l'estensione al primo uso. La
  navigazione invia richieste HTTP o HTTPS all'endpoint configurato (`http://`
  seleziona HTTP; altrimenti si usa HTTPS). Queste richieste inviano metadati
  come nomi di bucket e prefissi di chiavi, più informazioni di autenticazione
  in intestazioni firmate; la navigazione non carica file di database locali né
  risultati di query. Le query sugli oggetti remoti scaricano i dati sulla tua
  macchina tramite `httpfs`.

## Risoluzione dei problemi

| Sintomo | Causa probabile |
| --- | --- |
| La navigazione fallisce subito dopo la configurazione | Region o endpoint sbagliati; controlla il messaggio mostrato nella barra laterale |
| Errori su un endpoint self-hosted | Stile di indirizzamento sbagliato, o un endpoint che richiede un token di sessione |
| Errore di installazione di `httpfs` | Nessuna rete, o un proxy che blocca il download dell'estensione |
| Le credenziali sembrano dimenticate | È stato aperto o cambiato un database, che per scelta le cancella |

Quando DuckLocal è pacchettizzato come app firmata, caricare l'estensione `httpfs`
richiede l'entitlement `com.apple.security.cs.disable-library-validation`; lo
script di packaging distribuito lo include già.
