Skip to content

Commit

Permalink
Added examples to TimeSeriesQueryBuilder (#632)
Browse files Browse the repository at this point in the history 
Signed-off-by: rodalynbarce <[email protected]>
  • Loading branch information
@rodalynbarce
rodalynbarce authored Jan 11, 2024
1 parent 2228afb commit d635f22
Show file tree
Hide file tree
Showing 2 changed files with 305 additions and 1 deletion.
6 changes: 5 additions & 1 deletion mkdocs.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,11 @@ extra:
plugins:
- search
- autorefs
- mkdocstrings
- mkdocstrings:
handlers:
python:
options:
members_order: source
- tags
- blog:
post_excerpt: required
Expand Down
300 changes: 300 additions & 0 deletions src/sdk/python/rtdip_sdk/queries/time_series/time_series_query_builder.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
"""
Expand All @@ -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
Expand All @@ -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)
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand Down

0 comments on commit d635f22

Please sign in to comment.