Skip to main content
Google Drive is Google’s cloud storage and collaboration platform. This connector supports two operating modes:
  • Records mode (default): Reads Microsoft Excel files (.xlsx and .xls) and CSV files (.csv and .tsv) from Google Drive and turns them into data streams, so you can load tabular data from Drive, including files in Shared Drives, into Nekt.
  • Unstructured mode: Downloads any file type (PDFs, images, XML, etc.) from a Google Drive folder and uploads them to a Nekt volume, emitting one metadata record per file. Useful for materializing a catalog of unstructured assets into your warehouse.
CSV files are read as a stream, without being held in memory, so file size is not a limitation — a multi-gigabyte export loads the same way a small one does. For native Google Sheets (not Excel or CSV files), use the Google Sheets connector instead.

​
Records mode (Excel and CSV extraction)

​
Configuring Google Drive as a Source

In the Sources tab, click on the Add source button on the top right, then select Google Drive from the list of connectors. Click Next and you’ll be prompted to add your access.

​
1. Add account access

You need to authorize Nekt to read files from Google Drive and, optionally, pick the file or folder to extract from.
  • Authentication: Use the Google Authorization flow. Sign in with a Google account that has access to the Drive (and, if applicable, the Shared Drive) where your files are stored. The connector uses OAuth and stores a refresh token so it can keep accessing Drive without re-authorizing.
  • File or folder: Use the in-app picker to select the file or folder; the connector will resolve the correct ID.
Under Advanced Settings you can optionally set:
  • CSV delimiter: The character separating fields in your CSV files, such as , or ;. Leave it empty to have the connector detect it per file — set it only when a file is being read wrong, since one value applies to every CSV in the source.
Once you’re done, click Next.

​
2. Select streams

The connector discovers streams dynamically from the file or folder you selected, and how a file maps to streams depends on its type:
  • Excel files — one stream per sheet: Each worksheet in each Excel file becomes one stream, named {file_name}_{sheet_name} (lowercase, special characters replaced with underscores), e.g. monthly_sales_january.
  • CSV files — one stream per file: A CSV has no sheets, so each file becomes a single stream named after the file, e.g. base_clientes.
  • Skip rows: Number of rows to skip from the top before treating the next row as the header. Use this when the file has title or empty rows above the data. Works for both Excel sheets and CSV files. If headers are on the first row, leave this at 0.
  • Range (Excel only): A sheet range (e.g. A:D or A1:E100) so only part of the sheet is read. If not set, the full sheet is used.
Files that are neither spreadsheets nor CSVs are skipped, and the run log names them so you can tell the difference between “ignored” and “missing”.
When per-stream settings are provided, only the streams you configure use their custom range or skip rows; the others read the full sheet or file with no skip.
Choose which streams you want to sync. You can select all or a subset.
Tip: You can search for a stream by typing its name.
Select the streams and click Next.

​
3. Configure data streams

Customize how you want the data to appear in your catalog: layer, folder, table names, and sync type.
  • Layer: Choose the layer where the new tables will live.
  • Folder: Optionally create or select a folder inside the layer to group tables from this source.
  • Table name: A default name is suggested per stream; you can change it or add a prefix for all tables at once.
  • Sync type: Only FULL_TABLE is supported. Each run re-reads the selected files from scratch, so your tables always reflect the current content. There is no incremental mode in Records mode: a large file is read in full on every run, not just the first.
Click Next when done.

​
4. Configure data source

Add a short description of the source (e.g. what data it brings or which team owns it), and define your Trigger (how often the extraction runs). Optionally:
  • Configure Delta Log Retention for how long old table states are kept. See Resource control.
  • Schedule an Additional Full Sync if you want periodic full refreshes in addition to your normal schedule.
Click Next to finish.

​
5. Check your new source

Your new source appears on the Sources page. Trigger a run manually if needed; after a successful run, the tables will appear in your Catalog.
You need at least one successful source run to see the tables in your Catalog.

​
Unstructured mode (raw file extraction)

Unstructured mode downloads files from a Google Drive folder, uploads them to a Nekt volume, and emits one metadata record per file through a google_drive_files stream. This is useful for extracting PDFs, images, XML files, or any other file type that doesn’t fit a tabular format.

​
Configuring unstructured mode

In the Sources tab, click Add source and select Google Drive from the list of connectors.

​
1. Add account access

Same as Records mode: authorize Nekt via Google Authorization and select the folder containing your files.

​
2. Select mode

Under Advanced Settings, set the Mode to Unstructured.

​
3. Configure volume

When Unstructured mode is selected, the Attachments Volume setting becomes available.
  • Attachments Volume: Use the in-app volume picker to directly select the destination Nekt volume where you want the downloaded Google Drive files to be uploaded. This is required when operating in Unstructured mode.

​
4. Optional: filter files

You can optionally set a File name filter (under Advanced Settings) to only process files matching a wildcard pattern (e.g. *.pdf, invoice_*). Files that don’t match the pattern are skipped.

​
5. Configure and finish

Complete the remaining steps (data source description, trigger schedule) as with any other source.

​
How it works

  1. The connector lists all files in the selected Google Drive folder (with pagination for large folders).
  2. If a File name filter is set, only matching files are processed.
  3. Each file is downloaded and uploaded to the configured Nekt volume.
  4. On subsequent runs, only files modified after the last extraction are processed (incremental replication via modified_at).

​
Streams and Fields

Each selected Excel file contributes one stream per sheet (tab). The stream name is built from the file name (without extension) and the sheet name, sanitized (e.g. revenue_2024_q1).Schema: Column names and types are inferred from the first 1,000 rows of the sheet (after applying skip rows and any range, if configured). Column headers in the file are slugified: spaces and special characters become underscores, and names are lowercased (e.g. Revenue (USD) → revenue_usd).Field types: The connector maps Excel/pandas types to schema types:Data behavior:
  • Rows where every cell is empty are dropped.
  • Excel blanks become null in the output.
  • Records are cleansed (e.g. invalid values normalized) before being written.
Large files: Sheets are read in memory and emitted in chunks (e.g. 5,000 rows per chunk) for efficiency. The file is only parsed once per stream.
Each selected CSV file becomes one stream, named after the file without its extension (e.g. base_clientes.csv → base_clientes).Schema: Column names come from the header row, slugified the same way as Excel headers (lowercase, underscores). Blank header cells are dropped; repeated names are de-duplicated with a numeric suffix.Field types: every column is typed as String. This is deliberate. A CSV carries no type information, and the files are often too large to inspect in full, so a type guessed from the first rows could be contradicted millions of rows later — silently turning an unexpected value into null. Emitting the raw text keeps the data intact; cast the columns you need in a downstream transformation.Encoding: Detected automatically from the start of each file. UTF-8 (with or without a byte-order mark) is used when the file decodes as UTF-8; otherwise the connector falls back to latin-1, which covers the accented characters produced by Brazilian and European spreadsheet exports.Separator: Detected automatically per file, from ,, ;, tab and |. Detection compares how consistently each candidate splits the rows, so a semicolon-separated file whose fields contain commas (e.g. Rua São João, 100) is read correctly. Set CSV delimiter in the connector settings to override detection.Data behavior:
  • Quoted fields may contain the separator, and may span several lines; both are preserved as a single value.
  • Rows with more fields than the header declares have the extra values dropped; rows with fewer get null for the missing columns.
  • Null bytes are stripped, since they cannot be parsed as CSV.
Large files: The file is read as a stream, one line at a time, and never buffered whole or written to disk. Memory use is constant regardless of file size, so a multi-gigabyte CSV is supported — expect the run to take proportionally longer.
The unstructured mode emits a single stream google_drive_files with one metadata record per uploaded file.

​
Implementation notes

​
Authentication

  • Google OAuth: The connector uses Google OAuth (client ID, client secret, refresh token) to obtain access tokens for the Google Drive API. Credentials are stored securely.
  • Scopes: The connected account must have read access to the chosen file or folder (and to the Shared Drive, if applicable).
  • Shared Drives: Supported via supportsAllDrives and includeItemsFromAllDrives when resolving the item and listing folder contents.

​
File and folder behavior

  • Records mode: Excel (.xlsx, .xls) and CSV (.csv, .tsv) files are processed. Other files in a selected folder are skipped, and the run log lists them by name. If the selection points to a single file, it must be one of those types. If it points to a folder, the connector lists its full contents (paginated, including from Shared Drives, excluding items in the trash), then discovers one stream per sheet for each Excel file and one stream per CSV file. File type is determined by extension first and MIME type second, because Drive records the MIME type of an uploaded CSV inconsistently.
  • Unstructured mode: Any file type is accepted. The connector lists all files in the folder (with pagination), optionally filters by search_pattern, downloads each file, uploads it to a Nekt volume via the SDK’s Volume Attachment system, and emits one metadata record per file. Google Workspace files (Docs, Sheets, Slides) that cannot be downloaded as binary are skipped.

​
Schema and per-stream settings

  • Discovery (Excel): Schema is built from the first 1,000 rows, after skip rows and any optional range. If your header row is not the first row, set Skip rows so the correct row is used as the header.
  • Discovery (CSV): Only the first few hundred kilobytes of the file are read, to detect the encoding, the separator and the header row. The rest of the file is never touched during discovery, so adding a very large CSV does not make setup slow.
  • Per-stream settings: Optional, keyed by stream name (e.g. my_file_my_sheet or base_clientes). Each can set skip rows, and for Excel a range. Streams without settings read the full sheet or file with no skip.
  • Column names: All column names are slugified (lowercase, underscores) for consistency and compatibility with the catalog.
  • Column types: Excel types are inferred from the data; CSV columns are always String — see the CSV stream notes above for why.

​
Sync type

  • Records mode (FULL_TABLE): There is no replication key. Every run re-reads the file(s) in full, so sync type is effectively full table — including for large CSVs, which are re-read on every run rather than only when they change.
  • Unstructured mode (INCREMENTAL): Uses modified_at as the replication key. Only files modified after the last successful run are downloaded and uploaded.

​
Best practices

  1. Use a dedicated service account or folder: Prefer a Google account or folder used only for this integration, so permissions are clear and revocable.
  2. Set skip rows when needed: If the first rows of the file are empty or contain titles, set Skip rows so the header row is detected correctly.
  3. Use range for large sheets: If only a subset of columns or rows is needed, set Range to reduce payload and improve performance.
  4. Pick only needed streams: Selecting only the sheets and files you need keeps runs faster and the catalog simpler.
  5. Schedule according to updates: Run the source as often as your files change (e.g. daily or weekly). Because every run re-reads the files in full, scheduling a very large CSV more often than it actually changes costs time without adding data.
  6. Check the first run’s log for CSVs: The log reports the columns, separator and encoding detected for each CSV file. Confirming those once is the quickest way to catch a file that needs an explicit CSV delimiter or a Skip rows value.

​
Troubleshooting

​
Skills for agents

Download Google Drive skills file

Google Drive connector documentation as plain markdown, for use in AI agent contexts.