From d635f22496ea9dc027530e7440505c0cc81932b8 Mon Sep 17 00:00:00 2001 From: rodalynbarce <121169437+rodalynbarce@users.noreply.github.com> Date: Thu, 11 Jan 2024 14:00:06 +0000 Subject: [PATCH] Added examples to TimeSeriesQueryBuilder (#632) Signed-off-by: rodalynbarce --- mkdocs.yml | 6 +- .../time_series/time_series_query_builder.py | 300 ++++++++++++++++++ 2 files changed, 305 insertions(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index c3f483c67..ac715517d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -84,7 +84,11 @@ extra: plugins: - search - autorefs - - mkdocstrings + - mkdocstrings: + handlers: + python: + options: + members_order: source - tags - blog: post_excerpt: required diff --git a/src/sdk/python/rtdip_sdk/queries/time_series/time_series_query_builder.py b/src/sdk/python/rtdip_sdk/queries/time_series/time_series_query_builder.py index 967fe3595..38255d1c4 100644 --- a/src/sdk/python/rtdip_sdk/queries/time_series/time_series_query_builder.py +++ b/src/sdk/python/rtdip_sdk/queries/time_series/time_series_query_builder.py @@ -47,6 +47,23 @@ def connect(self, connection: ConnectionInterface): """ Specifies the connection to be used for the query. + **Example:** + ```python + from rtdip_sdk.authentication.azure import DefaultAuth + from rtdip_sdk.connectors import DatabricksSQLConnection + from rtdip_sdk.queries import TimeSeriesQueryBuilder + + auth = DefaultAuth().authenticate() + token = auth.get_token("2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default").token + connection = DatabricksSQLConnection("{server_hostname}", "{http_path}", token) + + connect = ( + TimeSeriesQueryBuilder() + .connect(connection) + ) + + ``` + Args: connection: Connection chosen by the user (Databricks SQL Connect, PYODBC SQL Connect, TURBODBC SQL Connect) """ @@ -64,6 +81,26 @@ def source( """ Specifies the source of the query. + **Example:** + ```python + from rtdip_sdk.authentication.azure import DefaultAuth + from rtdip_sdk.connectors import DatabricksSQLConnection + from rtdip_sdk.queries import TimeSeriesQueryBuilder + + auth = DefaultAuth().authenticate() + token = auth.get_token("2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default").token + connection = DatabricksSQLConnection("{server_hostname}", "{http_path}", token) + + source = ( + TimeSeriesQueryBuilder() + .connect(connection) + .source( + source="{table_path}" + ) + ) + + ``` + Args: source (str): Source of the query can be a Unity Catalog table, Hive metastore table or path tagname_column (optional str): The column name in the source that contains the tagnames or series @@ -90,6 +127,31 @@ def raw( """ A function to return back raw data. + **Example:** + ```python + from rtdip_sdk.authentication.azure import DefaultAuth + from rtdip_sdk.connectors import DatabricksSQLConnection + from rtdip_sdk.queries import TimeSeriesQueryBuilder + + auth = DefaultAuth().authenticate() + token = auth.get_token("2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default").token + connection = DatabricksSQLConnection("{server_hostname}", "{http_path}", token) + + data = ( + TimeSeriesQueryBuilder() + .connect(connection) + .source("{table_path}") + .raw( + tagname_filter=["{tag_name_1}", "{tag_name_2}"], + start_date="2023-01-01", + end_date="2023-01-31", + ) + ) + + display(data) + + ``` + Args: tagname_filter (list str): List of tagnames to filter on the source start_date (str): Start date (Either a date in the format YY-MM-DD or a datetime in the format YYY-MM-DDTHH:MM:SS or specify the timezone offset in the format YYYY-MM-DDTHH:MM:SS+zz:zz) @@ -133,6 +195,34 @@ def resample( """ A query to resample the source data. + **Example:** + ```python + from rtdip_sdk.authentication.azure import DefaultAuth + from rtdip_sdk.connectors import DatabricksSQLConnection + from rtdip_sdk.queries import TimeSeriesQueryBuilder + + auth = DefaultAuth().authenticate() + token = auth.get_token("2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default").token + connection = DatabricksSQLConnection("{server_hostname}", "{http_path}", token) + + data = ( + TimeSeriesQueryBuilder() + .connect(connection) + .source("{table_path}") + .resample( + tagname_filter=["{tag_name_1}", "{tag_name_2}"], + start_date="2023-01-01", + end_date="2023-01-31", + time_interval_rate="15", + time_interval_unit="minute", + agg_method="first", + ) + ) + + display(data) + + ``` + Args: tagname_filter (list str): List of tagnames to filter on the source start_date (str): Start date (Either a date in the format YY-MM-DD or a datetime in the format YYY-MM-DDTHH:MM:SS or specify the timezone offset in the format YYYY-MM-DDTHH:MM:SS+zz:zz) @@ -187,6 +277,35 @@ def interpolate( """ The Interpolate function will forward fill, backward fill or linearly interpolate the resampled data depending on the parameters specified. + **Example:** + ```python + from rtdip_sdk.authentication.azure import DefaultAuth + from rtdip_sdk.connectors import DatabricksSQLConnection + from rtdip_sdk.queries import TimeSeriesQueryBuilder + + auth = DefaultAuth().authenticate() + token = auth.get_token("2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default").token + connection = DatabricksSQLConnection("{server_hostname}", "{http_path}", token) + + data = ( + TimeSeriesQueryBuilder() + .connect(connection) + .source("{table_path}") + .interpolate( + tagname_filter=["{tag_name_1}", "{tag_name_2}"], + start_date="2023-01-01", + end_date="2023-01-31", + time_interval_rate="15", + time_interval_unit="minute", + agg_method="first", + interpolation_method="forward_fill", + ) + ) + + display(data) + + ``` + Args: tagname_filter (list str): List of tagnames to filter on the source start_date (str): Start date (Either a date in the format YY-MM-DD or a datetime in the format YYY-MM-DDTHH:MM:SS or specify the timezone offset in the format YYYY-MM-DDTHH:MM:SS+zz:zz) @@ -238,6 +357,30 @@ def interpolation_at_time( """ A interpolation at time function which works out the linear interpolation at a specific time based on the points before and after. + **Example:** + ```python + from rtdip_sdk.authentication.azure import DefaultAuth + from rtdip_sdk.connectors import DatabricksSQLConnection + from rtdip_sdk.queries import TimeSeriesQueryBuilder + + auth = DefaultAuth().authenticate() + token = auth.get_token("2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default").token + connection = DatabricksSQLConnection("{server_hostname}", "{http_path}", token) + + data = ( + TimeSeriesQueryBuilder() + .connect(connection) + .source("{table_path}") + .interpolation_at_time( + tagname_filter=["{tag_name_1}", "{tag_name_2}"], + timestamp_filter=["2023-01-01T09:30:00", "2023-01-02T12:00:00"], + ) + ) + + display(data) + + ``` + Args: tagname_filter (list str): List of tagnames to filter on the source timestamp_filter (list): List of timestamp or timestamps in the format YYY-MM-DDTHH:MM:SS or YYY-MM-DDTHH:MM:SS+zz:zz where %z is the timezone. (Example +00:00 is the UTC timezone) @@ -288,6 +431,34 @@ def time_weighted_average( """ A function that receives a dataframe of raw tag data and performs a time weighted averages. + **Example:** + ```python + from rtdip_sdk.authentication.azure import DefaultAuth + from rtdip_sdk.connectors import DatabricksSQLConnection + from rtdip_sdk.queries import TimeSeriesQueryBuilder + + auth = DefaultAuth().authenticate() + token = auth.get_token("2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default").token + connection = DatabricksSQLConnection("{server_hostname}", "{http_path}", token) + + data = ( + TimeSeriesQueryBuilder() + .connect(connection) + .source("{table_path}") + .time_weighted_average( + tagname_filter=["{tag_name_1}", "{tag_name_2}"], + start_date="2023-01-01", + end_date="2023-01-31", + time_interval_rate="15", + time_interval_unit="minute", + step="true", + ) + ) + + display(data) + + ``` + Args: tagname_filter (list str): List of tagnames to filter on the source start_date (str): Start date (Either a date in the format YY-MM-DD or a datetime in the format YYY-MM-DDTHH:MM:SS or specify the timezone offset in the format YYYY-MM-DDTHH:MM:SS+zz:zz) @@ -341,6 +512,29 @@ def metadata( """ A query to retrieve metadata. + **Example:** + ```python + from rtdip_sdk.authentication.azure import DefaultAuth + from rtdip_sdk.connectors import DatabricksSQLConnection + from rtdip_sdk.queries import TimeSeriesQueryBuilder + + auth = DefaultAuth().authenticate() + token = auth.get_token("2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default").token + connection = DatabricksSQLConnection("{server_hostname}", "{http_path}", token) + + data = ( + TimeSeriesQueryBuilder() + .connect(connection) + .source("{table_path}") + .metadata( + tagname_filter=["{tag_name_1}", "{tag_name_2}"], + ) + ) + + display(data) + + ``` + Args: tagname_filter (list str): List of tagnames to filter on the source limit (optional int): The number of rows to be returned @@ -369,6 +563,29 @@ def latest( """ A query to retrieve latest event_values. + **Example:** + ```python + from rtdip_sdk.authentication.azure import DefaultAuth + from rtdip_sdk.connectors import DatabricksSQLConnection + from rtdip_sdk.queries import TimeSeriesQueryBuilder + + auth = DefaultAuth().authenticate() + token = auth.get_token("2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default").token + connection = DatabricksSQLConnection("{server_hostname}", "{http_path}", token) + + data = ( + TimeSeriesQueryBuilder() + .connect(connection) + .source("{table_path}") + .latest( + tagname_filter=["{tag_name_1}", "{tag_name_2}"], + ) + ) + + display(data) + + ``` + Args: tagname_filter (list str): List of tagnames to filter on the source limit (optional int): The number of rows to be returned @@ -405,6 +622,35 @@ def circular_average( """ A function that receives a dataframe of raw tag data and computes the circular mean for samples in a range. + **Example:** + ```python + from rtdip_sdk.authentication.azure import DefaultAuth + from rtdip_sdk.connectors import DatabricksSQLConnection + from rtdip_sdk.queries import TimeSeriesQueryBuilder + + auth = DefaultAuth().authenticate() + token = auth.get_token("2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default").token + connection = DatabricksSQLConnection("{server_hostname}", "{http_path}", token) + + data = ( + TimeSeriesQueryBuilder() + .connect(connection) + .source("{table_path}") + .circular_average( + tagname_filter=["{tag_name_1}", "{tag_name_2}"], + start_date="2023-01-01", + end_date="2023-01-31", + time_interval_rate="15", + time_interval_unit="minute", + lower_bound="0", + upper_bound="360", + ) + ) + + display(data) + + ``` + Args: tagname_filter (list str): List of tagnames to filter on the source start_date (str): Start date (Either a date in the format YY-MM-DD or a datetime in the format YYY-MM-DDTHH:MM:SS or specify the timezone offset in the format YYYY-MM-DDTHH:MM:SS+zz:zz) @@ -460,6 +706,35 @@ def circular_standard_deviation( """ A function that receives a dataframe of raw tag data and computes the circular standard deviation for samples assumed to be in the range. + **Example:** + ```python + from rtdip_sdk.authentication.azure import DefaultAuth + from rtdip_sdk.connectors import DatabricksSQLConnection + from rtdip_sdk.queries import TimeSeriesQueryBuilder + + auth = DefaultAuth().authenticate() + token = auth.get_token("2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default").token + connection = DatabricksSQLConnection("{server_hostname}", "{http_path}", token) + + data = ( + TimeSeriesQueryBuilder() + .connect(connection) + .source("{table_path}") + .circular_standard_deviation( + tagname_filter=["{tag_name_1}", "{tag_name_2}"], + start_date="2023-01-01", + end_date="2023-01-31", + time_interval_rate="15", + time_interval_unit="minute", + lower_bound="0", + upper_bound="360", + ) + ) + + display(data) + + ``` + Args: tagname_filter (list str): List of tagnames to filter on the source start_date (str): Start date (Either a date in the format YY-MM-DD or a datetime in the format YYY-MM-DDTHH:MM:SS or specify the timezone offset in the format YYYY-MM-DDTHH:MM:SS+zz:zz) @@ -512,6 +787,31 @@ def summary( """ A function to return back a summary of statistics. + **Example:** + ```python + from rtdip_sdk.authentication.azure import DefaultAuth + from rtdip_sdk.connectors import DatabricksSQLConnection + from rtdip_sdk.queries import TimeSeriesQueryBuilder + + auth = DefaultAuth().authenticate() + token = auth.get_token("2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default").token + connection = DatabricksSQLConnection("{server_hostname}", "{http_path}", token) + + data = ( + TimeSeriesQueryBuilder() + .connect(connection) + .source("{table_path}") + .summary( + tagname_filter=["{tag_name_1}", "{tag_name_2}"], + start_date="2023-01-01", + end_date="2023-01-31", + ) + ) + + display(data) + + ``` + Args: tagname_filter (list str): List of tagnames to filter on the source start_date (str): Start date (Either a date in the format YY-MM-DD or a datetime in the format YYY-MM-DDTHH:MM:SS or specify the timezone offset in the format YYYY-MM-DDTHH:MM:SS+zz:zz)