> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scoutos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sync Google Sheets into Scout Databases

> Sync spreadsheet rows from Google Sheets directly into a Scout Database table. Map columns to fields, schedule syncs, and keep structured data current for agent retrieval.

The Google Sheets source syncs spreadsheet rows directly into a Scout table without rebuilding your data elsewhere. It's a good fit for structured lists that non-technical teams already maintain in a spreadsheet — CRM exports, content inventories, product catalogs, and similar data. Each row becomes a document, and your column headers map to table fields.

## Before You Start

* Create a Database and a destination table in Scout. See [Creating Databases](/databases/creating-databases).
* Make sure your sheet has a clear header row in **row 1** — Scout uses these headers as field names.
* Add table columns for the fields you want to search or filter on.
* Choose a stable identifier column (for example `ID`, `Slug`, or `URL`) before your first sync. Scout uses it to match and update existing rows; without one, every sync creates duplicates.

## Connect the Google Sheets Integration

<Steps>
  <Step title="Open Integrations">
    Navigate to **Integrations** in Scout.
  </Step>

  <Step title="Connect Google Sheets">
    Find **Google Sheets** in the list and start the connection.
  </Step>

  <Step title="Grant access">
    Sign in with your Google account and grant access to your spreadsheets.
  </Step>
</Steps>

<Note>
  Availability may vary by workspace during rollout.
</Note>

## How Sync Works

Scout reads the sheet top to bottom, treating each row as a document:

* **New rows** become new documents.
* **Updated rows** are matched by your stable identifier and overwritten — an upsert. Without an identifier, updates create duplicates instead.
* **Deleted rows** aren't removed automatically. Re-run with full replacement if you need to clear them out.

<Tip>
  Decide on a stable identifier column before your first sync. `ID`, `Slug`, and `URL` are common choices — anything that uniquely and consistently identifies a row.
</Tip>

## Create a Google Sheets Source

<Steps>
  <Step title="Open your Database table">
    Navigate to the table you want to populate.
  </Step>

  <Step title="Add a Source">
    Click **Sources** → **Add Source**, then select **Google Sheets**.
  </Step>

  <Step title="Select the spreadsheet">
    Choose the spreadsheet and the specific worksheet or tab to sync.
  </Step>

  <Step title="Map columns to fields">
    Match each sheet column to a column in your table. See [Field Mapping](#field-mapping) below.
  </Step>

  <Step title="Set sync frequency">
    Optionally choose a schedule, or leave the source as manual-only.
  </Step>

  <Step title="Create the source">
    Click **Create** to save the configuration.
  </Step>
</Steps>

## Field Mapping

Map your sheet headers to table column names. A typical content-inventory mapping looks like this:

| Sheet header   | Table column | Notes                        |
| -------------- | ------------ | ---------------------------- |
| `Title`        | `title`      | Used in search results       |
| `Page URL`     | `url`        | Links back to the source     |
| `Summary`      | `content`    | Main text for retrieval      |
| `Last Updated` | `updated_at` | Helps with freshness ranking |
| `Owner Team`   | `team`       | Useful for filtering         |

<Tip>
  Map your main text to the `content` column. Scout embeds this field for semantic search, so retrieval quality depends on it being mapped correctly.
</Tip>

Start with a small subset of columns and expand once you've validated data quality.

## Run and Validate

<Steps>
  <Step title="Run the source once">
    Trigger a manual run from the Sources panel.
  </Step>

  <Step title="Verify rows were created">
    Confirm the expected documents appear in your table.
  </Step>

  <Step title="Spot-check values">
    Check a few rows for correct types and formatting.
  </Step>

  <Step title="Query the data">
    Run a query to confirm retrieval quality. See [Querying Data](/databases/querying-data).
  </Step>
</Steps>

## Common Issues

<AccordionGroup>
  <Accordion title="Wrong or missing values">
    Confirm the header row exists in row 1, recheck your field mapping, and make sure column types match the shape of the data.
  </Accordion>

  <Accordion title="Duplicate documents">
    Add a stable identifier column before re-syncing. Without one, each sync creates new documents instead of updating existing ones.
  </Accordion>

  <Accordion title="Stale data">
    Review your sync strategy — full replacement versus incremental — and re-run after any major schema changes.
  </Accordion>

  <Accordion title="Permission errors">
    Reconnect with the correct Google account and verify you have at least view access to the spreadsheet.
  </Accordion>
</AccordionGroup>

## Best Practices

* **Keep header names consistent.** Renaming a header breaks the mapping until you update the source config.
* **Use an explicit table schema** rather than syncing every column in the sheet.
* **Schedule syncs only for sheets that change often.** Run manually for one-time imports.
* **Add metadata columns** like `team`, `status`, or `region` to support downstream filtering.

<Warning>
  Renaming a mapped sheet header or table column breaks the field mapping for that field. The column stays empty on subsequent syncs until you update the mapping.
</Warning>

## Next Steps

<CardGroup cols={3}>
  <Card title="Sources" icon="plug" href="/databases/sources">
    Compare all source types and their sync options.
  </Card>

  <Card title="Querying Data" icon="magnifying-glass" href="/databases/querying-data">
    Search synced data with semantic and hybrid search.
  </Card>

  <Card title="Creating Databases" icon="table" href="/databases/creating-databases">
    Design schemas for reliable ingestion.
  </Card>
</CardGroup>