feat: add dry run to the read_gbq function

[antoineeripret]

This change allows the user to run a dry run query using the read_gbq function. Instead of returning a pd.DataFrame, the behavior is changed and the amount of data processed (in GB) is returned.

[shuoweil]

@antoineeripret Could you please check the failed tests? Thanks a lot.

[antoineeripret]

@shuoweil , I've added a new commit with some changes to fix tests. I've ran nox -s unit-3.10 and got 0 fails. Thank you !

[shuoweil]

• lint / lint (pull_request)

Hi @antoineeripret, could you please check the failed check please? It should be a quick fix. Thanks a lot.

[antoineeripret]

Hi @shuoweil, the last commit should fix it. Got the following on my local env:

python -m black --check docs pandas_gbq tests noxfile.py setup.py
All done! ✨ 🍰 ✨
45 files would be left unchanged.

[sycai]

Could we simply return query_job.total_bytes_processed without further processing?

Reasons:

• The total_bytes_processed has integer type, which is more precise than a float type
• For small tables (ones with 1-10 MB sizes), converting the size to GB makes the result less readable
• It aligns more with the behavior of BigQuery Python client to return size in bytes.

Generally speaking, we want the caller of this function to perform unit conversions.

[antoineeripret]

@sycai, good call ! I've though about my own usage, but didn't think about the bigger picture here. I'll commit the change. :)

[sycai]

Thank you! I think we should be good to go once the doc and tests are updated.

[antoineeripret]

@sycai : updated :)

[shuoweil]

@antoineeripret I believe lint fails. Could you please update it? It still fails with the new commit.

[antoineeripret]

@shuoweil, fixed with last commit (I left a trailing space) in a file.

[shuoweil]

@antoineeripret Could you please take a look at the failed testcases? They seem to related to your change.
tests/system/test_gbq.py::TestReadGBQIntegration::test_read_gbq_with_dry_run

Thanks a lot.

[shuoweil]

@antoineeripret Please check the failed testcase tests/system/test_gbq.py::TestReadGBQIntegration::test_read_gbq_with_dry_run

[antoine-eripret-docplanner]

@shuoweil: Can I have the details of what has failed? I can't read the Kokoro's results (permission denied). Thank you !

[sycai]

Hey @antoineeripret I took the liberty to directly enhance your code.

Now when we do dry run, we will get more stats like table schema and creation time in addition to the total bytes processed. The results are aggregated into a pandas Series like this:

bigquerySchema         [SchemaField('my_col', 'TIMESTAMP', 'NULLABLE'...
projectId                                                     project-id
location                                                              US
jobType                                                            QUERY
dispatchedSql                                   SELECT * FROM `my_table`
destinationTable          {'projectId': 'project-id', 'datasetId': '_...
useLegacySql                                                       False
referencedTables          [{'projectId': 'project-id', 'datasetId': '...
totalBytesProcessed                                                  320
cacheHit                                                           False
statementType                                                     SELECT
creationTime                            2025-12-29 19:36:24.972000+00:00
dtype: object

I will make sure all the tests pass this time.

Also tagging @shuoweil and @tswast as it aligns more with our BigFrames code: https://github.com/googleapis/python-bigquery-dataframes/blob/69fa7f404cde5a202df68ed21a6faeac98fb1e4d/bigframes/session/dry_runs.py#L112

[antoineeripret]

Hey @antoineeripret I took the liberty to directly enhance your code.
[...]

Amazing improvement, thanks for adding your input and knowledge @sycai ! The output is beter than what I had envisioned !

Thank you !