Merge branch 'main' into start-index-2

Author: Linchin

.github/workflows/docs.yml

@@ -0,0 +1,39 @@
+on:
+  pull_request:
+    branches:
+      - main
+name: docs
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+    - name: Setup Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.10'
+    - name: Install nox
+      run: |
+        python -m pip install --upgrade setuptools pip wheel
+        python -m pip install nox
+    - name: Run docs session
+      run: |
+        nox -s docs-3.10
+
+  docfx:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+    - name: Setup Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.10'
+    - name: Install nox
+      run: |
+        python -m pip install --upgrade setuptools pip wheel
+        python -m pip install nox
+    - name: Run docfx session
+      run: |
+        nox -s docfx-3.10

.kokoro/presubmit/presubmit.cfg

@@ -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)
 
 

CHANGELOG.md

@@ -388,7 +388,7 @@ def range_to_py(self, value, field):
 
 
 class DataFrameCellDataParser(CellDataParser):
-    """Override of CellDataParser to handle differences in expection of values in DataFrame-like outputs.
+    """Override of CellDataParser to handle differences in expression of values in DataFrame-like outputs.
 
     This is used to turn the output of the REST API into a pyarrow Table,
     emulating the serialized arrow from the BigQuery Storage Read API.

google/cloud/bigquery/_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/_job_helpers.py

@@ -1144,7 +1144,7 @@ def determine_requested_streams(
     """
 
     if preserve_order:
-        # If preserve order is set, it takes precendence.
+        # If preserve order is set, it takes precedence.
         # Limit the requested streams to 1, to ensure that order
         # is preserved)
         return 1

google/cloud/bigquery/_pandas_helpers.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``.
@@ -3539,13 +3554,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
@@ -4141,7 +4149,7 @@ def _list_rows_from_query_results(
                 rows that were affected.
             query (Optional[str]):
                 The query text used.
-            total_bytes_processed (Optinal[int]):
+            total_bytes_processed (Optional[int]):
                 total bytes processed from job statistics, if present.
 
         Returns:

google/cloud/bigquery/client.py

@@ -407,3 +407,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/enums.py

@@ -1534,7 +1534,7 @@ def result(  # type: ignore  # (incompatible with supertype)
                 a DDL query, an ``_EmptyRowIterator`` instance is returned.
 
         Raises:
-            google.cloud.exceptions.GoogleAPICallError:
+            google.api_core.exceptions.GoogleAPICallError:
                 If the job failed and retries aren't successful.
             concurrent.futures.TimeoutError:
                 If the job did not complete in the given timeout.

google/cloud/bigquery/job/query.py

@@ -44,7 +44,7 @@
     import geopandas  # type: ignore
 except ImportError:
     geopandas = None
-else:
+finally:
     _COORDINATE_REFERENCE_SYSTEM = "EPSG:4326"
 
 try:
@@ -1786,7 +1786,7 @@ class RowIterator(HTTPIterator):
             the first page is requested.
         query (Optional[str]):
             The query text used.
-        total_bytes_processed (Optinal[int]):
+        total_bytes_processed (Optional[int]):
             total bytes processed from job statistics, if present.
     """