feat: add determinism level for javascript UDFs (#522)

* feat: add determinism level for javascript UDFs

* Add enum-like class for routine determinism level

docs/reference.rst

@@ -110,6 +110,7 @@ Routine
 .. autosummary::
     :toctree: generated
 
+    routine.DeterminismLevel
     routine.Routine
     routine.RoutineArgument
     routine.RoutineReference

google/cloud/bigquery/__init__.py

@@ -70,6 +70,7 @@
 from google.cloud.bigquery.query import StructQueryParameter
 from google.cloud.bigquery.query import UDFResource
 from google.cloud.bigquery.retry import DEFAULT_RETRY
+from google.cloud.bigquery.routine import DeterminismLevel
 from google.cloud.bigquery.routine import Routine
 from google.cloud.bigquery.routine import RoutineArgument
 from google.cloud.bigquery.routine import RoutineReference
@@ -134,6 +135,7 @@
     "Compression",
     "CreateDisposition",
     "DestinationFormat",
+    "DeterminismLevel",
     "ExternalSourceFormat",
     "Encoding",
     "QueryPriority",

google/cloud/bigquery/enums.py

@@ -234,3 +234,20 @@ class WriteDisposition(object):
     WRITE_EMPTY = "WRITE_EMPTY"
     """If the table already exists and contains data, a 'duplicate' error is
     returned in the job result."""
+
+
+class DeterminismLevel:
+    """Specifies determinism level for JavaScript user-defined functions (UDFs).
+
+    https://cloud.google.com/bigquery/docs/reference/rest/v2/routines#DeterminismLevel
+    """
+
+    DETERMINISM_LEVEL_UNSPECIFIED = "DETERMINISM_LEVEL_UNSPECIFIED"
+    """The determinism of the UDF is unspecified."""
+
+    DETERMINISTIC = "DETERMINISTIC"
+    """The UDF is deterministic, meaning that 2 function calls with the same inputs
+    always produce the same result, even across 2 query runs."""
+
+    NOT_DETERMINISTIC = "NOT_DETERMINISTIC"
+    """The UDF is not deterministic."""

google/cloud/bigquery/routine/__init__.py

@@ -0,0 +1,29 @@
+# Copyright 2021 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""User-Defined Routines."""
+
+
+from google.cloud.bigquery.enums import DeterminismLevel
+from google.cloud.bigquery.routine.routine import Routine
+from google.cloud.bigquery.routine.routine import RoutineArgument
+from google.cloud.bigquery.routine.routine import RoutineReference
+
+
+__all__ = (
+    "DeterminismLevel",
+    "Routine",
+    "RoutineArgument",
+    "RoutineReference",
+)

google/cloud/bigquery/routine.py → google/cloud/bigquery/routine/routine.py

@@ -50,6 +50,7 @@ class Routine(object):
         "return_type": "returnType",
         "type_": "routineType",
         "description": "description",
+        "determinism_level": "determinismLevel",
     }
 
     def __init__(self, routine_ref, **kwargs):
@@ -253,6 +254,17 @@ def description(self):
     def description(self, value):
         self._properties[self._PROPERTY_TO_API_FIELD["description"]] = value
 
+    @property
+    def determinism_level(self):
+        """Optional[str]: (experimental) The determinism level of the JavaScript UDF
+        if defined.
+        """
+        return self._properties.get(self._PROPERTY_TO_API_FIELD["determinism_level"])
+
+    @determinism_level.setter
+    def determinism_level(self, value):
+        self._properties[self._PROPERTY_TO_API_FIELD["determinism_level"]] = value
+
     @classmethod
     def from_api_repr(cls, resource):
         """Factory: construct a routine given its API representation.

tests/system/test_client.py

@@ -2682,6 +2682,7 @@ def test_create_routine(self):
             )
         ]
         routine.body = "return maxValue(arr)"
+        routine.determinism_level = bigquery.DeterminismLevel.DETERMINISTIC
         query_string = "SELECT `{}`([-100.0, 3.14, 100.0, 42.0]) as max_value;".format(
             str(routine.reference)
         )

tests/unit/routine/test_routine.py

@@ -18,6 +18,7 @@
 import pytest
 
 import google.cloud._helpers
+from google.cloud import bigquery
 from google.cloud import bigquery_v2
 
 
@@ -73,6 +74,7 @@ def test_ctor_w_properties(target_class):
     )
     type_ = "SCALAR_FUNCTION"
     description = "A routine description."
+    determinism_level = bigquery.DeterminismLevel.NOT_DETERMINISTIC
 
     actual_routine = target_class(
         routine_id,
@@ -82,6 +84,7 @@ def test_ctor_w_properties(target_class):
         return_type=return_type,
         type_=type_,
         description=description,
+        determinism_level=determinism_level,
     )
 
     ref = RoutineReference.from_string(routine_id)
@@ -92,6 +95,9 @@ def test_ctor_w_properties(target_class):
     assert actual_routine.return_type == return_type
     assert actual_routine.type_ == type_
     assert actual_routine.description == description
+    assert (
+        actual_routine.determinism_level == bigquery.DeterminismLevel.NOT_DETERMINISTIC
+    )
 
 
 def test_from_api_repr(target_class):
@@ -120,6 +126,7 @@ def test_from_api_repr(target_class):
         "routineType": "SCALAR_FUNCTION",
         "someNewField": "someValue",
         "description": "A routine description.",
+        "determinismLevel": bigquery.DeterminismLevel.DETERMINISTIC,
     }
     actual_routine = target_class.from_api_repr(resource)
 
@@ -152,6 +159,7 @@ def test_from_api_repr(target_class):
     assert actual_routine.type_ == "SCALAR_FUNCTION"
     assert actual_routine._properties["someNewField"] == "someValue"
     assert actual_routine.description == "A routine description."
+    assert actual_routine.determinism_level == "DETERMINISTIC"
 
 
 def test_from_api_repr_w_minimal_resource(target_class):
@@ -177,6 +185,7 @@ def test_from_api_repr_w_minimal_resource(target_class):
     assert actual_routine.return_type is None
     assert actual_routine.type_ is None
     assert actual_routine.description is None
+    assert actual_routine.determinism_level is None
 
 
 def test_from_api_repr_w_unknown_fields(target_class):
@@ -208,6 +217,7 @@ def test_from_api_repr_w_unknown_fields(target_class):
                 "returnType": {"typeKind": "INT64"},
                 "routineType": "SCALAR_FUNCTION",
                 "description": "A routine description.",
+                "determinismLevel": bigquery.DeterminismLevel.DETERMINISM_LEVEL_UNSPECIFIED,
             },
             ["arguments"],
             {"arguments": [{"name": "x", "dataType": {"typeKind": "INT64"}}]},
@@ -220,6 +230,7 @@ def test_from_api_repr_w_unknown_fields(target_class):
                 "returnType": {"typeKind": "INT64"},
                 "routineType": "SCALAR_FUNCTION",
                 "description": "A routine description.",
+                "determinismLevel": bigquery.DeterminismLevel.DETERMINISM_LEVEL_UNSPECIFIED,
             },
             ["body"],
             {"definitionBody": "x * 3"},
@@ -232,6 +243,7 @@ def test_from_api_repr_w_unknown_fields(target_class):
                 "returnType": {"typeKind": "INT64"},
                 "routineType": "SCALAR_FUNCTION",
                 "description": "A routine description.",
+                "determinismLevel": bigquery.DeterminismLevel.DETERMINISM_LEVEL_UNSPECIFIED,
             },
             ["language"],
             {"language": "SQL"},
@@ -244,6 +256,7 @@ def test_from_api_repr_w_unknown_fields(target_class):
                 "returnType": {"typeKind": "INT64"},
                 "routineType": "SCALAR_FUNCTION",
                 "description": "A routine description.",
+                "determinismLevel": bigquery.DeterminismLevel.DETERMINISM_LEVEL_UNSPECIFIED,
             },
             ["return_type"],
             {"returnType": {"typeKind": "INT64"}},
@@ -256,6 +269,7 @@ def test_from_api_repr_w_unknown_fields(target_class):
                 "returnType": {"typeKind": "INT64"},
                 "routineType": "SCALAR_FUNCTION",
                 "description": "A routine description.",
+                "determinismLevel": bigquery.DeterminismLevel.DETERMINISM_LEVEL_UNSPECIFIED,
             },
             ["type_"],
             {"routineType": "SCALAR_FUNCTION"},
@@ -268,20 +282,45 @@ def test_from_api_repr_w_unknown_fields(target_class):
                 "returnType": {"typeKind": "INT64"},
                 "routineType": "SCALAR_FUNCTION",
                 "description": "A routine description.",
+                "determinismLevel": bigquery.DeterminismLevel.DETERMINISM_LEVEL_UNSPECIFIED,
             },
             ["description"],
             {"description": "A routine description."},
         ),
+        (
+            {
+                "arguments": [{"name": "x", "dataType": {"typeKind": "INT64"}}],
+                "definitionBody": "x * 3",
+                "language": "SQL",
+                "returnType": {"typeKind": "INT64"},
+                "routineType": "SCALAR_FUNCTION",
+                "description": "A routine description.",
+                "determinismLevel": bigquery.DeterminismLevel.DETERMINISM_LEVEL_UNSPECIFIED,
+            },
+            ["determinism_level"],
+            {
+                "determinismLevel": bigquery.DeterminismLevel.DETERMINISM_LEVEL_UNSPECIFIED
+            },
+        ),
         (
             {},
-            ["arguments", "language", "body", "type_", "return_type", "description"],
+            [
+                "arguments",
+                "language",
+                "body",
+                "type_",
+                "return_type",
+                "description",
+                "determinism_level",
+            ],
             {
                 "arguments": None,
                 "definitionBody": None,
                 "language": None,
                 "returnType": None,
                 "routineType": None,
                 "description": None,
+                "determinismLevel": None,
             },
         ),
         (