Merge branch 'main' into feat-dataset-view

Author: chalmerlowe

CHANGELOG.md

@@ -5,6 +5,24 @@
 [1]: https://pypi.org/project/google-cloud-bigquery/#history
 
 
+## [3.34.0](https://github.com/googleapis/python-bigquery/compare/v3.33.0...v3.34.0) (2025-05-27)
+
+
+### Features
+
+* Job creation mode GA ([#2190](https://github.com/googleapis/python-bigquery/issues/2190)) ([64cd39f](https://github.com/googleapis/python-bigquery/commit/64cd39fb395c4a03ef6d2ec8261e1709477b2186))
+
+
+### Bug Fixes
+
+* **deps:** Update all dependencies ([#2184](https://github.com/googleapis/python-bigquery/issues/2184)) ([12490f2](https://github.com/googleapis/python-bigquery/commit/12490f2f03681516465fc34217dcdf57000f6fdd))
+
+
+### Documentation
+
+* Update query.py ([#2192](https://github.com/googleapis/python-bigquery/issues/2192)) ([9b5ee78](https://github.com/googleapis/python-bigquery/commit/9b5ee78f046d9ca3f758eeca6244b8485fe35875))
+* Use query_and_wait in the array parameters sample ([#2202](https://github.com/googleapis/python-bigquery/issues/2202)) ([28a9994](https://github.com/googleapis/python-bigquery/commit/28a9994792ec90a6a4d16835faf2137c09c0fb02))
+
 ## [3.33.0](https://github.com/googleapis/python-bigquery/compare/v3.32.0...v3.33.0) (2025-05-19)
 
 

google/cloud/bigquery/_job_helpers.py

@@ -37,7 +37,6 @@
 
 import copy
 import functools
-import os
 import uuid
 import textwrap
 from typing import Any, Dict, Optional, TYPE_CHECKING, Union
@@ -400,12 +399,6 @@ def query_and_wait(
 ) -> table.RowIterator:
     """Run the query, wait for it to finish, and return the results.
 
-    While ``jobCreationMode=JOB_CREATION_OPTIONAL`` is in preview in the
-    ``jobs.query`` REST API, use the default ``jobCreationMode`` unless
-    the environment variable ``QUERY_PREVIEW_ENABLED=true``. After
-    ``jobCreationMode`` is GA, this method will always use
-    ``jobCreationMode=JOB_CREATION_OPTIONAL``. See:
-    https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs/query
 
     Args:
         client:
@@ -500,9 +493,8 @@ def query_and_wait(
         request_body["maxResults"] = min(page_size, max_results)
     elif page_size is not None or max_results is not None:
         request_body["maxResults"] = page_size or max_results
-
-    if os.getenv("QUERY_PREVIEW_ENABLED", "").casefold() == "true":
-        request_body["jobCreationMode"] = "JOB_CREATION_OPTIONAL"
+    if client.default_job_creation_mode:
+        request_body["jobCreationMode"] = client.default_job_creation_mode
 
     def do_query():
         request_body["requestId"] = make_job_id()

google/cloud/bigquery/client.py

@@ -221,6 +221,10 @@ class Client(ClientWithProject):
         client_options (Optional[Union[google.api_core.client_options.ClientOptions, Dict]]):
             Client options used to set user options on the client. API Endpoint
             should be set through client_options.
+        default_job_creation_mode (Optional[str]):
+            Sets the default job creation mode used by query methods such as
+            query_and_wait().  For lightweight queries, JOB_CREATION_OPTIONAL is
+            generally recommended.
 
     Raises:
         google.auth.exceptions.DefaultCredentialsError:
@@ -243,6 +247,7 @@ def __init__(
         client_options: Optional[
             Union[google.api_core.client_options.ClientOptions, Dict[str, Any]]
         ] = None,
+        default_job_creation_mode: Optional[str] = None,
     ) -> None:
         if client_options is None:
             client_options = {}
@@ -277,6 +282,7 @@ def __init__(
         self._connection = Connection(self, **kw_args)
         self._location = location
         self._default_load_job_config = copy.deepcopy(default_load_job_config)
+        self.default_job_creation_mode = default_job_creation_mode
 
         # Use property setter so validation can run.
         self.default_query_job_config = default_query_job_config
@@ -286,6 +292,15 @@ def location(self):
         """Default location for jobs / datasets / tables."""
         return self._location
 
+    @property
+    def default_job_creation_mode(self):
+        """Default job creation mode used for query execution."""
+        return self._default_job_creation_mode
+
+    @default_job_creation_mode.setter
+    def default_job_creation_mode(self, value: Optional[str]):
+        self._default_job_creation_mode = value
+
     @property
     def default_query_job_config(self) -> Optional[QueryJobConfig]:
         """Default ``QueryJobConfig`` or ``None``.
@@ -3554,13 +3569,6 @@ def query_and_wait(
     ) -> RowIterator:
         """Run the query, wait for it to finish, and return the results.
 
-        While ``jobCreationMode=JOB_CREATION_OPTIONAL`` is in preview in the
-        ``jobs.query`` REST API, use the default ``jobCreationMode`` unless
-        the environment variable ``QUERY_PREVIEW_ENABLED=true``. After
-        ``jobCreationMode`` is GA, this method will always use
-        ``jobCreationMode=JOB_CREATION_OPTIONAL``. See:
-        https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs/query
-
         Args:
             query (str):
                 SQL query to be executed. Defaults to the standard SQL

google/cloud/bigquery/enums.py

@@ -425,3 +425,22 @@ class BigLakeTableFormat(object):
 
     ICEBERG = "ICEBERG"
     """Apache Iceberg format."""
+
+
+class JobCreationMode(object):
+    """Documented values for Job Creation Mode."""
+
+    JOB_CREATION_MODE_UNSPECIFIED = "JOB_CREATION_MODE_UNSPECIFIED"
+    """Job creation mode is unspecified."""
+
+    JOB_CREATION_REQUIRED = "JOB_CREATION_REQUIRED"
+    """Job creation is always required."""
+
+    JOB_CREATION_OPTIONAL = "JOB_CREATION_OPTIONAL"
+    """Job creation is optional.
+
+    Returning immediate results is prioritized.
+    BigQuery will automatically determine if a Job needs to be created.
+    The conditions under which BigQuery can decide to not create a Job are
+    subject to change.
+    """

google/cloud/bigquery/version.py

@@ -12,4 +12,4 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-__version__ = "3.33.0"
+__version__ = "3.34.0"

samples/client_query_shortmode.py samples/client_query_job_optional.pysamples/client_query_shortmode.py renamed to samples/client_query_job_optional.py

@@ -13,16 +13,18 @@
 # limitations under the License.
 
 
-def client_query_shortmode() -> None:
-    # [START bigquery_query_shortquery]
-    # This example demonstrates issuing a query that may be run in short query mode.
-    #
-    # To enable the short query mode preview feature, the QUERY_PREVIEW_ENABLED
-    # environmental variable should be set to `TRUE`.
+def client_query_job_optional() -> None:
+    # [START bigquery_query_job_optional]
+    # This example demonstrates executing a query without requiring an associated
+    # job.
     from google.cloud import bigquery
+    from google.cloud.bigquery.enums import JobCreationMode
 
-    # Construct a BigQuery client object.
-    client = bigquery.Client()
+    # Construct a BigQuery client object, specifying that the library should
+    # avoid creating jobs when possible.
+    client = bigquery.Client(
+        default_job_creation_mode=JobCreationMode.JOB_CREATION_OPTIONAL
+    )
 
     query = """
         SELECT
@@ -44,10 +46,12 @@ def client_query_shortmode() -> None:
     if rows.job_id is not None:
         print("Query was run with job state.  Job ID: {}".format(rows.job_id))
     else:
-        print("Query was run in short mode.  Query ID: {}".format(rows.query_id))
+        print(
+            "Query was run without creating a job.  Query ID: {}".format(rows.query_id)
+        )
 
     print("The query data:")
     for row in rows:
         # Row values can be accessed by field name or index.
         print("name={}, gender={}, total={}".format(row[0], row[1], row["total"]))
-    # [END bigquery_query_shortquery]
+    # [END bigquery_query_job_optional]

samples/client_query_w_array_params.py

@@ -35,8 +35,8 @@ def client_query_w_array_params() -> None:
             bigquery.ArrayQueryParameter("states", "STRING", ["WA", "WI", "WV", "WY"]),
         ]
     )
-    query_job = client.query(query, job_config=job_config)  # Make an API request.
+    rows = client.query_and_wait(query, job_config=job_config)  # Make an API request.
 
-    for row in query_job:
+    for row in rows:
         print("{}: \t{}".format(row.name, row.count))
     # [END bigquery_query_params_arrays]

samples/desktopapp/requirements-test.txt

@@ -1,4 +1,4 @@
 google-cloud-testutils==1.6.4
 pytest==8.3.5
 mock==5.2.0
-pytest-xdist==3.6.1
+pytest-xdist==3.7.0

samples/geography/requirements-test.txt

@@ -1,3 +1,3 @@
 pytest==8.3.5
 mock==5.2.0
-pytest-xdist==3.6.1
+pytest-xdist==3.7.0

samples/magics/requirements-test.txt

@@ -1,4 +1,4 @@
 google-cloud-testutils==1.6.4
 pytest==8.3.5
 mock==5.2.0
-pytest-xdist==3.6.1
+pytest-xdist==3.7.0