Already have an account? Sign in

Google Sheets (v1)

Google Sheets integration summary

Stitch’s Google Sheets integration replicates data using theGoogle Sheets v4 AP1. Refer to theSchema section for a list of objects available for replication.

Stitch’s Google Sheets integration will generate tables containing data related to metadata and the individual sheets within a spreadsheet.

Note: There are a few limitations:

• Currently, the Google Sheets integration replicates one spreadsheet at a time. To replicate another spreadsheet, you will need to create another Google Sheets integration in Stitch.
• TheIMPORTRANGE() function in Google Sheets isn’t currently supported. This integration identifies new and updated data using a spreadsheet’s lastupdated_at value, which theIMPORTRANGE() doesn’t update when used.
• Spreadsheets from sharedTeam Drives aren’t currently supported. Permission and/orFile Not Found errors will surface during extraction if you connect a spreadsheet from a shared Team Drive.

Google Sheets feature snapshot

A high-level look at Stitch's Google Sheets (v1) integration, including release status, useful links, and the features supported in Stitch.

Connecting Google Sheets

Google Sheets setup requirements

To set up Google Sheets in Stitch, you need:

• A spreadsheet in your Google Drive (My Drive). Stitch’s Google Sheets integration doesn’t currently support replicating spreadsheets from shared Team Drives.

• A header row with unique column values in the first row of every sheet you want to replicate. If there are multiple headers not in the first row, your worksheet data may not be replicated correctly. Headers that aren’t in the first row may be extracted as column data.

• A full row of data in the second row of every sheet you want to replicate. Data must begin in the second row of the sheet. Values in this row may not beNULL orissues will arise during Extraction.

Step 1: Obtain your spreadsheet ID

1. Go toGoogle Sheets and log into the Google account associated with the spreadsheet you are looking to integrate.
2. Open the spreadsheet that you want to use in the integration.
3. The Spreadsheet ID is within the URL to the webpage. In the image below, the portion of the URL within the blue box is the Spreadsheet ID. Keep this readily available to continue with the integration.Note: The file should be stored inMy Drive and not a shared drive or you’ll receive aFile Not Found error.

Step 2: Add Google Sheets as a Stitch data source

1. Sign into your Stitch account.

2. On the Stitch Dashboard page, click theAdd Integration button.

3. Click theGoogle Sheets icon.

4. Enter a name for the integration. This is the name that will display on the Stitch Dashboard for the integration; it’ll also be used to create the schema in your destination.

   For example, the name “Stitch Google Sheets” would create a schema calledstitch_google_sheets in the destination.Note: Schema names cannot be changed after you save the integration.

5. In theSpreadsheet ID field, enter your Spreadsheet ID you obtained from theprevious step.Note: To integrate another spreadsheet, you’ll need to repeat these steps over again with another Google Sheets integration.

Step 3: Define the historical replication start date

The Sync Historical Data setting defines the starting date for your Google Sheets integration. This means that dataequal to or newer than this date will be replicated to your data warehouse.

Change this setting if you want to replicate data beyond Google Sheets’s default setting of1 year. For a detailed look at historical replication jobs, check out theSyncing Historical SaaS Data guide.

Step 4: Create a replication schedule

In theReplication Frequency section, you’ll create the integration’sreplication schedule. An integration’s replication schedule determines how often Stitch runs a replication job, and the time that job begins.

Google Sheets integrations support the following replication scheduling methods:

• Replication Frequency

• Anchor Scheduling

• Advanced Scheduling using Cron (Advanced or Premium plans only)

To keep your row usage low, consider setting the integration to replicate less frequently. See theUnderstanding and Reducing Your Row Usage guide for tips on reducing your usage.

Step 5: Authorize Stitch

1. Next, you’ll be prompted to log into your Google account and approve Stitch’s access to your Google Sheets data.Note that we will only ever read your data.
2. Select theSee all your Google Sheets spreadsheets access.
3. ClickContinue.

Step 6: Set objects to replicate

The last step is to select the tables and columns you want to replicate.Learn about the available tables for this integration.

Note: If a replication job is currently in progress, new selections won’t be used until the next job starts.

• Selection options
• Individual tables and columns
• All tables and columns

Initial and historical replication jobs

After you finish setting up Google Sheets, itsSync Status may show asPending on either the Stitch Dashboard or in the Integration Details page.

For a new integration, aPending status indicates that Stitch is in the process of scheduling the initial replication job for the integration.This may take some time to complete.

Free historical data loads

The first seven days of replication, beginning when data is first replicated, are free. Rows replicated from the new integration during this time won’t count towards your quota. Stitch offers this as a way of testing new integrations, measuring usage, and ensuring historical data volumes don’t quickly consume your quota.

Google Sheets replication

In this section:

• Details about Extraction, including object discovery and selecting data for replication

• Details about how data replicated from Google Sheets is loaded into a destination

Extraction

For every table set to replicate, Stitch will perform the following during Extraction:

• Discover table schemas and type discovered columns

• Select records (files) for replication

Discovery

During Discovery, Stitch will:

• Determine table schemas

• Type the data in discovered columns

Determining table schemas

At the start of each replication job, Stitch will check the sheets’s header row and first data row (the second row in the sheet) for data.

To be detected and properly replicated, every sheet set to replicate must have:

1. Column headers with unique values in the first row. If there are duplicate column names, Stitch will skip the sheet and surface aduplicate column name error.

   For example: Two columns in the header row can’t be namedcustomer_id. Uniqueness must not rely on case. Whilecustomer_id andCustomer_ID may be unique due to case differences, this may still cause errors during extraction and loading. For this reason, column names must be completely unique.

2. A full row of data in the second row. If any column in this row contains aNULL value, Stitch will skip the sheet and surface amalformed sheet message during extraction.

If the sheet doesn’t contain a header row and a second row of data, Stitch will skip the sheet and surface anempty sheet message during extraction.

Data typing

To determine data types, Stitch will analyze the first two rows in thefiles included in object discovery.

If a column contains non-standard boolean language, Stitch will intentionally coerce those values into boolean. The following values are to be expected to be replicated asTrue:

• YES/yes
• Y/y
• 1
• true (the string “true” prefixed with a tick [`])

The following values are expected to be replicated asFalse:

• NO/no
• N/n
• 0
• false (the string “false” prefixed with a tick [`])

If a column has been specified as aSTRING, Stitch will attempt to parse the value as a string, unless the column contains non-standard boolean language. If this fails, the column will be loaded as a nullableSTRING.

For all other columns, Stitch will perform the following to determine the column’s data type:

1. Attempt to parse the value as aBOOLEAN value
2. If that fails, attempt to parse the value as anINTEGER
3. If that fails, attempt to parse the value as aDATE-TIME value
4. If that fails, attempt to parse the value as aDATE date
5. If that fails, attempt to parse the value as aTIME value
6. If that fails, type the column as aSTRING

Data replication

After discovery is completed, Stitch will move onto extracting data from the sheets set to replicate.

While data from Google Sheets integrations is replicated usingKey-based Incremental Replication, the behavior for this integration differs subtly from other integrations.

The table below compares Key-based Incremental Replication andReplication Key behavior for Google Sheets to that of other integrations.

To reduce row usage, considerscheduling the integration to replicate less frequently.

Loading

For every sheet you set to replicate, Stitch will create a table in your destination. These tables will contain the columns you select for replication, along with some system columns created by Stitch. Refer to thesample table in the next section for an example.

Google Sheets table reference

sample_table.__sdc_spreadsheet_id = spreadsheet_metadata.spreadsheetId

sample_table.__sdc_spreadsheet_id = sheet_metadata.spreadsheetId

sample_table.__sdc_sheet_id = sheet_metadata.sheetId

sample_table.__sdc_spreadsheet_id = sheets_loaded.spreadsheetId

sample_table.__sdc_sheet_id = sheets_loaded.sheetId

sheet_metadata.spreadsheetId = spreadsheet_metadata.spreadsheetId

sheet_metadata.spreadsheetId = sheets_loaded.spreadsheetId

sheet_metadata.sheetId = sheets_loaded.sheetId

sheet_metadata.spreadsheetId = sample_table.__sdc_spreadsheet_id

sheet_metadata.sheetId = sample_table.__sdc_sheet_id

sheets_loaded.spreadsheetId = spreadsheet_metadata.spreadsheetId

sheets_loaded.spreadsheetId = sheet_metadata.spreadsheetId

sheets_loaded.sheetId = sheet_metadata.sheetId

sheets_loaded.spreadsheetId = sample_table.__sdc_spreadsheet_id

sheets_loaded.sheetId = sample_table.__sdc_sheet_id

spreadsheet_metadata.spreadsheetId = sheet_metadata.spreadsheetId

spreadsheet_metadata.spreadsheetId = sheets_loaded.spreadsheetId

spreadsheet_metadata.spreadsheetId = sample_table.__sdc_spreadsheet_id

Did this article help? If you have questions or feedback, feel free tosubmit a pull request with your suggestions,open an issue on GitHub, orreach out to us.