feat: support timestamp_precision in table schema

google/cloud/bigquery/enums.py

@@ -480,3 +480,18 @@ class SourceColumnMatch(str, enum.Enum):
     NAME = "NAME"
     """Matches by name. This reads the header row as column names and reorders
     columns to match the field names in the schema."""
+
+
+class TimestampPrecision(object):
+    """Precision (maximum number of total digits in base 10) for seconds of
+    TIMESTAMP type."""
+
+    MICROSECOND = None
+    """
+    Default, for TIMESTAMP type with microsecond precision.
+    """
+
+    PICOSECOND = 12
+    """
+    For TIMESTAMP type with picosecond precision.
+    """

google/cloud/bigquery/schema.py

@@ -196,6 +196,14 @@ class SchemaField(object):
 
             Only valid for top-level schema fields (not nested fields).
             If the type is FOREIGN, this field is required.
+
+        timestamp_precision: Union[enums.TimestampPrecision, int, None]
+            Precision (maximum number of total digits in base 10) for seconds
+            of TIMESTAMP type.
+
+            Defaults to `enums.TimestampPrecision.MICROSECOND` (`None`) for
+            microsecond precision. Use `enums.TimestampPrecision.PICOSECOND`
+            (`12`) for picosecond precision.
     """
 
     def __init__(
@@ -213,6 +221,7 @@ def __init__(
         range_element_type: Union[FieldElementType, str, None] = None,
         rounding_mode: Union[enums.RoundingMode, str, None] = None,
         foreign_type_definition: Optional[str] = None,
+        timestamp_precision: Union[enums.TimestampPrecision, int, None] = None,
     ):
         self._properties: Dict[str, Any] = {
             "name": name,
@@ -237,6 +246,8 @@ def __init__(
                 if isinstance(policy_tags, PolicyTagList)
                 else None
             )
+        if timestamp_precision is not None:
+            self._properties["timestampPrecision"] = timestamp_precision
         if isinstance(range_element_type, str):
             self._properties["rangeElementType"] = {"type": range_element_type}
         if isinstance(range_element_type, FieldElementType):
@@ -374,6 +385,13 @@ def policy_tags(self):
         resource = self._properties.get("policyTags")
         return PolicyTagList.from_api_repr(resource) if resource is not None else None
 
+    @property
+    def timestamp_precision(self):
+        """Union[enums.TimestampPrecision, int, None]: Precision (maximum number
+        of total digits in base 10) for seconds of TIMESTAMP type.
+        """
+        return _helpers._int_or_none(self._properties.get("timestampPrecision"))
+
     def to_api_repr(self) -> dict:
         """Return a dictionary representing this schema field.
 
@@ -417,6 +435,7 @@ def _key(self):
             self.description,
             self.fields,
             policy_tags,
+            self.timestamp_precision,
         )
 
     def to_standard_sql(self) -> standard_sql.StandardSqlField:
@@ -467,10 +486,9 @@ def __hash__(self):
         return hash(self._key())
 
     def __repr__(self):
-        key = self._key()
-        policy_tags = key[-1]
+        *initial_tags, policy_tags, timestamp_precision_tag = self._key()
         policy_tags_inst = None if policy_tags is None else PolicyTagList(policy_tags)
-        adjusted_key = key[:-1] + (policy_tags_inst,)
+        adjusted_key = (*initial_tags, policy_tags_inst, timestamp_precision_tag)
         return f"{self.__class__.__name__}{adjusted_key}"
 
 

tests/system/test_client.py

@@ -74,6 +74,16 @@
     bigquery.SchemaField("full_name", "STRING", mode="REQUIRED"),
     bigquery.SchemaField("age", "INTEGER", mode="REQUIRED"),
 ]
+SCHEMA_PICOSECOND = [
+    bigquery.SchemaField("full_name", "STRING", mode="REQUIRED"),
+    bigquery.SchemaField("age", "INTEGER", mode="REQUIRED"),
+    bigquery.SchemaField(
+        "time_pico",
+        "TIMESTAMP",
+        mode="REQUIRED",
+        timestamp_precision=enums.TimestampPrecision.PICOSECOND,
+    ),
+]
 CLUSTERING_SCHEMA = [
     bigquery.SchemaField("full_name", "STRING", mode="REQUIRED"),
     bigquery.SchemaField("age", "INTEGER", mode="REQUIRED"),
@@ -631,6 +641,19 @@ def test_create_table_w_time_partitioning_w_clustering_fields(self):
         self.assertEqual(time_partitioning.field, "transaction_time")
         self.assertEqual(table.clustering_fields, ["user_email", "store_code"])
 
+    def test_create_table_w_picosecond_timestamp(self):
+        dataset = self.temp_dataset(_make_dataset_id("create_table"))
+        table_id = "test_table"
+        table_arg = Table(dataset.table(table_id), schema=SCHEMA_PICOSECOND)
+        self.assertFalse(_table_exists(table_arg))
+
+        table = helpers.retry_403(Config.CLIENT.create_table)(table_arg)
+        self.to_delete.insert(0, table)
+
+        self.assertTrue(_table_exists(table))
+        self.assertEqual(table.table_id, table_id)
+        self.assertEqual(table.schema, SCHEMA_PICOSECOND)
+
     def test_delete_dataset_with_string(self):
         dataset_id = _make_dataset_id("delete_table_true_with_string")
         project = Config.CLIENT.project

tests/unit/test_schema.py

@@ -69,6 +69,7 @@ def test_constructor_explicit(self):
             default_value_expression=FIELD_DEFAULT_VALUE_EXPRESSION,
             rounding_mode=enums.RoundingMode.ROUNDING_MODE_UNSPECIFIED,
             foreign_type_definition="INTEGER",
+            timestamp_precision=enums.TimestampPrecision.PICOSECOND,
         )
         self.assertEqual(field.name, "test")
         self.assertEqual(field.field_type, "STRING")
@@ -87,6 +88,10 @@ def test_constructor_explicit(self):
         )
         self.assertEqual(field.rounding_mode, "ROUNDING_MODE_UNSPECIFIED")
         self.assertEqual(field.foreign_type_definition, "INTEGER")
+        self.assertEqual(
+            field._properties["timestampPrecision"],
+            enums.TimestampPrecision.PICOSECOND,
+        )
 
     def test_constructor_explicit_none(self):
         field = self._make_one("test", "STRING", description=None, policy_tags=None)
@@ -189,6 +194,23 @@ def test_to_api_repr_with_subfield(self):
                 },
             )
 
+    def test_to_api_repr_w_timestamp_precision(self):
+        field = self._make_one(
+            "foo",
+            "TIMESTAMP",
+            "NULLABLE",
+            timestamp_precision=enums.TimestampPrecision.PICOSECOND,
+        )
+        self.assertEqual(
+            field.to_api_repr(),
+            {
+                "mode": "NULLABLE",
+                "name": "foo",
+                "type": "TIMESTAMP",
+                "timestampPrecision": enums.TimestampPrecision.PICOSECOND,
+            },
+        )
+
     def test_from_api_repr(self):
         field = self._get_target_class().from_api_repr(
             {
@@ -198,6 +220,7 @@ def test_from_api_repr(self):
                 "name": "foo",
                 "type": "record",
                 "roundingMode": "ROUNDING_MODE_UNSPECIFIED",
+                "timestampPrecision": enums.TimestampPrecision.PICOSECOND,
             }
         )
         self.assertEqual(field.name, "foo")
@@ -210,6 +233,10 @@ def test_from_api_repr(self):
         self.assertEqual(field.fields[0].mode, "NULLABLE")
         self.assertEqual(field.range_element_type, None)
         self.assertEqual(field.rounding_mode, "ROUNDING_MODE_UNSPECIFIED")
+        self.assertEqual(
+            field._properties["timestampPrecision"],
+            enums.TimestampPrecision.PICOSECOND,
+        )
 
     def test_from_api_repr_policy(self):
         field = self._get_target_class().from_api_repr(
@@ -323,6 +350,12 @@ def test_foreign_type_definition_property_str(self):
         schema_field._properties["foreignTypeDefinition"] = FOREIGN_TYPE_DEFINITION
         self.assertEqual(schema_field.foreign_type_definition, FOREIGN_TYPE_DEFINITION)
 
+    def test_timestamp_precision_property(self):
+        TIMESTAMP_PRECISION = enums.TimestampPrecision.PICOSECOND
+        schema_field = self._make_one("test", "TIMESTAMP")
+        schema_field._properties["timestampPrecision"] = TIMESTAMP_PRECISION
+        self.assertEqual(schema_field.timestamp_precision, TIMESTAMP_PRECISION)
+
     def test_to_standard_sql_simple_type(self):
         examples = (
             # a few legacy types
@@ -637,7 +670,9 @@ def test___hash__not_equals(self):
 
     def test___repr__(self):
         field1 = self._make_one("field1", "STRING")
-        expected = "SchemaField('field1', 'STRING', 'NULLABLE', None, None, (), None)"
+        expected = (
+            "SchemaField('field1', 'STRING', 'NULLABLE', None, None, (), None, None)"
+        )
         self.assertEqual(repr(field1), expected)
 
     def test___repr__evaluable_no_policy_tags(self):