Data Integrations

This page is the source of truth for how data gets into Bridge Town. It reconciles the connectors named on the marketing site against what is actually implemented in the platform today, and gives agents and users a clear recommended path for every common “connect my ” request.

TL;DR

Source	Status	How to bring it in
CSV / Excel / Parquet files (.csv, .xlsx, .xlsm, .parquet, ≤50 MB) — as a data table	Live	Browser: Data Sources → Upload file on /data — or via MCP: ingest_data_source with kind: "file_upload"
Excel workbook — convert formulas/sheets into a Bridge Town Python project	Live	Excel Workbook Conversion — browser upload or upload link, then review and apply generated files
Google Sheets (Picker-connected, manual or scheduled snapshot)	Live	ingest_data_source with kind: "google_sheet_snapshot" after connecting in the web app
Databases & data warehouses (Snowflake, BigQuery, Postgres, Redshift, etc.)	Live, via export	Export to CSV/Excel/Parquet, then ingest_data_source with kind: "file_upload" — or land in a Google Sheet and connect it here. There is no live JDBC/ODBC connector.
Salesforce, HubSpot, Stripe	Planned	Today: export the relevant report/dataset to CSV and call ingest_data_source with kind: "file_upload".
Ramp / Brex, Rippling, Deel	Planned	Today: export the relevant report to CSV and call ingest_data_source with kind: "file_upload".

If a connector is not in the Live rows above, treat it as planned and use the export-then-upload path until it ships.

Excel as a data table vs. Excel workbook conversion

Bridge Town has two separate pathways for Excel files. Choosing the wrong one is a common mistake.

Situation	Path to use
The Excel file is a data export — rows of actuals, a headcount roster, a pricing table	ingest_data_source with kind: "file_upload"
The Excel file is a financial model — formulas, named ranges, sheets with business logic	Excel Workbook Conversion

ingest_data_source on a workbook with formulas stores the cached cell values only. It does not translate formulas, preserve workbook structure, or produce Python code. If you upload a budget model this way, you get a snapshot of the numbers — not the model.

Excel workbook conversion profiles the workbook structure, translates supported formulas to Bridge Town Python, produces parity tests, and generates dashboard candidates. It does not ingest data into a Parquet snapshot.

See the Excel Workbook Conversion guide for the full workflow, v1 support matrix, upload options, and security notes.

How Bridge Town thinks about data

Bridge Town’s execution model is snapshot-based, not live-connected:

1. Data is captured into Bridge Town as an immutable Parquet snapshot on S3 ({tenant_id}/{project_name}/uploads/{source_name}.parquet).
2. Models read from that snapshot via DuckDB at run time.
3. New uploads create new snapshots; older snapshots stay reproducible.

This means there is no “live database connector” in the product today — even Google Sheets goes through a snapshot import via ingest_data_source. DuckDB then runs queries in-process against the snapshot. No external data warehouse is required, and nothing in the model run reaches out to the source system at execution time. See Data Sources & Snapshots for the full mental model.

What works today

CSV, Parquet, and Excel table uploads

Bridge Town accepts .csv, .parquet, .xlsx, and .xlsm files (up to 50 MB) as data sources — treating the file as a rectangular data table (rows and columns), not as a formula-based workbook. To convert an Excel financial model, see Excel Workbook Conversion.

Browser upload (recommended for most users):

1. Go to Data Sources (/data).
2. Click Upload file on the Upload file card.
3. Select a project, enter a source name, and drop or browse to your file.
4. For .xlsx/.xlsm: you can click Convert the logic if you want a Python model instead of a data table.
5. Click Upload — Bridge Town stores the file as an immutable snapshot and infers column schemas automatically.

MCP tool upload (for agents):

{
  "name": "ingest_data_source",
  "arguments": {
    "project_name": "q2-forecast",
    "spec": {
      "kind": "file_upload",
      "source_name": "actuals",
      "filename": "actuals_q1.csv",
      "file_content": "<base64-encoded file bytes>"
    }
  }
}

Schema is inferred automatically with best-effort type coercion. Re-uploading (browser: click Re-upload on the source row; MCP: call ingest_data_source again with the same source_name) creates a new snapshot — earlier model runs keep pointing at the snapshot they ran against. See ingest_data_source for the full parameter list.

Large files and chat-based hosts

For files larger than a few hundred KB, or when the MCP host cannot handle large binary tool arguments (e.g. Claude.ai), direct the user to upload via the web app instead: Data Sources → Add data source → Upload file at app.bridgetown.builders. The browser upload path accepts files up to 50 MB and does not pass file bytes through the tool call. For .xlsx / .xlsm uploads, the wizard asks whether to ingest the file as a data table (Use the numbers) or convert the workbook’s formulas into a Python project (Convert the logic).

Google Sheets

The ingest_data_source tool with kind: "google_sheet_snapshot" reads selected tabs from a Picker-connected Google Sheet, converts each tab to CSV, and stores it as a Parquet snapshot. The sheet must be connected once via the web app (Picker-based OAuth) before the tool can run.

To connect a sheet:

1. Open app.bridgetown.builders → Data Sources (/data).
2. Click Connect Google Sheet — this opens the four-step connection wizard.
3. Sign in with Google (step 1), pick a spreadsheet using the Google file picker (step 2), select tabs and set a refresh schedule (step 3), and confirm (step 4).
4. Bridge Town registers the sheet as a project data source with a source_name.

Then import:

{
  "name": "ingest_data_source",
  "arguments": {
    "project_name": "q2-forecast",
    "spec": {
      "kind": "google_sheet_snapshot",
      "source_name": "budget_actuals",
      "tab_names": ["Sales", "Costs"],
      "schedule_interval_minutes": 1440
    }
  }
}

Pass schedule_interval_minutes to refresh the snapshot on a schedule (common values: 60 hourly, 1440 daily, 10080 weekly). See the full Google Sheets Integration guide for the end-to-end workflow including Picker connection, write-back, and creating new Sheets from model output.

Querying with DuckDB

Once data is uploaded or linked, query it with query_data:

-- Uploaded file (source_name = "actuals"):
SELECT region, SUM(revenue) AS total
FROM actuals
GROUP BY region
ORDER BY total DESC;

-- Google Sheet snapshot (source = "budget_actuals", tab = "Q1 Revenue"):
SELECT * FROM budget_actuals_Q1_Revenue LIMIT 10;

DuckDB runs queries in-process inside the MCP server — no external data warehouse is required. Use list_data_sources first to discover exact table names and schemas.

Bringing database and warehouse data in today

Bridge Town does not ship a live JDBC/ODBC connector for Snowflake, BigQuery, Postgres, Redshift, MySQL, or other warehouses. Two patterns work well today:

Option 1 — Export to file, then ingest_data_source

For most warehouse data, the simplest path is to export the relevant table or query result to CSV/Excel/Parquet and call ingest_data_source with kind: "file_upload".

Examples:

Warehouse	One-time export pattern
Snowflake	COPY INTO @stage/file.csv FROM (SELECT ... ); then download from the stage and ingest_data_source
BigQuery	EXPORT DATA OPTIONS(uri='gs://…/data-*.csv', format='CSV') AS (SELECT ...), then download and ingest_data_source
Postgres / Redshift	\copy (SELECT ...) TO 'data.csv' CSV HEADER, then ingest_data_source
dbt / Airflow / Fivetran outputs	Land the model output as a CSV/Parquet in object storage or a shared drive, then ingest_data_source

For recurring loads, automate the export from your orchestrator (Airflow, dbt Cloud, GitHub Actions, etc.) and have the final step call ingest_data_source with a stable source_name. Each run produces a new snapshot.

Parquet is preferred for large tables

ingest_data_source accepts CSV and Excel today. If your dataset is on the larger side, consider exporting smaller pre-aggregated CSVs scoped to the model’s needs rather than full table dumps. Files must be ≤100 MB.

Option 2 — Land the warehouse data in a Google Sheet first

When a warehouse view is small enough to fit in Google Sheets and your team already publishes scorecards there, you can:

1. Use a warehouse-to-Sheets connector (e.g. Google Sheets BigQuery connector, Connected Sheets, Census, Hightouch, Coefficient) to push the query result into a sheet your team owns.
2. Connect that sheet via Picker in the Bridge Town web app.
3. Snapshot the sheet with ingest_data_source (kind: google_sheet_snapshot) and set schedule_interval_minutes so Bridge Town re-snapshots on its own cadence.

This gives you a refresh cadence without writing your own export pipeline, at the cost of an extra hop through Google Sheets.

Planned connectors

The marketing site lists business-system connectors as planned. None of these are live today. Until they ship, agents and users should fall back to the export-then-upload path.

Connector	Status	Recommended path today
Salesforce	Planned	Export the report (Reports → “Export”) to CSV, then ingest_data_source.
HubSpot	Planned	Export the list/report to CSV, then ingest_data_source.
Stripe	Planned	Export from the Stripe Dashboard (Payments / Balance / Reports), then ingest_data_source.
Ramp / Brex	Planned	Export the transactions or spend report to CSV, then ingest_data_source.
Rippling	Planned	Export the headcount/payroll report to CSV, then ingest_data_source.
Deel	Planned	Export the contractor/payment report to CSV, then ingest_data_source.
Live database / warehouse JDBC connector	Planned	Use Option 1 or Option 2 above.

If a customer needs a connector that is not yet live, capture the request at integrations@bridgetown.builders or support@bridgetown.builders — that is the input we use to pick what to build next.

Agent playbook: answering “connect my ”

When a user asks an agent to “connect Salesforce”, “pull from our warehouse”, “hook up Stripe”, or similar, do not invent a tool call. There is no connect_salesforce, connect_warehouse, connect_stripe, etc. Instead, follow this script:

1. Acknowledge the request and name the current state. Confirm the system is on the roadmap but not live, and explain the snapshot model — Bridge Town runs models against captured snapshots, not live source systems.
2. Offer the supported path now.
   • Direct DB / warehouse → ask the user to export the query/table to CSV, Excel, or Parquet (≤100 MB) and use ingest_data_source with kind: "file_upload".
   • Salesforce / HubSpot / Stripe / Ramp / Brex / Rippling / Deel → ask the user to export the relevant report to CSV from that system’s UI and use ingest_data_source with kind: "file_upload".
   • If the data already lives in a Google Sheet the user has connected via Picker, use ingest_data_source with kind: "google_sheet_snapshot" and a refresh schedule.
3. Help structure the upload. Suggest a clear source_name (e.g. salesforce_pipeline, stripe_payments, warehouse_revenue_actuals), and confirm with list_data_sources afterwards so downstream tools can discover the schema.
4. Capture the connector demand. If the user is blocked because the manual path is too painful, suggest emailing integrations@bridgetown.builders so it feeds the roadmap.

Example agent reply

Bridge Town doesn’t have a live Salesforce connector yet — that’s on our roadmap but not shipped. The fastest way to model your pipeline today is to export the Salesforce report you care about (Reports → Export → CSV) and upload it as a data source. I can call ingest_data_source with source_name salesforce_pipeline once you have the file. After that, we can query it with query_data and use it in your forecast model. If you want this automated, you can also push the same data into a Google Sheet from Salesforce and I’ll connect the sheet on a daily refresh.

Example agent reply (warehouse)

There isn’t a direct Snowflake connector yet — Bridge Town runs models against captured snapshots rather than live database connections. For now the cleanest path is: run your SELECT in Snowflake, export the result to CSV (or Parquet ≤100 MB), and I’ll call ingest_data_source with that file and a source_name of warehouse_revenue_actuals. If this is a recurring load, your orchestrator (Airflow, dbt, GitHub Actions) can do the export and call ingest_data_source on a schedule. Want me to outline that pipeline?

When to escalate to support

If a user requires:

• A connector that does not yet exist and cannot work via export/upload
• Help wiring an export pipeline from a warehouse or BI tool to ingest_data_source
• Larger-than-100 MB datasets, partitioned warehouse loads, or live-DB read patterns

…direct them to Bridge Town Services or support@bridgetown.builders. The services team can scope a one-off integration or migration without inventing tool calls that do not exist.

Related references

Page	Why it’s useful
Data Sources & Snapshots	Conceptual model: snapshots, immutability, DuckDB-in-process.
Excel Workbook Conversion	Convert an Excel financial model (formulas, sheets, named ranges) into a Bridge Town Python project.
Google Sheets Integration	End-to-end walkthrough: Picker connect, import, query, write-back, scheduled refresh.
ingest_data_source	Tool reference for CSV/Excel file ingestion and Google Sheet snapshot imports.
list_data_sources	Discover the tables and schemas of every source attached to a project.
query_data	Run read-only DuckDB SQL against uploaded files and Sheet snapshots.
Bridge Town Services · support@bridgetown.builders	Hands-on help for migrations and bespoke integration pipelines.