feat(BigQuery): Add support for Stateless Queries: Stateless query by Hectorhammett · Pull Request #9022 · googleapis/google-cloud-php

Hectorhammett · 2026-03-17T21:20:15Z

Add support for stateless queries.

b/331273989

bshaffer

Looks great! A couple nits, but my main concern is with the QueryResults::fromStatelessQuery method. I think there may be an opportunity for improvement there.

Also, could we add a SystemTest for this? Even if it's not run on CI it would be nice to have it as a sanity check.

bshaffer · 2026-03-18T21:16:27Z

BigQuery/src/QueryJobConfiguration.php

+                isset($queryConfig['priority']) &&
+                $queryConfig['priority'] !== 'INTERACTIVE'
+            ) ||
+            (isset($queryConfig['useLegacySql']) && $queryConfig['useLegacySql']) ||


nit: Consider this more concise variant?

Suggested change

(isset($queryConfig['useLegacySql']) && $queryConfig['useLegacySql']) ||

($queryConfig['useLegacySql'] ?? false) ||

bshaffer · 2026-03-18T21:17:08Z

BigQuery/src/QueryJobConfiguration.php

+            return false;
+        }
+
+        if (isset($config['configuration']['dryRun']) && $config['configuration']['dryRun']) {


Same here

Suggested change

if (isset($config['configuration']['dryRun']) && $config['configuration']['dryRun']) {

if ($config['configuration']['dryRun'] ?? false) {

I know you're right, I know you're right haha, but my brain always liked the other one:
Hey, is this set? Yes? ok so... is this true?

And the bottom one reads like "This true ?? FALSE" to me haha.

But I think is more readable your way haha.

bshaffer · 2026-03-18T21:18:32Z

BigQuery/src/QueryJobConfiguration.php

+        if (isset($config['jobReference']['jobId']) && !$this->isJobIdGenerated()
+        ) {


nit: the closing parenthesis should only on a newline if the if statement spans multiple lines

Suggested change

if (isset($config['jobReference']['jobId']) && !$this->isJobIdGenerated()

) {

if (isset($config['jobReference']['jobId']) && !$this->isJobIdGenerated())

{

bshaffer · 2026-03-18T21:20:52Z

BigQuery/src/QueryJobConfiguration.php

+            (
+                isset($queryConfig['priority']) &&
+                $queryConfig['priority'] !== 'INTERACTIVE'
+            ) ||


nit: I find it a tiny bit hard to read that we have a bunch of isset calls, but then we have this block, and the block below, that are different. Also, we have dryRun, which follows the same logic as useLegacySql, but isn't in this block.

My preference would be that we separate out the more complex checks from this large if statement, for readability.

bshaffer · 2026-03-18T21:23:29Z

BigQuery/src/BigQueryClient.php

+        if ($query instanceof QueryJobConfiguration && $query->isStateless()) {
+            $queryRequest = $query->toQueryRequest();
+
+            if (isset($queryResultsOptions['formatOptions.useInt64Timestamp'])) {


nit: This is for backwards compatiblity, correct? Maybe add a comment saying that, for clarity

This is because for some reason, the RequestBuilder handles this in a dot notation for get requests but not for post request, which in a stateless query is a post request. In the jobs.query api, this is expected to be in the body instead of the query parameters. So I am normalizing the regular options passed by the user into a json body for the request.

This lives on cloud-core::RequestBuilder::build line 115.

bshaffer · 2026-03-18T21:24:26Z

BigQuery/src/BigQueryClient.php

+            $statelessArgs = $queryRequest + $queryResultsOptions + [
+                'projectId' => $this->projectId
+            ] + $options;


I don't love that we are just adding $options at the end like this... can we validate the keys before or after doing this, so we know for sure what values are being added?

bshaffer · 2026-03-18T21:25:20Z

BigQuery/src/BigQueryClient.php

+                $this->projectId,
+                $statelessResponse,
+                $this->mapper,
+                $queryResultsOptions + $options


Same here... we did all the work to validate $queryResultOptions and $queryRequest, it would be nice to do the same to these $options and the ones above, so we know what keys are being passed in.

bshaffer · 2026-03-18T21:26:51Z

BigQuery/src/JobConfigurationTrait.php

     */
    private $config = [];

+    private bool $isJobIdGenerated = false;


since this is only used in QueryJobConfiguration, I'd advocate for moving it out of the trait and instead keeping it entirely in QueryJobConfiguration. I don't see any need to have it in the trait if it isn't used in the other classes which use the trait.

bshaffer · 2026-03-18T21:27:55Z

BigQuery/src/QueryResults.php

+        if (!isset($this->info['jobReference'])) {
+            return $this->info;
+        }


This doesn't seem right

If we had a stateless query, the response would be in the info field. If it has not JobReference, it means that it was in fact, completely stateless and we cannot "reload" by sending the request as there is no jobId to getQueryResults from.

Maybe we could throw and error if you want to reload a stateless query results? But that means that the user would have to be aware of the internal changes and it would be a breaking change to some people.

bshaffer · 2026-03-18T21:39:28Z

BigQuery/src/QueryResults.php

+     *        [documentation](https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs/getQueryResults#query-parameters)
+     *        for available options.
+     */
+    public static function fromStatelessQuery(


I have to say, I don't love this implementation. It seems like we are creating a Job for no reason, where we should make the Job nullable (Stateless queries don't have jobs, right? You run them immediately?).

This may require further discussion, but IMHO it seems like it would be better to instantiate QueryResults in the runQuery method, and then have waitUntilComplete be a no-op (or throw an exception) for Stateless Queries, since they're not applicable.

A Sateless query may or may not create a job. If we take a look at QueryJobConfiguration::toQueryRequest() line 678, the request has the field:
jobCreationMode => self::JOB_CREATION_MODE_OPTIONAL enum here

So even though we run the stateless query path, BigQuery itself may decide that the best course of action for this query is to actually create a Job, meaning that we do have a job reference and jobId when the job.query endpoint responds.

We cannot force BigQuery to run it stateless.

Hectorhammett added 2 commits March 17, 2026 21:00

Add support for stateless queries

080d6e2

Fix style

182f001

Hectorhammett requested a review from a team as a code owner March 17, 2026 21:20

product-auto-label bot added the api: bigquery Issues related to the BigQuery API. label Mar 17, 2026

Edit line length

0a61b88

Hectorhammett mentioned this pull request Mar 18, 2026

feat(BigQuery): Add support for Stateless Queries #8943

Closed

Hectorhammett added the next release PRs to be included in the next release label Mar 18, 2026

Remove unnecessary check

eb8ec4d

bshaffer reviewed Mar 18, 2026

View reviewed changes

	(isset($queryConfig['useLegacySql']) && $queryConfig['useLegacySql']) \|\|
	($queryConfig['useLegacySql'] ?? false) \|\|

	if (isset($config['configuration']['dryRun']) && $config['configuration']['dryRun']) {
	if ($config['configuration']['dryRun'] ?? false) {

		if (isset($config['jobReference']['jobId']) && !$this->isJobIdGenerated()
		) {

Conversation

Hectorhammett commented Mar 17, 2026

Uh oh!

bshaffer left a comment

Choose a reason for hiding this comment

Uh oh!

bshaffer Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bshaffer Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bshaffer Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bshaffer Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Hectorhammett Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

bshaffer Mar 18, 2026 •

edited

Loading

bshaffer Mar 18, 2026 •

edited

Loading

bshaffer Mar 18, 2026 •

edited

Loading

bshaffer Mar 18, 2026 •

edited

Loading

Hectorhammett Mar 18, 2026 •

edited

Loading