Merge branch 'main' into refactor-load-table-methods

Author: chalmerlowe

CHANGELOG.md

@@ -5,6 +5,31 @@
 [1]: https://pypi.org/project/google-cloud-bigquery/#history
 
 
+## [3.38.0](https://github.com/googleapis/python-bigquery/compare/v3.37.0...v3.38.0) (2025-09-15)
+
+
+### Features
+
+* Add additional query stats ([#2270](https://github.com/googleapis/python-bigquery/issues/2270)) ([7b1b718](https://github.com/googleapis/python-bigquery/commit/7b1b718123afd80c0f68212946e4179bcd6db67f))
+
+## [3.37.0](https://github.com/googleapis/python-bigquery/compare/v3.36.0...v3.37.0) (2025-09-08)
+
+
+### Features
+
+* Updates to fastpath query execution ([#2268](https://github.com/googleapis/python-bigquery/issues/2268)) ([ef2740a](https://github.com/googleapis/python-bigquery/commit/ef2740a158199633b5543a7b6eb19587580792cd))
+
+
+### Bug Fixes
+
+* Remove deepcopy while setting properties for _QueryResults ([#2280](https://github.com/googleapis/python-bigquery/issues/2280)) ([33ea296](https://github.com/googleapis/python-bigquery/commit/33ea29616c06a2e2a106a785d216e784737ae386))
+
+
+### Documentation
+
+* Clarify that the presence of `XyzJob.errors`  doesn't necessarily mean that the job has not completed or was unsuccessful ([#2278](https://github.com/googleapis/python-bigquery/issues/2278)) ([6e88d7d](https://github.com/googleapis/python-bigquery/commit/6e88d7dbe42ebfc35986da665d656b49ac481db4))
+* Clarify the api_method arg for client.query() ([#2277](https://github.com/googleapis/python-bigquery/issues/2277)) ([8a13c12](https://github.com/googleapis/python-bigquery/commit/8a13c12905ffcb3dbb6086a61df37556f0c2cd31))
+
 ## [3.36.0](https://github.com/googleapis/python-bigquery/compare/v3.35.1...v3.36.0) (2025-08-20)
 
 

google/cloud/bigquery/_job_helpers.py

@@ -658,6 +658,9 @@ def _supported_by_jobs_query(request_body: Dict[str, Any]) -> bool:
         "requestId",
         "createSession",
         "writeIncrementalResults",
+        "jobTimeoutMs",
+        "reservation",
+        "maxSlots",
     }
 
     unsupported_keys = request_keys - keys_allowlist

google/cloud/bigquery/client.py

@@ -3524,7 +3524,8 @@ def query(
                 specified here becomes the default ``job_retry`` for
                 ``result()``, where it can also be specified.
             api_method (Union[str, enums.QueryApiMethod]):
-                Method with which to start the query job.
+                Method with which to start the query job.  By default,
+                the jobs.insert API is used for starting a query.
 
                 See :class:`google.cloud.bigquery.enums.QueryApiMethod` for
                 details on the difference between the query start methods.

google/cloud/bigquery/job/__init__.py

@@ -39,6 +39,7 @@
 from google.cloud.bigquery.job.query import QueryPlanEntryStep
 from google.cloud.bigquery.job.query import ScriptOptions
 from google.cloud.bigquery.job.query import TimelineEntry
+from google.cloud.bigquery.job.query import IncrementalResultStats
 from google.cloud.bigquery.enums import Compression
 from google.cloud.bigquery.enums import CreateDisposition
 from google.cloud.bigquery.enums import DestinationFormat
@@ -84,4 +85,5 @@
     "SourceFormat",
     "TransactionInfo",
     "WriteDisposition",
+    "IncrementalResultStats",
 ]

google/cloud/bigquery/job/base.py

@@ -224,6 +224,37 @@ def job_timeout_ms(self, value):
         else:
             self._properties.pop("jobTimeoutMs", None)
 
+    @property
+    def max_slots(self) -> Optional[int]:
+        """The maximum rate of slot consumption to allow for this job.
+
+        If set, the number of slots used to execute the job will be throttled
+        to try and keep its slot consumption below the requested rate.
+        This feature is not generally available.
+        """
+
+        max_slots = self._properties.get("maxSlots")
+        if max_slots is not None:
+            if isinstance(max_slots, str):
+                return int(max_slots)
+            if isinstance(max_slots, int):
+                return max_slots
+        return None
+
+    @max_slots.setter
+    def max_slots(self, value):
+        try:
+            value = _int_or_none(value)
+        except ValueError as err:
+            raise ValueError("Pass an int for max slots, e.g. 100").with_traceback(
+                err.__traceback__
+            )
+
+        if value is not None:
+            self._properties["maxSlots"] = str(value)
+        else:
+            self._properties.pop("maxSlots", None)
+
     @property
     def reservation(self):
         """str: Optional. The reservation that job would use.
@@ -662,7 +693,12 @@ def transaction_info(self) -> Optional[TransactionInfo]:
 
     @property
     def error_result(self):
-        """Error information about the job as a whole.
+        """Output only. Final error result of the job.
+
+        If present, indicates that the job has completed and was unsuccessful.
+
+        See:
+        https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobStatus.FIELDS.error_result
 
         Returns:
             Optional[Mapping]: the error information (None until set from the server).
@@ -673,7 +709,13 @@ def error_result(self):
 
     @property
     def errors(self):
-        """Information about individual errors generated by the job.
+        """Output only. The first errors encountered during the running of the job.
+
+        The final message includes the number of errors that caused the process to stop.
+        Errors here do not necessarily mean that the job has not completed or was unsuccessful.
+
+        See:
+        https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobStatus.FIELDS.errors
 
         Returns:
             Optional[List[Mapping]]:
@@ -685,7 +727,12 @@ def errors(self):
 
     @property
     def state(self):
-        """Status of the job.
+        """Output only. Running state of the job.
+
+        Valid states include 'PENDING', 'RUNNING', and 'DONE'.
+
+        See:
+        https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobStatus.FIELDS.state
 
         Returns:
             Optional[str]:

google/cloud/bigquery/job/query.py

@@ -197,6 +197,66 @@ def from_api_repr(cls, stats: Dict[str, str]) -> "DmlStats":
         return cls(*args)
 
 
+class IncrementalResultStats:
+    """IncrementalResultStats provides information about incremental query execution."""
+
+    def __init__(self):
+        self._properties = {}
+
+    @classmethod
+    def from_api_repr(cls, resource) -> "IncrementalResultStats":
+        """Factory: construct instance from the JSON repr.
+
+        Args:
+            resource(Dict[str: object]):
+                IncrementalResultStats representation returned from API.
+
+        Returns:
+            google.cloud.bigquery.job.IncrementalResultStats:
+                stats parsed from ``resource``.
+        """
+        entry = cls()
+        entry._properties = resource
+        return entry
+
+    @property
+    def disabled_reason(self):
+        """Optional[string]: Reason why incremental results were not
+        written by the query.
+        """
+        return _helpers._str_or_none(self._properties.get("disabledReason"))
+
+    @property
+    def result_set_last_replace_time(self):
+        """Optional[datetime]: The time at which the result table's contents
+        were completely replaced.  May be absent if no results have been written
+        or the query has completed."""
+        from google.cloud._helpers import _rfc3339_nanos_to_datetime
+
+        value = self._properties.get("resultSetLastReplaceTime")
+        if value:
+            try:
+                return _rfc3339_nanos_to_datetime(value)
+            except ValueError:
+                pass
+        return None
+
+    @property
+    def result_set_last_modify_time(self):
+        """Optional[datetime]: The time at which the result table's contents
+        were modified. May be absent if no results have been written or the
+        query has completed."""
+        from google.cloud._helpers import _rfc3339_nanos_to_datetime
+
+        value = self._properties.get("resultSetLastModifyTime")
+        if value:
+            try:
+                return _rfc3339_nanos_to_datetime(value)
+            except ValueError:
+                pass
+        return None
+
+
 class IndexUnusedReason(typing.NamedTuple):
     """Reason about why no search index was used in the search query (or sub-query).
 
@@ -1339,6 +1399,13 @@ def bi_engine_stats(self) -> Optional[BiEngineStats]:
         else:
             return BiEngineStats.from_api_repr(stats)
 
+    @property
+    def incremental_result_stats(self) -> Optional[IncrementalResultStats]:
+        stats = self._job_statistics().get("incrementalResultStats")
+        if stats is None:
+            return None
+        return IncrementalResultStats.from_api_repr(stats)
+
     def _blocking_poll(self, timeout=None, **kwargs):
         self._done_timeout = timeout
         self._transport_timeout = timeout

google/cloud/bigquery/query.py

@@ -1400,7 +1400,7 @@ def _set_properties(self, api_response):
             api_response (Dict): Response returned from an API call
         """
         self._properties.clear()
-        self._properties.update(copy.deepcopy(api_response))
+        self._properties.update(api_response)
 
 
 def _query_param_from_api_repr(resource):

google/cloud/bigquery/table.py

@@ -3574,9 +3574,9 @@ def __init__(
     def __eq__(self, other):
         if not isinstance(other, TableConstraints) and other is not None:
             raise TypeError("The value provided is not a BigQuery TableConstraints.")
-        return (
-            self.primary_key == other.primary_key if other.primary_key else None
-        ) and (self.foreign_keys == other.foreign_keys if other.foreign_keys else None)
+        return self.primary_key == (
+            other.primary_key if other.primary_key else None
+        ) and self.foreign_keys == (other.foreign_keys if other.foreign_keys else None)
 
     @classmethod
     def from_api_repr(cls, resource: Dict[str, Any]) -> "TableConstraints":

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.36.0"
+__version__ = "3.38.0"

samples/desktopapp/requirements-test.txt

@@ -1,4 +1,4 @@
 google-cloud-testutils==1.6.4
-pytest==8.4.1
+pytest==8.4.2
 mock==5.2.0
 pytest-xdist==3.8.0