feat: DFS support for test result ID, column name queries, and interactive queries (#164)

Add a `test_result_id` field to all metadata models (create, read, and modify). Add an `interactive` field to the query tables request model. Document the ability to filter tables by test result ID and column names.

Author: spanglerco

nisystemlink/clients/dataframe/models/_create_table_request.py

@@ -18,5 +18,11 @@ class CreateTableRequest(JsonModel):
     properties: Optional[Dict[str, str]] = None
     """User-defined properties to associate with the table."""
 
+    test_result_id: Optional[str] = None
+    """The ID of the test result associated with the table. A value of ``None`` or an empty string
+    indicates there is no associated test result. Added in version 2 of the
+    :py:attr:`nisystemlink.clients.dataframe.models.OperationsV1.create_tables` operation. Older
+    versions of the service will ignore this value."""
+
     workspace: Optional[str] = None
     """The workspace to create the table in. Uses the default workspace when not specified."""

nisystemlink/clients/dataframe/models/_modify_table_request.py

@@ -11,8 +11,7 @@ class ColumnMetadataPatch(JsonModel):
 
     properties: Dict[str, Optional[str]]
     """The properties to modify. A map of key value properties containing the metadata
-    to be added or modified. Setting a property value to ``None`` will delete the
-    property."""
+    to be added or modified. Set a property value to ``None`` to delete the property."""
 
 
 class ModifyTableRequest(JsonModel):
@@ -27,17 +26,23 @@ class ModifyTableRequest(JsonModel):
     state."""
 
     name: Optional[str] = None
-    """The new name of the table. Setting to ``None`` will reset the name to the table's ID."""
+    """The new name of the table. Set to ``None`` to reset the name to the table's ID."""
+
+    test_result_id: Optional[str] = None
+    """The new test result ID associated with the table. Set to ``None`` or an empty string to
+    remove the test result ID. Added in version 2 of the
+    :py:attr:`nisystemlink.clients.dataframe.models.OperationsV1.modify_metadata` operation. Older
+    versions of the service will ignore this value."""
 
     workspace: Optional[str] = None
-    """The new workspace for the table. Setting to ``None`` will reset to the
+    """The new workspace for the table. Set to ``None`` to reset to the
     default workspace. Changing the workspace requires permission to delete the
     table in its current workspace and permission to create the table in its new
     workspace."""
 
     properties: Optional[Dict[str, Optional[str]]] = None
     """The properties to modify. A map of key value properties containing the
-    metadata to be added or modified. Setting a property value to ``None`` will
+    metadata to be added or modified. Set a property value to ``None`` to
     delete the property."""
 
     columns: Optional[List[ColumnMetadataPatch]] = None

nisystemlink/clients/dataframe/models/_modify_tables_request.py

@@ -22,6 +22,12 @@ class TableMetadataModification(JsonModel):
     name: Optional[str] = None
     """The new name of the table."""
 
+    test_result_id: Optional[str] = None
+    """The new test result ID associated with the table. Set to an empty string to remove
+    the test result ID. Added in version 2 of the
+    :py:attr:`nisystemlink.clients.dataframe.models.OperationsV1.modify_metadata` operation. Older
+    versions of the service will ignore this value."""
+
     workspace: Optional[str] = None
     """The new workspace for the table. Changing the workspace requires
     permission to delete the table in its current workspace and permission to

nisystemlink/clients/dataframe/models/_query_tables_request.py

@@ -17,6 +17,8 @@ class QueryTablesRequest(WithPaging):
 
     Allowed properties in the filter are:
 
+    * ``columns``: List of columns in the table (see below; requires version 2 of the
+      :py:attr:`nisystemlink.clients.dataframe.models.OperationsV1.list_tables` operation)
     * ``createdAt``: DateTime the table was created
     * ``createdWithin``: TimeSpan in which the table was created
     * ``id``: String value uniquely identifying the table
@@ -32,8 +34,14 @@ class QueryTablesRequest(WithPaging):
     * ``rowCount``: Int32 number of rows in the table
     * ``supportsAppend``: Boolean indicating whether or not the table supports
       appending additional rows of data
-    * ``workspace``: String value ID of the workspace the table belongs to
-    * ``workspaceName``: String value name of the workspace the table belongs to
+    * ``testResultId``: String ID of the test result associated with the table (requires version 2
+      of the :py:attr:`nisystemlink.clients.dataframe.models.OperationsV1.list_tables` operation)
+    * ``workspace``: String ID of the workspace the table belongs to
+    * ``workspaceName``: String name of the workspace the table belongs to
+
+    Allowed properties in the ``columns`` list are:
+
+    * ``name``: String name of the column (requires a ``testResultId`` filter)
 
     Allowed constants in the filter are:
 
@@ -76,3 +84,9 @@ class QueryTablesRequest(WithPaging):
     string. The elements in the list are sorted ascending if false and
     descending if true.
     """
+
+    interactive: Optional[bool] = None
+    """Whether the query is being made within an interactive context, such as a web UI.
+    Interactive queries receive faster feedback for slow queries. Added in version 2 of the
+    :py:attr:`nisystemlink.clients.dataframe.models.OperationsV1.list_tables` operation.
+    Older versions of the service will ignore this value."""

nisystemlink/clients/dataframe/models/_table_metadata.py

@@ -1,5 +1,5 @@
 from datetime import datetime
-from typing import Dict, List
+from typing import Dict, List, Optional
 
 from nisystemlink.clients.core._uplink._json_model import JsonModel
 
@@ -39,5 +39,10 @@ class TableMetadata(JsonModel):
     supports_append: bool
     """Whether the table supports appending additional rows of data."""
 
+    test_result_id: Optional[str] = None
+    """The ID of the test result associated with the table. Added in version 2 of the
+    :py:attr:`nisystemlink.clients.dataframe.models.OperationsV1.list_tables` operation. This
+    value will always be ``None`` when communicating with older versions of the service."""
+
     workspace: str
     """The workspace the table belongs to."""

tests/integration/dataframe/test_dataframe.py

@@ -1,6 +1,7 @@
 # -*- coding: utf-8 -*-
+import warnings
 from datetime import datetime, timezone
-from typing import List, Optional
+from typing import Callable, List, Optional, TypedDict
 
 import pytest  # type: ignore
 import responses
@@ -31,6 +32,10 @@
 from responses import matchers
 
 
+_TestResultIdArg = TypedDict(
+    "_TestResultIdArg", {"test_result_id": Optional[str]}, total=False
+)
+
 int_index_column = Column(
     name="index", data_type=DataType.Int32, column_type=ColumnType.Index
 )
@@ -84,6 +89,21 @@ def test_tables(create_table):
     return ids
 
 
+@pytest.fixture(scope="class")
+def supports_test_result_id(client: DataFrameClient) -> bool:
+    """Fixture to determine if the server supports test result IDs."""
+    api_info = client.api_info()
+    result = api_info.operations.create_tables.version >= 2
+    if not result:
+        warnings.warn(
+            (
+                "The selected version of the DataFrame Service does not support test "
+                "result IDs. Tests will not attempt to set a test result ID."
+            )
+        )
+    return result
+
+
 @pytest.mark.enterprise
 @pytest.mark.integration
 class TestDataFrame:
@@ -126,6 +146,43 @@ def test__create_table__metadata_is_correct(
                 properties={},
             ),
         ]
+        assert table_metadata.test_result_id is None
+
+    def test__create_table__supports_test_result(
+        self,
+        client: DataFrameClient,
+        create_table: Callable[[CreateTableRequest], str],
+        supports_test_result_id: bool,
+    ):
+        test_result_id = "Test result" if supports_test_result_id else None
+        id = create_table(
+            CreateTableRequest(
+                columns=[
+                    Column(
+                        name="index",
+                        data_type=DataType.Int32,
+                        column_type=ColumnType.Index,
+                    )
+                ],
+                name="Test table with test result ID",
+                test_result_id=test_result_id,
+            )
+        )
+
+        table = client.get_table_metadata(id)
+        assert table.test_result_id == test_result_id
+
+        page = client.list_tables(take=1, id=[id])
+        assert len(page.tables) == 1
+        assert page.tables[0].test_result_id == test_result_id
+        assert page.continuation_token is None
+
+        page = client.query_tables(
+            QueryTablesRequest(filter="id == @0", substitutions=[id], take=1)
+        )
+        assert len(page.tables) == 1
+        assert page.tables[0].test_result_id == test_result_id
+        assert page.continuation_token is None
 
     def test__get_table__correct_timestamp(self, client: DataFrameClient, create_table):
         id = create_table(basic_table_model)
@@ -188,7 +245,9 @@ def test__query_tables__returns(
         assert len(second_page.tables) == 1
         assert second_page.continuation_token is None
 
-    def test__modify_table__returns(self, client: DataFrameClient, create_table):
+    def test__modify_table__returns(
+        self, client: DataFrameClient, create_table, supports_test_result_id: bool
+    ):
         id = create_table(basic_table_model)
 
         client.modify_table(
@@ -200,12 +259,18 @@ def test__modify_table__returns(self, client: DataFrameClient, create_table):
                 columns=[
                     ColumnMetadataPatch(name="index", properties={"sheep": "baa"})
                 ],
+                **self._test_result_id_if_supported(
+                    "Test result", supports_test_result_id
+                ),
             ),
         )
         table = client.get_table_metadata(id)
 
         assert table.metadata_revision == 2
         assert table.name == "Modified table"
+        assert table.test_result_id == (
+            "Test result" if supports_test_result_id else None
+        )
         assert table.properties == {"cow": "moo"}
         assert table.columns[0].properties == {"sheep": "baa"}
 
@@ -214,6 +279,9 @@ def test__modify_table__returns(self, client: DataFrameClient, create_table):
 
         assert table.properties == {"cow": "moo", "bee": "buzz"}
         assert table.name == "Modified table"
+        assert table.test_result_id == (
+            "Test result" if supports_test_result_id else None
+        )
 
         client.modify_table(
             id,
@@ -222,15 +290,23 @@ def test__modify_table__returns(self, client: DataFrameClient, create_table):
                 name=None,
                 properties={"cow": None},
                 columns=[ColumnMetadataPatch(name="index", properties={"sheep": None})],
+                **self._test_result_id_if_supported(None, supports_test_result_id),
             ),
         )
         table = client.get_table_metadata(id)
 
         assert table.metadata_revision == 4
         assert table.name == id
+        assert table.test_result_id is None
         assert table.properties == {"bee": "buzz"}
         assert table.columns[0].properties == {}
 
+    @staticmethod
+    def _test_result_id_if_supported(
+        test_result_id: Optional[str], supports_test_result_id: bool
+    ) -> _TestResultIdArg:
+        return {"test_result_id": test_result_id} if supports_test_result_id else {}
+
     def test__delete_table__deletes(self, client: DataFrameClient):
         id = client.create_table(
             basic_table_model
@@ -259,13 +335,16 @@ def test__delete_tables__returns_partial_success(self, client: DataFrameClient):
         assert len(response.error.inner_errors) == 1
 
     def test__modify_tables__modifies_tables(
-        self, client: DataFrameClient, create_table
+        self, client: DataFrameClient, create_table, supports_test_result_id: bool
     ):
         ids = [create_table(basic_table_model) for _ in range(3)]
 
         updates = [
             TableMetadataModification(
-                id=id, name="Modified table", properties={"duck": "quack"}
+                id=id,
+                name="Modified table",
+                test_result_id="Test result" if supports_test_result_id else None,
+                properties={"duck": "quack"},
             )
             for id in ids
         ]
@@ -274,6 +353,9 @@ def test__modify_tables__modifies_tables(
 
         for table in client.list_tables(id=ids).tables:
             assert table.name == "Modified table"
+            assert table.test_result_id == (
+                "Test result" if supports_test_result_id else None
+            )
             assert table.properties == {"duck": "quack"}
 
         updates = [
@@ -286,15 +368,34 @@ def test__modify_tables__modifies_tables(
         )
 
         for table in client.list_tables(id=ids).tables:
+            assert table.name == "Modified table"
+            assert table.test_result_id == (
+                "Test result" if supports_test_result_id else None
+            )
             assert table.properties == {"pig": "oink"}
 
+        if supports_test_result_id:
+            updates = [
+                TableMetadataModification(id=id, test_result_id="") for id in ids
+            ]
+
+            assert client.modify_tables(ModifyTablesRequest(tables=updates)) is None
+
+            for table in client.list_tables(id=ids).tables:
+                assert table.name == "Modified table"
+                assert table.test_result_id is None
+
     def test__modify_tables__returns_partial_success(
-        self, client: DataFrameClient, create_table
+        self, client: DataFrameClient, create_table, supports_test_result_id: bool
     ):
         id = create_table(basic_table_model)
 
         updates = [
-            TableMetadataModification(id=id, name="Modified table")
+            TableMetadataModification(
+                id=id,
+                name="Modified table",
+                test_result_id="Test result" if supports_test_result_id else None,
+            )
             for id in [id, "invalid_id"]
         ]