gdrive

Dateien in Google Drive direkt über ein gdrive://-Dateisystem abfragen

Maintainer: jrosskopf

Installation und Laden

INSTALL gdrive FROM community;
LOAD gdrive;

Beispiel

-- Unattended: a service account. To WRITE you need a Shared Drive --
-- service accounts have no personal Drive storage quota and get
-- 403 storageQuotaExceeded anywhere else. Reading a shared folder is fine.
--
-- DRIVE_ID is a SHARED DRIVE id; ROOT_FOLDER_ID is a FOLDER id. They are
-- not interchangeable: passing a folder id as DRIVE_ID fails with
-- "Shared drive not found". Use whichever matches what was shared.
CREATE SECRET gdrive (
    TYPE gdrive,
    PROVIDER service_account,
    KEY_FILE '/etc/creds/sa.json',
    DRIVE_ID '0ABcDeFgHiJkLmNoPQ',       -- or ROOT_FOLDER_ID '1a2b3c...'
    DRIVE_SCOPE 'https://www.googleapis.com/auth/drive.readonly'
);

-- Query a file by path. Drive has no path addressing, so each segment
-- costs a lookup; results are cached per secret.
SELECT count(*) FROM 'gdrive://Finance/2026/actuals.parquet';

-- Address a file by id instead: zero resolution calls. Prefer this in
-- generated or stored queries.
SELECT * FROM read_csv('gdrive://id:1a2b3cDeFgHiJkLmNoPQrStUvWxYz');

-- Glob a folder.
SELECT * FROM read_parquet('gdrive://exports/parts/*.parquet');

-- A native Google Sheet is queryable with no manual export: it has no
-- byte stream, so it is served through Drive's CSV export.
SELECT * FROM read_csv('gdrive://Finance/Budget');

-- Write a whole file. Writes are sequential; Drive cannot write at a
-- byte offset, so positional writes raise an error rather than corrupt.
COPY (SELECT * FROM t) TO 'gdrive://reports/out.parquet' (FORMAT parquet);

-- Inspect API calls and cache hits for the session.
SELECT * FROM gdrive_stats();

Über gdrive

Registriert ein Dateisystem gdrive://, sodass jeder DuckDB-Pfadausdruck eine Datei in Google Drive ohne Download- oder Kopierschritt adressieren kann. Weil DuckDB den Dateizugriff über sein virtuelles Dateisystem dispatcht, erbt alles darauf Aufbauende das Schema: read_parquet, read_csv, COPY, glob und Tabellenformate wie DuckLake — das Anhängen eines DuckLake, dessen DATA_PATH auf Drive liegt, funktioniert und wird live getestet.

ATTACH einer DuckDB-Datenbankdatei auf gdrive:// wird NICHT unterstützt. DuckDB öffnet Datenbankdateien über einen anderen Pfad, der das virtuelle Dateisystem nicht konsultiert; der Versuch schlägt daher sofort fehl, statt nur halb zu funktionieren.

Das ist Google Drive, nicht Google Cloud Storage — ein anderes Produkt mit anderer API und anderem Zugriffsmodell. Für gs://-Buckets verwenden Sie die Erweiterung gcs.

Lesezugriffe sind bereichsweise, sodass ein Parquet-Scan Footer und Spaltenchunks statt ganzer Dateien holt. Die Pfadauflösung wird pro Secret und pro Drive gecacht, weil Drive keine Pfadressierung hat und jedes Segment sonst einen API-Aufruf kostet.

Zwei Verhaltensweisen sind bewusst streng. Drive erlaubt zwei Dateien mit demselben Namen in einem Ordner, daher ist ein Pfad kein eindeutiger Identifikator: statt eine auszuwählen und Ergebnisse von der internen Reihenfolge von Drive abhängig zu machen, ist Mehrdeutigkeit ein Fehler, der beide Datei-IDs nennt. Und Drive kann nicht an einem Byte-Offset schreiben, daher lösen positionale Schreibvorgänge einen Fehler aus, statt eine Datei still zu beschädigen.

Drive ist deutlich langsamer als Objektspeicher und erzwingt benutzerbezogene API-Kontingente, die Objektspeicher nicht hat. Ein Bereichslese kostet ~1,3 s unabhängig davon, wie wenige Bytes angefordert werden, gegenüber ~1 ms bei S3/GCS. Verwenden Sie dies, wenn Drive das System of Record für Daten ist, die Sie abfragen möchten, und Sie lieber keine zweite Kopie pflegen — nicht als Ersatz für Objektspeicher unter hoher Last. Auf einer Workstation sind Google Drive for desktop plus gewöhnliche lokale Pfade einfacher und schneller.

Hinzugefügte Funktionen

Überladene Funktionen

Diese Erweiterung fügt keine Funktionsüberladungen hinzu.

Hinzugefügte Typen

Diese Erweiterung fügt keine Typen hinzu.

Hinzugefügte Einstellungen