feat(bigquery): Add script statistics to job resource.

Author: tswast

bigquery/google/cloud/bigquery/job.py

@@ -344,6 +344,15 @@ def parent_job_id(self):
         """
         return _helpers._get_sub_prop(self._properties, ["statistics", "parentJobId"])
 
+    @property
+    def script_statistics(self):
+        resource = _helpers._get_sub_prop(
+            self._properties, ["statistics", "scriptStatistics"]
+        )
+        if resource is None:
+            return None
+        return ScriptStatistics(resource)
+
     @property
     def num_child_jobs(self):
         """The number of child jobs executed.
@@ -3456,3 +3465,82 @@ def from_api_repr(cls, resource, client):
         resource["jobReference"] = job_ref_properties
         job._properties = resource
         return job
+
+
+class ScriptStackFrame(object):
+    """Stack frame showing the line/column/procedure name where the current
+    evaluation happened.
+
+    Args:
+        resource (Map[str, Any]):
+            JSON representation of object.
+    """
+
+    def __init__(self, resource):
+        self._properties = resource
+
+    @property
+    def procedure_id(self):
+        """str: Name of the active procedure, empty if in a top-level
+        script.
+        """
+        return self._properties.get("procedureId")
+
+    @property
+    def text(self):
+        """str: Text of the current statement/expression."""
+        return self._properties.get("text")
+
+    @property
+    def start_line(self):
+        """int: One-based start line."""
+        return _helpers._int_or_none(self._properties.get("startLine"))
+
+    @property
+    def start_column(self):
+        """int: One-based start column."""
+        return _helpers._int_or_none(self._properties.get("startColumn"))
+
+    @property
+    def end_line(self):
+        """int: One-based end line."""
+        return _helpers._int_or_none(self._properties.get("endLine"))
+
+    @property
+    def end_column(self):
+        """int: One-based end column."""
+        return _helpers._int_or_none(self._properties.get("endColumn"))
+
+
+class ScriptStatistics(object):
+    """Statistics for a child job of a script.
+
+    Args:
+        resource (Map[str, Any]):
+            JSON representation of object.
+    """
+
+    def __init__(self, resource):
+        self._properties = resource
+
+    @property
+    def stack_frames(self):
+        """List[ScriptStackFrame]: Stack trace where the current evaluation
+        happened.
+
+        Shows line/column/procedure name of each frame on the stack at the
+        point where the current evaluation happened.
+
+        The leaf frame is first, the primary script is last.
+        """
+        return [
+            ScriptStackFrame(frame) for frame in self._properties.get("stackFrames", [])
+        ]
+
+    @property
+    def evaluation_kind(self):
+        """str: Indicates the type of child job.
+
+        Possible values include ``STATEMENT`` and ``EXPRESSION``.
+        """
+        return self._properties.get("evaluationKind")

bigquery/tests/unit/test_job.py

@@ -276,6 +276,46 @@ def test_parent_job_id(self):
         job._properties["statistics"] = {"parentJobId": "parent-job-123"}
         self.assertEqual(job.parent_job_id, "parent-job-123")
 
+    def test_script_statistics(self):
+        client = _make_client(project=self.PROJECT)
+        job = self._make_one(self.JOB_ID, client)
+
+        self.assertIsNone(job.script_statistics)
+        job._properties["statistics"] = {
+            "scriptStatistics": {
+                "evaluationKind": "EXPRESSION",
+                "stackFrames": [
+                    {
+                        "procedureId": "some-procedure",
+                        "startLine": 5,
+                        "startColumn": 29,
+                        "endLine": 9,
+                        "endColumn": 14,
+                        "text": "QUERY TEXT",
+                    },
+                    {},
+                ],
+            }
+        }
+        script_stats = job.script_statistics
+        self.assertEqual(script_stats.evaluation_kind, "EXPRESSION")
+        stack_frames = script_stats.stack_frames
+        self.assertEqual(len(stack_frames), 2)
+        stack_frame = stack_frames[0]
+        self.assertEqual(stack_frame.procedure_id, "some-procedure")
+        self.assertEqual(stack_frame.start_line, 5)
+        self.assertEqual(stack_frame.start_column, 29)
+        self.assertEqual(stack_frame.end_line, 9)
+        self.assertEqual(stack_frame.end_column, 14)
+        self.assertEqual(stack_frame.text, "QUERY TEXT")
+        stack_frame = stack_frames[1]
+        self.assertIsNone(stack_frame.procedure_id)
+        self.assertIsNone(stack_frame.start_line)
+        self.assertIsNone(stack_frame.start_column)
+        self.assertIsNone(stack_frame.end_line)
+        self.assertIsNone(stack_frame.end_column)
+        self.assertIsNone(stack_frame.text)
+
     def test_num_child_jobs(self):
         client = _make_client(project=self.PROJECT)
         job = self._make_one(self.JOB_ID, client)