Disable query when tag is None in TsFileDataFrame

python/tests/test_tsfile_dataset.py

@@ -819,6 +819,44 @@ def query_table_by_row(self, *args, **kwargs):
         reader.read_series_by_row(device_id, 0, 0, 2)
 
 
+def test_dataframe_rejects_null_tag_values_during_metadata_load(tmp_path, monkeypatch):
+    class _FakeSeriesReader:
+        def __init__(self, file_path, show_progress=True):
+            self.file_path = file_path
+            self.show_progress = show_progress
+            self._catalog = MetadataCatalog()
+            table_id = self._catalog.add_table(
+                "weather",
+                ("city", "device"),
+                (TSDataType.STRING, TSDataType.STRING),
+                ("temperature",),
+            )
+            self._catalog.add_device(table_id, ("beijing", None), 0, 1)
+
+        @property
+        def catalog(self):
+            return self._catalog
+
+        @property
+        def series_count(self):
+            return 1
+
+        def close(self):
+            pass
+
+    file_path = tmp_path / "null_tag.tsfile"
+    file_path.touch()
+    monkeypatch.setattr("tsfile.dataset.reader.TsFileSeriesReader", _FakeSeriesReader)
+
+    with pytest.raises(NotImplementedError) as exc_info:
+        TsFileDataFrame(str(file_path), show_progress=False)
+
+    message = str(exc_info.value)
+    assert "NULL TAG values" in message
+    assert "weather" in message
+    assert "device" in message
+
+
 def test_dataframe_resolves_named_sparse_tag_series_path():
     tsdf = object.__new__(TsFileDataFrame)
     tsdf._index = dataframe_module._LogicalIndex()

python/tsfile/dataset/dataframe.py

@@ -139,6 +139,22 @@ def _validate_table_schema(existing: TableEntry, incoming: TableEntry, file_path
     )
 
 
+def _ensure_supported_device_tags(table_entry: TableEntry, tag_values: tuple, file_path: str) -> None:
+    null_tag_columns = [
+        column
+        for idx, column in enumerate(table_entry.tag_columns)
+        if idx >= len(tag_values) or tag_values[idx] is None
+    ]
+    if not null_tag_columns:
+        return
+
+    raise NotImplementedError(
+        "TsFileDataFrame does not support querying tables with NULL TAG values yet. "
+        f"Found NULL TAG column(s) {null_tag_columns} in table '{table_entry.table_name}' "
+        f"from file '{file_path}'."
+    )
+
+
 def _register_reader(
     readers: Dict[str, object],
     index: _LogicalIndex,
@@ -158,6 +174,7 @@ def _register_reader(
 
     for device_id, device_entry in enumerate(catalog.device_entries):
         table_entry = catalog.table_entries[device_entry.table_id]
+        _ensure_supported_device_tags(table_entry, device_entry.tag_values, file_path)
         device_key = (table_entry.table_name, tuple(device_entry.tag_values))
         device_idx = index.device_index_by_key.get(device_key)
         if device_idx is None:

python/tsfile/dataset/reader.py

@@ -47,7 +47,7 @@ def _to_python_scalar(value):
 def _ensure_supported_exact_tag_values(tag_values: Dict[str, object]) -> None:
     if any(tag_value is None for tag_value in tag_values.values()):
         raise NotImplementedError(
-            "Exact tag matching with None tag values is not supported yet. "
+            "TsFileDataFrame exact tag matching with NULL TAG values is not supported yet. "
             "Native tag filter support for IS NULL / IS NOT NULL is required."
         )