Advanced Analytica Advanced Analytica: IBOM
← All connectors
Google Sheets logo

Source connector

Google Sheets

Set up Google Sheets as a source and move its data into your chosen destination.

Version 0.13.1 certified generally available

Google Sheets

Use this page to set up and reference the Google Sheets source connector.

:::info The Google Sheets source connector pulls data from one Google Sheets spreadsheet. You can sync every sheet within that spreadsheet. To sync multiple spreadsheets, use the Google Drive connector or configure multiple Google Sheets source connectors in your Airbyte instance. The connector doesn’t access other files in your Google Drive. :::

Prerequisites

  • Spreadsheet Link - The link to the Google spreadsheet you want to sync.
  • For Airbyte Cloud A Google Workspace user with access to the spreadsheet
  • For Airbyte Open Source:
    • A GCP project
    • The Google Sheets API enabled in your GCP project
    • A Service Account Key with access to the spreadsheet you want to replicate

Setup guide

You can authenticate the Google Sheets source connector with OAuth or Service Account Key Authentication.

Step 1: Set up Google Sheets

For Airbyte Cloud:

OAuth is strongly recommended because it simplifies setup and lets you authenticate directly from the Airbyte UI.

For Airbyte Open Source:

Service Account Key Authentication is recommended. Follow these steps to create a service account, generate a key and enable the Google Sheets API.

:::note If you prefer OAuth authentication with Airbyte Open Source, follow Google’s OAuth instructions to create an authentication app. Set the scopes to https://www.googleapis.com/auth/spreadsheets.readonly and https://www.googleapis.com/auth/drive.readonly. You’ll need your client ID, client secret and refresh token when setting up the connector. :::

Set up the service account key

Create a service account

  1. Open the Service Accounts page in your Google Cloud console.
  2. Select an existing project or create a new one.
  3. At the top of the page, click + Create service account.
  4. Enter a name and description for the service account, then click Create and Continue.
  5. Under Service account permissions, select the roles to grant the service account, then click Continue. The Viewer role is recommended.

Generate a key

  1. Go to the API Console/Credentials page and click the email address of the service account you created.
  2. In the Keys tab, click + Add key, then click Create new key.
  3. Select JSON as the Key type. This generates and downloads the JSON key file you’ll use for authentication. Click Continue.

Enable the Google Sheets API

  1. Go to the API Console/Library page.
  2. Confirm that you’ve selected the correct project at the top.
  3. Find and select the Google Sheets API.
  4. Click ENABLE.

If anyone with the link can view your spreadsheet, you don’t need to take further action. Otherwise, select the spreadsheet in Google Drive and click Share. Add the service account’s email address with Viewer permission. This address is the client_email value in your JSON key. See Google’s sharing instructions for details.

Set up the Google Sheets connector in Airbyte

For Airbyte Cloud:

  1. Open your Log into your Airbyte Cloud account.
  2. Click Sources, then click + New source.
  3. On the Set up the source page, select Google Sheets from the Source type dropdown.
  4. Enter a name for the Google Sheets connector.

For Airbyte Open Source:

  1. Open the Airbyte Open Source dashboard.
  2. Click Sources, then click + New source.
  3. On the Set up the source page, select Google Sheets from the Source type dropdown.
  4. Enter a name for the Google Sheets connector.
  1. Select your authentication method:
  • For Airbyte Cloud: (Recommended) Select Authenticate via Google (OAuth) from the Authentication dropdown, click Sign in with Google and complete the authentication workflow.
  • For Airbyte Open Source: (Recommended) Select Service Account Key Authentication from the dropdown and enter your Google Cloud service account key in JSON format:
  {
    "type": "service_account",
    "project_id": "YOUR_PROJECT_ID",
    "private_key_id": "YOUR_PRIVATE_KEY",
    ...
  }
  • To authenticate your Google account through OAuth, select Authenticate via Google (OAuth) from the dropdown. Enter your Google application’s client ID, client secret and refresh token.
6. For **Spreadsheet Link**, enter the link to the Google spreadsheet. To get it, open the Google spreadsheet you want to sync. Click **Share** in the top-right corner, then click **Copy Link**. 7. For **Batch Size**, enter an integer representing the batch size used to process a Google Sheet. The default value is 1000000. Batch size is the number of rows included in each request sent to the Google Sheets API. For example, the default value of 1000000 processes rows 2-1000002, followed by 1000003-2000003, and so on. Based on [Google Sheets API limits documentation](https://developers.google.com/sheets/api/limits), you can send up to 300 requests per minute. Each request must finish within 180 seconds or it returns a timeout error. Consider your network speed and the Google Sheet's column count when choosing a batch_size value. 8. (Optional) You can enable **Convert Column Names to SQL-Compliant Format**. This option converts column names into a standardised, SQL-friendly format. For example, it converts `Café Earnings 2022` to `cafe_earnings_2022`. Enable this option if your target destination uses SQL, such as Postgres or MySQL. The default is false. 9. Click **Set up source** and wait for the tests to finish.

Configuration options

Rename sheet and stream names

You can rename streams, including sheet and tab names, as they appear in Airbyte and your destination. This option helps when sheet names aren’t descriptive, contain special characters or need consistent naming across sources.

How stream renaming works

  • Provide a list of overrides. Each override specifies a source_stream_name, the exact sheet or tab name in your spreadsheet. It also specifies a custom_stream_name, the name shown in Airbyte and your destination.
  • If source_stream_name isn’t found in your spreadsheet, the connector ignores it and uses the default name.
  • This feature only changes stream names for sheets or tabs. It doesn’t change field or column names.
  • To rename fields or columns, use the Airbyte Mappings feature after creating your connection. See the Airbyte documentation for details on using Mappings.
  • Stream renaming happens before any other name conversion or sanitisation options.

Example

Your spreadsheet contains sheets named Sheet1, 2024 Q1 and Summary. You want to rename them to sales_data and q1_2024, while leaving Summary unchanged. Configure:

[
  { "source_stream_name": "Sheet1", "custom_stream_name": "sales_data" },
  { "source_stream_name": "2024 Q1", "custom_stream_name": "q1_2024" }
]

After discovery, Airbyte names your streams sales_data, q1_2024 and Summary.

Configure stream names

  • In the Airbyte UI, add your overrides to the Stream Name Overrides field as an array of objects.
  • Leave this field blank if you don’t want to rename any streams.
  • After adding or changing a stream name override, refresh your schema in Airbyte to see the new stream names take effect.
  • Overridden streams will default to Sync Mode: Full Refresh (Append), which does not support primary keys. If you want to use primary keys and deduplication, update the sync mode to “Full Refresh | Overwrite + Deduped” in your connection settings.

Google Sheets connector column names

The Google Sheets connector lets you convert spreadsheet column names into a SQL-compliant format. Configure these settings in the Airbyte UI when setting up the connector.


1. Convert Column Names to SQL-Compliant Format

  • Description: When enabled, this setting converts column names into a format compatible with SQL databases. For example, it uses lowercase and replaces spaces with underscores. You must enable this primary toggle before applying any column name conversion.
  • Default: Off

2. Additional Conversion Options

Use the following options to refine column name conversion. They only apply when “Convert Column Names to SQL-Compliant Format” is enabled.

  • Remove Leading and Trailing Underscores

    • Description: Removes leading and trailing underscores from column names. If “Allow Leading Numbers” is disabled, leading underscores remain on names starting with a number.
    • Example:
      • Input: " EXAMPLE Domain "
      • Output: "example_domain"
    • Default: Off
  • Combine Number-Word Pairs

    • Description: Combines adjacent numbers and words into one token without separators.
    • Example:
      • Input: "50th Percentile"
      • Output: "50th_percentile" (if “Allow Leading Numbers” is enabled)
      • Output: "_50th_percentile" (if “Allow Leading Numbers” is disabled)
    • Default: Off
  • Remove All Special Characters

    • Description: Removes all special characters, including *, ?, !, $, %, ( and ), from column names.
    • Example:
      • Input: "Example ID*"
      • Output: "example_id"
    • Default: Off
  • Combine Letter-Number Pairs

    • Description: Combines adjacent letters and numbers into one token without separators.
    • Example:
      • Input: "Q3 2023"
      • Output: "q3_2023"
    • Default: Off
  • Allow Leading Numbers

    • Description: Allows column names to start with numbers. If disabled, column names beginning with a number receive a leading underscore.
    • Example:
      • Input: "50th Percentile"
      • Output: "50_th_percentile" (if enabled)
      • Output: "_50_th_percentile" (if disabled)
    • Default: Off

Conversion details

  • All converted column names use lowercase.
  • Multiple spaces or special characters are collapsed or removed, rather than replaced with multiple underscores.
  • Only single underscores separate tokens.
  • The result is always SQL-friendly and readable.

Use these options to match column name conversions to your database requirements. Adjust them as needed in the Airbyte UI when configuring the Google Sheets connector.


Header deduplication

The Google Sheets connector automatically creates unique field names for duplicate column headers by appending each cell position. This ensures every column syncs correctly, even when your spreadsheet contains duplicate header names.

How duplicate headers work

  • When the connector detects duplicate headers, it appends _<cell_position> to each duplicated header name.
  • The cell position follows the standard Google Sheet naming convention, such as A1, B1 and C1.
  • This creates unique field names while preserving the original header text.

Example

Your spreadsheet has a header named stats in columns C and Q, at positions C1 and Q1. The connector creates two distinct fields:

  • stats_C1 for the column at position C1
  • stats_Q1 for the column at position Q1

This ensures data from both columns is captured and synced to your destination. Each field clearly identifies the column it represents.


Supported sync modes

The Google Sheets source connector supports these sync modes:

Supported streams

Each sheet in the selected spreadsheet syncs as a separate stream. Each selected column in the sheet syncs as a string field.

Airbyte can only replicate Grid sheets.

Data type mapping

Integration TypeAirbyte TypeNotes
any typestring

Limitations and troubleshooting

Expand to see details about Google Sheets connector limitations and troubleshooting.

Connector limitations

Rate limits

The Google API rate limits are:

  • 300 read requests per minute per project
  • 60 requests per minute per user per project

Airbyte batches API requests to pull data efficiently while respecting these rate limits. For high transfer speeds, Airbyte recommends using each user or service account for no more than 3 Google Sheets source connector instances.

Troubleshooting

  • Invalid Spreadsheet Link: Enter a bare spreadsheet ID. An optional trailing / is accepted. You can also enter a full spreadsheet URL. Supported forms include https://docs.google.com/spreadsheets/d/<id>/..., https://docs.google.com/spreadsheets/u/0/d/<id>/..., and https://sheets.googleapis.com/v4/spreadsheets/<id>/.... Existing HTTPS links remain supported when Airbyte can extract the ID. Airbyte checks access through the Google Sheets API.
  • Spreadsheet not found or access denied: Check that the spreadsheet exists and the link is correct. Share the spreadsheet with the service account’s client_email from its JSON key. Alternatively, share it with the Google user authorised for the source.
  • Google API disabled: Enable both the Google Sheets API and Google Drive API in the Google Cloud project linked to your credentials. Allow a few minutes for the change to take effect, then retry.
  • Authentication failed: Re-authenticate the source if OAuth authorisation has expired or been revoked. For service accounts, provide the complete JSON key downloaded from Google Cloud. Create a new key if the existing key is invalid or revoked.
  • Airbyte won’t delete the destination table if your sheet is deleted or completely empty, with no header rows. In this case, the sync logs will say the sheet was skipped while syncing the full spreadsheet.
  • Connector setup will fail unless the spreadsheet is a Google Sheets file. Setup could fail if the file was saved or imported as another file type.
  • Google is probably struggling to serve the spreadsheet if connection checks or schema discovery fail with Failed to find output files from connector within timeout of 9 minute(s) after repeated Rate limit exceeded (HTTP 503) retries. The connector records every retry as Rate limit exceeded. However, 503 means the Sheets API is unavailable or considers the request or spreadsheet too complex. Therefore, the API rate limits above usually aren’t the cause. During checks and discovery, the connector reads every sheet’s header row. This includes hidden sheets and sheets you don’t sync. It retries each 503 up to five times, with increasingly long waits. Across all requests, these waits can exceed the 9-minute limit. If one request exhausts its retries first, you’ll see Exhausted available request attempts instead. Airbyte checks the source before sync attempts. Therefore, syncs can fail for days, then succeed without any Airbyte-side change. To reduce the load, follow Google’s suggestions for 503 errors. For example:
    • Limit spreadsheet access to people who need it. For example, remove inactive accounts from its sharing settings.
    • Limit IMPORTRANGE, QUERY, and other complex formulas. Use volatile functions like NOW, TODAY, and RAND sparingly.
    • Delete sheets you don’t need. Alternatively, move the sheets you sync into a separate, smaller spreadsheet. Hiding a sheet doesn’t help because the connector still reads it. Paste plain values into the new spreadsheet instead of using IMPORTRANGE, which increases formula load.
  • See common troubleshooting issues for the Google Sheets source connector on the Airbyte Forum.

IP allow list

If you use Airbyte Cloud and restrict access to specific IPs, add the Airbyte Cloud IP addresses to your allow list.

Changelog

Expand to review
VersionDatePull RequestSubject
0.13.12026-11-1091589Update dependencies
0.13.02026-10-3090237Declare the sections of the stepped setup form (Connect spreadsheet, Review & set up) in the spec; the CDK’s section-aware CHECK runs the declared check for the first section
0.12.472026-10-3090255Validate spreadsheet links and explain authentication, API enablement, and access failures in connection checks
0.12.462026-11-0390596Update dependencies
0.12.452026-10-2789945Update dependencies
0.12.442026-10-2089239Update dependencies
0.12.432026-10-1689046Show Authentication before Spreadsheet Link in the setup form
0.12.422026-10-1388639Update dependencies
0.12.412026-10-0687878Update dependencies
0.12.402026-09-2987193Update dependencies
0.12.392026-09-2286655Update dependencies
0.12.382026-09-1586081Update dependencies
0.12.372026-09-0885517Update dependencies
0.12.362026-08-1883961Update dependencies
0.12.352026-07-2882977Update dependencies
0.12.342026-07-2182453Update dependencies
0.12.332026-07-1481855Update dependencies
0.12.322026-06-3081092Update dependencies
0.12.312026-06-2380490Update dependencies
0.12.302026-06-1679895Update dependencies
0.12.292026-06-0978741Update dependencies
0.12.282026-06-0379121Promoted release candidate to GA
0.12.28-rc.12026-05-2978519Set default_concurrency to 2, add num_workers spec field, add HTTP API budget
0.12.27-rc.12026-05-2678437Set default_concurrency to 4 for concurrency tuning
0.12.262026-05-2678443Update dependencies
0.12.252026-04-2877273Update dependencies
0.12.242026-04-2176629Update dependencies
0.12.232026-04-0275578Add oauth_connector_input_specification with granular scopes
0.12.232026-03-3075578Add oauth_connector_input_specification with granular scopes
0.12.222026-03-1774660Update dependencies
0.12.212026-02-2473968Update dependencies
0.12.202026-02-1073078Update dependencies
0.12.192026-02-0372644Update dependencies
0.12.182026-01-2071904Update dependencies
0.12.172026-01-1471703Update dependencies
0.12.162025-12-1870510Update dependencies
0.12.152025-12-0369848Add optional flag to read columns with empty headers
0.12.142025-11-2570029Update dependencies
0.12.132025-11-1869396Update dependencies
0.12.122025-10-2968759Update dependencies
0.12.112025-10-2168254Update dependencies
0.12.102025-10-1667531Add error handling for unexpected data in sheets causing 500 responses.
0.12.92025-10-1467876Update dependencies
0.12.82025-10-0767395Update dependencies
0.12.72025-09-3065383Update dependencies
0.12.62025-09-1666012Update to CDK v7
0.12.52025-08-0964633Update dependencies
0.12.42025-08-0264179Update dependencies
0.12.32025-07-2663822Update dependencies
0.12.22025-07-2263334Feature: Deduplicate Headers
0.12.12025-07-1955490Update dependencies
0.12.02025-07-1563305Promoting release candidate 0.12.0-rc.2 to a main version.
0.12.0-rc.22025-07-1162931Fix: handle empty propeties_to_match in SchmemaMatchingExtractor
0.12.0-rc.12025-07-0262456Feature: migrate connector to manifest-only format
0.11.02025-06-1161489Feature: Added Streeam Name Override Options
0.10.02025-06-0960836Feature: Added additional sanitization flags when using Convert Column Names to SQL-Compliant Format (names_conversion)
0.9.62025-05-2260874Use custom backoff policy on 429 errors for single sheets
0.9.52025-05-1360259Fix whitespaces used for column names when enabling names_conversion
0.9.42025-03-0154989Update dependencies
0.9.32025-02-2254434Update dependencies
0.9.22025-02-1553720Update dependencies
0.9.12025-02-0851696Update dependencies
0.9.02025-02-0453154Promoting release candidate 0.9.0-rc.3 to a main version.
0.9.0-rc.32025-01-3152682Fix stream name typing
0.9.0-rc.22025-01-3152671Fix sheet id encoding
0.9.0-rc.12025-01-3050843Migrate to low-code
0.8.52025-01-1144270Starting with this version, the Docker image is now rootless. Please note that this and future versions will not be compatible with Airbyte versions earlier than 0.64
0.8.42024-12-0948835Implementing integration tests
0.7.42024-09-0945108Google Sheets API errors now cause syncs to fail
0.7.32024-08-1243921Update dependencies
0.7.22024-08-1043544Update dependencies
0.7.12024-08-0343290Update dependencies
0.7.02024-08-0242975Migrate to CDK v4.3.0
0.6.32024-07-2742826Update dependencies
0.6.22024-07-2241993Avoid syncs with rate limits being considered successful
0.6.12024-07-2042376Update dependencies
0.6.02024-07-1742071Migrate to CDK v3.9.0
0.5.112024-07-1341527Update dependencies
0.5.102024-07-0941273Update dependencies
0.5.92024-07-0641005Update dependencies
0.5.82024-06-2840587Replaced deprecated AirbyteLogger with logging.Logger
0.5.72024-06-2540560Catch an auth error during discover and raise a config error
0.5.62024-06-2640533Update dependencies
0.5.52024-06-2540505Update dependencies
0.5.42024-06-2240129Update dependencies
0.5.32024-06-0639225[autopull] Upgrade base image to v1.2.2
0.5.22024-06-0238851Emit state message at least once per stream
0.5.12024-04-1135404Add row_batch_size parameter more granular control read records
0.5.02024-03-2636515Resolve poetry dependency conflict, add record counts to state messages
0.4.02024-03-1936267Pin airbyte-cdk version to ^0
0.3.172024-02-2935722Add logic to emit stream statuses
0.3.162024-02-1235136Fix license in pyproject.toml.
0.3.152024-02-0734944Manage dependencies with Poetry.
0.3.142024-01-2334437Fix header cells filtering
0.3.132024-01-1934376Fix names conversion
0.3.122023-12-1433414Prepare for airbyte-lib
0.3.112023-10-1931599Base image migration: remove Dockerfile and use the python-connector-base image
0.3.102023-09-2730487Fix bug causing rows to be skipped when batch size increased due to rate limits.
0.3.92023-09-2530749Performance testing - include socat binary in docker image
0.3.82023-09-2530747Performance testing - include socat binary in docker image
0.3.72023-08-2529826Remove row batch size from spec, add auto increase this value when rate limits
0.3.62023-08-1629491Update to latest CDK
0.3.52023-08-1629427Add stop reading in case of 429 error
0.3.42023-05-1529453Update spec descriptions
0.3.32023-08-1029327Add user-friendly error message for 404 and 403 error while discover
0.3.22023-08-0929246Add checking while reading to skip modified sheets
0.3.12023-07-0628033Fixed several reported vulnerabilities (25 total), CVE-2022-37434, CVE-2022-42898
0.3.02023-06-2627738License Update: Elv2
0.2.392023-05-3126833Remove authSpecification in favour of advancedAuth in specification
0.2.382023-05-1626097Refactor config error
0.2.372023-02-2123292Skip non grid sheets.
0.2.362023-02-2123272Handle empty sheets gracefully.
0.2.352023-02-2323057Slugify column names
0.2.342023-02-1523071Change min spreadsheet id size to 20 symbols
0.2.332023-02-1323278Handle authentication errors
0.2.322023-02-1322884Do not consume http spreadsheets.
0.2.312022-10-0919574Revert ‘Add row_id to rows and use as primary key’
0.2.302022-10-0919215Add row_id to rows and use as primary key
0.2.212022-10-0415591Clean instantiation of AirbyteStream
0.2.202022-10-1017766Fix null pointer exception when parsing the spreadsheet id.
0.2.192022-09-2917410Use latest CDK.
0.2.182022-09-2817326Migrate to per-stream states.
0.2.172022-08-0315107Expose Row Batch Size in Connector Specification
0.2.162022-07-0713729Improve configuration field description
0.2.152022-06-0213446Retry requests resulting in a server error
0.2.132022-05-0612685Update CDK to v0.1.56 to emit an AirbyeTraceMessage on uncaught exceptions
0.2.122022-04-2012230Update connector to use a spec.yaml
0.2.112022-04-1311977Replace leftover print statement with airbyte logger
0.2.102022-03-2511404Allow using Spreadsheet Link/URL instead of Spreadsheet ID
0.2.92022-01-259208Update title and descriptions
0.2.72021-09-278470Migrate to the CDK
0.2.62021-09-276354Support connecting via Oauth webflow
0.2.52021-09-125972Fix full_refresh test by adding supported_sync_modes to Stream initialization
0.2.42021-08-055233Fix error during listing sheets with diagram only
0.2.32021-06-093973Add AIRBYTE_ENTRYPOINT for Kubernetes support
0.2.22021-04-202994Formatting spec
0.2.12021-04-032726Fix base connector versioning
0.2.02021-03-092238Protocol allows future/unknown properties
0.1.72021-01-211762Fix issue large spreadsheet
0.1.62021-01-271668Adopt connector best practices
0.1.52020-12-301438Implement backoff
0.1.42020-11-301046Add connectors using an index YAML file
Advanced Analytica

Most businesses are sitting on information they can’t use at speed. The people who hold it are busy, and when they leave, the knowledge goes with them. The documents are static, and the processes around them weren’t designed for AI.

Advanced Analytica works with these businesses to turn that information into structured data assets. Once they're integrated, AI systems can govern it, and the business can use it. We bring in the strategy, the specification and the AI skills to rework how the business operates.

MOVE FAST. STAY SAFE.