feat: Query for data (#37)

Author: mure

nisystemlink/clients/dataframe/_data_frame_client.py

@@ -197,3 +197,33 @@ def append_table_data(self, id: str, data: models.AppendTableDataRequest) -> Non
             data: The rows of data to append and any additional options.
         """
         ...
+
+    @post("tables/{id}/query-data", args=[Path, Body])
+    def query_table_data(
+        self, id: str, query: models.QueryTableDataRequest
+    ) -> models.PagedTableRows:
+        """Reads rows of data that match a filter from the table identified by its ID.
+
+        Args:
+            id: Unique ID of a DataFrame table.
+            query: The filtering and sorting to apply when reading data.
+
+        Returns:
+            models.PagedTableRows: The table data and total number of rows with a continuation token.
+        """
+        ...
+
+    @post("tables/{id}/query-decimated-data", args=[Path, Body])
+    def query_decimated_data(
+        self, id: str, query: models.QueryDecimatedDataRequest
+    ) -> models.TableRows:
+        """Reads decimated rows of data from the table identified by its ID.
+
+        Args:
+            id: Unique ID of a DataFrame table.
+            query: The filtering and decimation options to apply when reading data.
+
+        Returns:
+            models.TableRows: The decimated table data.
+        """
+        ...

nisystemlink/clients/dataframe/models/__init__.py

@@ -12,7 +12,15 @@
 from ._order_by import OrderBy
 from ._paged_tables import PagedTables
 from ._paged_table_rows import PagedTableRows
+from ._query_decimated_data_request import (
+    DecimationMethod,
+    DecimationOptions,
+    QueryDecimatedDataRequest,
+)
+from ._query_table_data_base import ColumnFilter, FilterOperation
+from ._query_table_data_request import ColumnOrderBy, QueryTableDataRequest
 from ._query_tables_request import QueryTablesRequest
 from ._table_metadata import TableMetadata
+from ._table_rows import TableRows
 
 # flake8: noqa

nisystemlink/clients/dataframe/models/_query_decimated_data_request.py

@@ -0,0 +1,57 @@
+from enum import Enum
+from typing import List, Optional
+
+from nisystemlink.clients.core._uplink._json_model import JsonModel
+
+from ._query_table_data_base import QueryTableDataBase
+
+
+class DecimationMethod(str, Enum):
+    """Represents the different methods that can be used to decimate data."""
+
+    Lossy = "LOSSY"
+    """Creates an ``x_column`` ordered set and returns an uniformly distributed
+    sample of rows with as many rows as the number specified as ``intervals.``"""
+
+    MaxMin = "MAX_MIN"
+    """Creates an ``x_column`` ordered set which will be divided in the number of
+    ``intervals`` specified. For each of the intervals, the maximum and minimum
+    values for all the columns specified in ``y_columns`` will be returned."""
+
+    EntryExit = "ENTRY_EXIT"
+    """Creates an ``x_column`` ordered set which will be divided in the number of
+    ``intervals`` specified. For each of the intervals, the first and last row
+    within the interval will be returned in addition to the maximum and minimum
+    values for all the columns specified in ``y_columns``."""
+
+
+class DecimationOptions(JsonModel):
+    """Contains the parameters to use for data decimation."""
+
+    x_column: Optional[str] = None
+    """The name of the column that will be used as the x-axis for decimating the
+    data. The column in the table that was specified as Index will be used if
+    this field is excluded. Only numeric columns are supported. i.e. ``INT32``,
+    ``INT64``, ``FLOAT32``, ``FLOAT64`` and ``TIMESTAMP``."""
+
+    y_columns: Optional[List[str]] = None
+    """A list of columns to decimate by. This property is only needed when the
+    specified method is ``MAX_MIN`` or ``ENTRY_EXIT``. Only numeric columns are
+    supported. i.e. ``INT32``, ``INT64``, ``FLOAT32``, ``FLOAT64`` and
+    ``TIMESTAMP``."""
+
+    intervals: Optional[int] = None
+    """Number of intervals to use for decimation. Defaults to 1000."""
+
+    method: Optional[DecimationMethod] = None
+    """Specifies the method used to decimate the data. Defaults to
+    :class:`DecimationMethod.Lossy`"""
+
+
+class QueryDecimatedDataRequest(QueryTableDataBase):
+    """Specifies the columns, filters and decimation parameters for a query."""
+
+    decimation: Optional[DecimationOptions] = None
+    """The decimation options to use when querying data. If not specified, the
+    default is to use :class:`DecimationMethod.Lossy` with 1000 intervals over
+    the table's index column."""

nisystemlink/clients/dataframe/models/_query_table_data_base.py

@@ -0,0 +1,54 @@
+from enum import Enum
+from typing import List, Optional
+
+from nisystemlink.clients.core._uplink._json_model import JsonModel
+
+
+class FilterOperation(str, Enum):
+    """Represents the different operations that can be used in a filter."""
+
+    Equals = "EQUALS"
+    NotEquals = "NOT_EQUALS"
+    LessThan = "LESS_THAN"
+    LessThanEquals = "LESS_THAN_EQUALS"
+    GreaterThan = "GREATER_THAN"
+    GreaterThanEquals = "GREATER_THAN_EQUALS"
+    Contains = "CONTAINS"
+    NotContains = "NOT_CONTAINS"
+
+
+class ColumnFilter(JsonModel):
+    """A filter to apply to the table data."""
+
+    column: str
+    """The name of the column to use for filtering."""
+
+    operation: FilterOperation
+    """How to compare the column's value with the specified value.
+
+    An error is returned if the column's data type does not support the specified operation:
+    * String columns only support ``EQUALS``, ``NOT_EQUALS``, ``CONTAINS``, and ``NOT_CONTAINS``.
+    * Non-string columns do not support ``CONTAINS`` or ``NOT_CONTAINS``.
+    * When ``value`` is ``None``, the operation must be ``EQUALS`` or ``NOT_EQUALS``.
+    * When ``value`` is ``NaN`` for a floating-point column, the operation must be ``NOT_EQUALS``.
+    """
+
+    value: Optional[str]
+    """The comparison value to use for filtering. An error will be returned if
+    the value cannot be converted to the column's data type."""
+
+
+class QueryTableDataBase(JsonModel):
+    """Contains the common set of options when querying table data."""
+
+    columns: Optional[List[str]] = None
+    """The names of columns to include in the response. The response will
+    include the columns in the same order specified in this parameter. All
+    columns are included in the order specified at table creation if this
+    property is excluded."""
+
+    filters: Optional[List[ColumnFilter]] = None
+    """A list of columns to filter by. Only rows whose columns contain values
+    matching all of the specified filters are returned. The columns used for
+    filtering do not need to be included in the columns list. When reading
+    decimated data, the filters are applied before decimation."""

nisystemlink/clients/dataframe/models/_query_table_data_request.py

@@ -0,0 +1,30 @@
+from typing import List, Optional
+
+from nisystemlink.clients.core._uplink._json_model import JsonModel
+from nisystemlink.clients.core._uplink._with_paging import WithPaging
+
+from ._query_table_data_base import QueryTableDataBase
+
+
+class ColumnOrderBy(JsonModel):
+    """Specifies a column to order by and the ordering direction."""
+
+    column: str
+    """The name of the column to order by."""
+
+    descending: Optional[bool] = None
+    """Whether the ordering should be in descending order."""
+
+
+class QueryTableDataRequest(QueryTableDataBase, WithPaging):
+    """Contains the filtering and sorting options to use when querying table data."""
+
+    order_by: Optional[List[ColumnOrderBy]] = None
+    """A list of columns to order the results by. Multiple columns may be
+    specified to order rows that have the same value for prior columns. The
+    columns used for sorting do not need to be included in the columns list, in
+    which case they are not returned. If ``order_by`` is not specified, then the
+    order in which results are returned is undefined."""
+
+    take: Optional[int] = None
+    """Limits the returned list to the specified number of results."""

nisystemlink/clients/dataframe/models/_table_rows.py

@@ -0,0 +1,10 @@
+from nisystemlink.clients.core._uplink._json_model import JsonModel
+
+from ._data_frame import DataFrame
+
+
+class TableRows(JsonModel):
+    """Contains the result of a query for rows of decimated data."""
+
+    frame: DataFrame
+    """The data frame containing the rows of data."""