feat: adds null_markers as a load and external_config option

Author: chalmerlowe

google/cloud/bigquery/external_config.py

@@ -476,7 +476,15 @@ def skip_leading_rows(self, value):
 
     @property
     def null_markers(self) -> Optional[Iterable[str]]:
-        """Optional[Iterable[str]]: The strings that are interpreted as NULL values.
+        """Optional[Iterable[str]]: A list of strings represented as SQL NULL values in a CSV file.
+
+        .. note::
+            null_marker and null_markers can't be set at the same time.
+            If null_marker is set, null_markers has to be not set.
+            If null_markers is set, null_marker has to be not set.
+            If both null_marker and null_markers are set at the same time, a user error would be thrown.
+            Any strings listed in null_markers, including empty string would be interpreted as SQL NULL.
+            This applies to all column types.
 
         See
         https://cloud.google.com/bigquery/docs/reference/rest/v2/tables#CsvOptions.FIELDS.null_markers

google/cloud/bigquery/job/load.py

@@ -388,7 +388,15 @@ def null_marker(self, value):
 
     @property
     def null_markers(self) -> Optional[List[str]]:
-        """Optional[List[str]]: Represents a null value (CSV only).
+        """Optional[List[str]]: A list of strings represented as SQL NULL values in a CSV file.
+
+        .. note::
+            null_marker and null_markers can't be set at the same time.
+            If null_marker is set, null_markers has to be not set.
+            If null_markers is set, null_marker has to be not set.
+            If both null_marker and null_markers are set at the same time, a user error would be thrown.
+            Any strings listed in null_markers, including empty string would be interpreted as SQL NULL.
+            This applies to all column types.
 
         See:
         https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad.FIELDS.null_markers

tests/unit/job/test_load.py

@@ -42,6 +42,7 @@ def _setUpConstants(self):
         self.TIME_ZONE = "UTC"
         self.TIME_FORMAT = "%H:%M:%S"
         self.TIMESTAMP_FORMAT = "YYYY-MM-DD HH:MM:SS.SSSSSSZ"
+        self.NULL_MARKERS = ["", "NA"]
 
     def _make_resource(self, started=False, ended=False):
         resource = super(TestLoadJob, self)._make_resource(started, ended)
@@ -52,6 +53,7 @@ def _make_resource(self, started=False, ended=False):
         config["timeZone"] = self.TIME_ZONE
         config["timeFormat"] = self.TIME_FORMAT
         config["timestampFormat"] = self.TIMESTAMP_FORMAT
+        config["nullMarkers"] = self.NULL_MARKERS
 
         config["destinationTable"] = {
             "projectId": self.PROJECT,
@@ -215,6 +217,7 @@ def test_ctor(self):
         self.assertIsNone(job.ignore_unknown_values)
         self.assertIsNone(job.max_bad_records)
         self.assertIsNone(job.null_marker)
+        self.assertIsNone(job.null_markers)
         self.assertIsNone(job.quote_character)
         self.assertIsNone(job.skip_leading_rows)
         self.assertIsNone(job.source_format)