Skip to main content

Version: Next

GoogleSheets

GoogleSheets source connector

Description

Used to read data from Google Sheets through the Google Sheets API. The connector reads a configured range from a sheet using a Google Cloud service account and converts each row into a SeaTunnel record based on the user-defined schema.

Support Those Engines

Spark
Flink
SeaTunnel Zeta

Key features

Data Type Mapping

The Google Sheets API does not expose per-cell types — every cell comes back as an untyped raw value. The connector casts each cell according to the user-declared schema option, so the resulting SeaTunnel type is driven entirely by your schema, not by any type detected from the sheet itself. Cells with values that cannot be cast to the configured schema field will cause the connector to fail the row.

Google Sheets Cell	SeaTunnel Data Type (after schema cast)
string	string / numeric / boolean / date
number	int / long / float / double
boolean	boolean
date	date / time / timestamp

Source Options

name	type	required	default value	description
service_account_key	string	yes	-	Google Cloud service account credentials. Must be provided as a Base64-encoded JSON string.
sheet_id	string	yes	-	The sheet id of the Google Sheets URL, for example `1VI0DvyZK-NIdssSdsDSsSSSC-_-rYMi7ppJiI_jhE`.
sheet_name	string	yes	-	The name of the sheet (tab) inside the Google Sheets document to read from.
range	string	yes	-	The A1 notation range to read from the sheet, for example `A1:C3` or `Sheet1!A1:D100`.
schema	config	no	-	The schema of the rows emitted by the connector. See Schema Feature.

service_account_key [string]

The Base64-encoded JSON content of a Google Cloud service account key file. The service account must have access to the target Google Sheets document (share the sheet with the service account email).

sheet_id [string]

The id of the Google Sheets document. It is the long identifier between /d/ and /edit in the sheet's URL.

sheet_name [string]

The name of the sheet (tab) inside the Google Sheets document to read from, for example Sheet1.

range [string]

The A1 notation range to read from the sheet, for example A1:C3 to read a fixed area or Sheet1!A:D to read entire columns from a specific sheet.

schema [config]

fields [config]

The schema fields of upstream data. The connector reads each cell as a string and casts it to the declared field type. Please refer to Schema Feature for the available types.

Task Example

Simple

source {
  GoogleSheets {
    service_account_key = "seatunnel-test"
    sheet_id = "1VI0DvyZK-NIdssSdsDSsSSSC-_-rYMi7ppJiI_jhE"
    sheet_name = "sheets01"
    range = "A1:C3"
    schema = {
      fields {
        a = int
        b = string
        c = string
      }
    }
  }
}

With downstream sink

Read a sheet and print the rows through the Console sink.

env {
  parallelism = 1
  job.mode = "BATCH"
}

source {
  GoogleSheets {
    service_account_key = "seatunnel-test"
    sheet_id = "1VI0DvyZK-NIdssSdsDSsSSSC-_-rYMi7ppJiI_jhE"
    sheet_name = "sheets01"
    range = "A1:C100"
    schema = {
      fields {
        a = int
        b = string
        c = string
      }
    }
  }
}

sink {
  Console {
  }
}

Changelog

Change Log

Change	Commit	Version
[improve] google sheets options (#8922)	https://github.com/apache/seatunnel/commit/48ede612dc	2.3.10
[Improve] restruct connector common options (#8634)	https://github.com/apache/seatunnel/commit/f3499a6eeb	2.3.10
[Improve][API] Make sure the table name in TablePath not be null (#7252)	https://github.com/apache/seatunnel/commit/764d8b0bc8	2.3.7
[Feature][Kafka] Support multi-table source read (#5992)	https://github.com/apache/seatunnel/commit/60104602d1	2.3.6
[Improve][Connector-V2] Replace CommonErrorCodeDeprecated.JSON_OPERATION_FAILED (#5978)	https://github.com/apache/seatunnel/commit/456cd17714	2.3.4
[Improve][Common] Introduce new error define rule (#5793)	https://github.com/apache/seatunnel/commit/9d1b2582b2	2.3.4
Support config column/primaryKey/constraintKey in schema (#5564)	https://github.com/apache/seatunnel/commit/eac76b4e50	2.3.4
Merge branch 'dev' into merge/cdc	https://github.com/apache/seatunnel/commit/4324ee1912	2.3.1
[Improve][Project] Code format with spotless plugin.	https://github.com/apache/seatunnel/commit/423b583038	2.3.1
[improve][api] Refactoring schema parse (#4157)	https://github.com/apache/seatunnel/commit/b2f573a13e	2.3.1
[Improve][build] Give the maven module a human readable name (#4114)	https://github.com/apache/seatunnel/commit/d7cd601051	2.3.1
[Improve][Project] Code format with spotless plugin. (#4101)	https://github.com/apache/seatunnel/commit/a2ab166561	2.3.1
[Feature][shade][Jackson] Add seatunnel-jackson module (#3947)	https://github.com/apache/seatunnel/commit/5d8862ec9c	2.3.1
[Feature][Connector] add get source method to all source connector (#3846)	https://github.com/apache/seatunnel/commit/417178fb84	2.3.1
[Hotfix][OptionRule] Fix option rule about all connectors (#3592)	https://github.com/apache/seatunnel/commit/226dc6a119	2.3.0
[Improve][Connector-V2][GoogleSheets] Unified exception for GoogleSheets source connector (#3524)	https://github.com/apache/seatunnel/commit/eb42d629ad	2.3.0
[Feature][Connector-V2][Google Sheets] Add Google Sheets option rules (#3364)	https://github.com/apache/seatunnel/commit/da33f730ca	2.3.0
fix: schema get error (#3361)	https://github.com/apache/seatunnel/commit/fdaa85ed24	2.3.0
[Feature][Connector-V2][GoogleSheets] Support GoogleSheets Source (#3185)	https://github.com/apache/seatunnel/commit/60ecc6428b	2.3.0

Description
Support Those Engines
Key features
Data Type Mapping
Source Options
Task Example
- Simple
- With downstream sink
Changelog