Vai al contenuto

S3 e httpfs ​

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:

CampoPredefinitoNote
Endpoints3.amazonaws.comhttp:// viene rispettato; altrimenti si usa HTTPS
Regionus-east-1Inviata 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.

Limiti ​

  • 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 ​

SintomoCausa probabile
La navigazione fallisce subito dopo la configurazioneRegion o endpoint sbagliati; controlla il messaggio mostrato nella barra laterale
Errori su un endpoint self-hostedStile di indirizzamento sbagliato, o un endpoint che richiede un token di sessione
Errore di installazione di httpfsNessuna 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à.

Pubblicato con licenza Apache-2.0.