feat: search statistics

google/cloud/bigquery/job/query.py

@@ -198,6 +198,39 @@ def from_api_repr(cls, stats: Dict[str, str]) -> "DmlStats":
         return cls(*args)
 
 
+class SearchReason(typing.NamedTuple):
+    """docstring"""
+
+    code: str
+    message: str
+    baseTable: TableReference
+    indexName: str
+
+    @classmethod
+    def from_api_repr(cls, reason):
+        code = reason.get("code")
+        message = reason.get("message")
+        baseTable = reason.get("baseTable")
+        indexName = reason.get("indexName")
+
+        return cls(code, message, baseTable, indexName)
+
+
+class SearchStats(typing.NamedTuple):
+    """docstring"""
+
+    mode: str
+    reason: list
+
+    @classmethod
+    def from_api_repr(cls, stats: Dict[str, Any]):
+        mode = stats.get("indexUsageMode", "INDEX_USAGE_MODE_UNSPECIFIED")
+        reason = [
+            SearchReason.from_api_repr(r) for r in stats.get("indexUnusedReasons")
+        ]
+        return cls(mode, reason)
+
+
 class ScriptOptions:
     """Options controlling the execution of scripts.
 
@@ -724,7 +757,6 @@ def to_api_repr(self) -> dict:
             Dict: A dictionary in the format used by the BigQuery API.
         """
         resource = copy.deepcopy(self._properties)
-
         # Query parameters have an addition property associated with them
         # to indicate if the query is using named or positional parameters.
         query_parameters = resource["query"].get("queryParameters")
@@ -858,6 +890,13 @@ def priority(self):
         """
         return self.configuration.priority
 
+    @property
+    def search_stats(self):
+        """docstring"""
+
+        stats = self._job_statistics().get("searchStatistics")
+        return SearchStats.from_api_repr(stats)
+
     @property
     def query(self):
         """str: The query text used in this query job.