Filter BigQuery From a Connected Sheets Cell Range

Connected Sheets can pass a cell range to BigQuery as one list parameter. Put one filter value in each cell, add the range as a Cell Reference parameter, and filter the query with IN UNNEST(@PARAMETER_NAME). Collaborators can then change the filter values without editing the SQL.

Enter your range, parameter name, and BigQuery field to check the setup and generate the filter clause.

Google introduced range-based list parameters in August 2026. Each selected cell supplies a value to the list, allowing an input sheet or dropdowns to control filtering without changes to the underlying query (Google Workspace Updates).

This is a Connected Sheets feature for BigQuery. It does not apply to the regular Google Sheets QUERY() formula.

Build a Clean Input Range

Assume the BigQuery table contains three fields: region, order_id, and net_sales.

Create an Input sheet and enter one region per cell:

Cell	Value
B2	North
B3	South
B4	West

Use Input!B2:B4 as the parameter range. Keep its header outside the selection, and avoid a larger open-ended range containing unused cells, notes, or subtotals.

The cells should represent one consistent data type. Do not mix numeric IDs with text versions of the same IDs. Values such as ZIP codes may look numeric while needing to remain text so that leading zeroes and exact formatting survive.

Dropdowns are useful when collaborators must choose from an approved vocabulary. They reduce spelling, capitalization, and spacing differences that could prevent otherwise valid values from matching the source table.

Add the Range as a List Parameter

You need access to the relevant BigQuery project. The Connected Sheets query editor supports GoogleSQL rather than legacy SQL (Google Docs Editors Help).

1. In Google Sheets, select Data > Data connectors > Connect to BigQuery.
2. Choose the project, then open Saved queries and query editor.
3. In the panel on the right, select Parameters > Add.
4. Enter REGIONS as the parameter name. Do not include the @ prefix in this field.
5. Choose Cell Reference.
6. Select or enter Input!B2:B4, confirm the range, and add the parameter.

The parameter definition uses REGIONS, while the SQL refers to it as @REGIONS. If you include @ when naming the parameter in the panel, the query reference will not match the intended name.

Filter With IN UNNEST()

BigQuery documents IN UNNEST(@parameter) as the syntax for testing a field against an array parameter (BigQuery documentation). For the sample range, use this query after replacing the table path and fields with those in your schema:

SELECT region, COUNT(DISTINCT order_id) AS order_count, SUM(net_sales) AS net_sales FROM project_id.dataset_id.orders WHERE region IN UNNEST(@REGIONS) GROUP BY region ORDER BY net_sales DESC;

Select Preview results to inspect the output and estimated data scanned. Select Connect when the query is ready.

With North, South, and West in the sample range, the result should contain aggregates for those regions where matching source records exist. It should not contain another region. The output order may differ from the cell order because the query sorts by net_sales.

Do not substitute the range parameter directly into an IN list as if it were a single scalar value. Connected Sheets supplies a list, and UNNEST() exposes its values for the membership test.

Match Cell And BigQuery Types

The BigQuery field and the cells need compatible types. If the field contains text but the cells are interpreted as numbers, or the reverse, correct the input cells before relying on the result.

Where conversion is intentional, cast explicitly in SQL. A numeric-looking ZIP code that must remain text can use WHERE CAST(zip_code AS STRING) IN UNNEST(@ZIP_CODES).

Casting can make the intended comparison clear, but it should not conceal inconsistent inputs. Use one representation throughout the input range and confirm that it matches the source data’s meaning.

A parameter cannot stand in for a table name or column name. BigQuery parameters substitute values and expressions, not identifiers such as schema objects or field names. The table and field references must remain part of the SQL itself.

Validate The Filtered Result

Check the result before treating it as a finished extract:

• Value coverage: Every intended input with matching source records appears in the result.
• Unexpected values: No value outside the selected list appears.
• Types: The BigQuery field and input cells represent the same kind of value.
• Totals: The filtered total agrees with a known control query or existing report.
• Range boundaries: The parameter excludes headings, notes, subtotals, and unused cells.

A missing result is not automatically a parameter failure. The selected value may have no matching source record. Compare the input list with the underlying data or a control query before changing the range.

Likewise, the number of output rows does not necessarily equal the number of selected cells. The sample query groups by region, duplicate input values do not create duplicate groups, and selected regions without source records do not appear.

Publish A Reviewed Extract

Treat the Connected Sheet as the working analysis and publish a reviewed extract. This keeps parameter controls, helper tabs, and unrelated workbook data out of the public file.

1. Refresh the query using the final list.
2. Copy the result to a publication-only sheet or export it as CSV.
3. Give every output column a clear, stable heading.
4. Record the source table, query date, and selected filter values in accompanying notes.
5. Verify row counts and totals in the exported file, not only in the live Connected Sheet.
6. Remove fields that should not be public. Do not publish sensitive or restricted data.

If the result is too large for a normal workbook workflow, create a bounded extract rather than splitting rows arbitrarily. The guide to large CSV files and Connected Sheets explains that decision.

TablePage accepts CSV, TSV, XLSX, and XLS files and turns an uploaded dataset into a public page with a filterable table (TablePage). Upload only the reviewed publication file. The cell range controls what BigQuery returns; the exported result is the artifact readers should receive.