Timeseries

opengate_data.timeseries.timeseries

Provision Timeseries Builder

TimeseriesBuilder Objects

class TimeseriesBuilder(SearchBuilder)

Timeseries Builder

Exports the data of a timeseries to a file — Parquet unless you ask for another content type — and reports the state of an export already running. Both operations work over the same endpoint, /v80/timeseries/provision/organizations/{organization}/{identifier}/export: export() starts one with a POST, export_status() asks about it with a GET.

Pick the operation, then close the chain with build() and execute(), or with build_execute(). Only one export per timeseries can run at a time.

To read rows instead of exporting them, use client.new_timeseries_search_builder().

Example:

builder = client.new_timeseries_builder()
builder.with_organization_name("organization").with_identifier(
"timeseries_identifier"
).with_output_file("export.parquet").export().build().execute()

with_organization_name

def with_organization_name(organization_name: str) -> "TimeseriesBuilder"

Sets the organization that owns the timeseries. Required.

Arguments:

organization_name str - The name of the organization.

Returns:

TimeseriesBuilder - Returns itself to allow for method chaining.

Example:

builder.with_organization_name("organization")

with_identifier

def with_identifier(identifier: str) -> "TimeseriesBuilder"

Sets the identifier of the timeseries to export. Required.

Arguments:

identifier str - The identifier of the timeseries.

Returns:

TimeseriesBuilder - Returns itself to allow for method chaining.

Example:

builder.with_identifier("timeseries_identifier")

with_callback

def with_callback(callback_url: str) -> "TimeseriesBuilder"

Sets a URL to be notified when the export finishes, sent as the callback header. Optional: without it, poll with export_status().

Arguments:

callback_url str - The URL to notify.

Returns:

TimeseriesBuilder - Returns itself to allow for method chaining.

Example:

builder.with_callback("https://your-application/export-done")

with_output_file

def with_output_file(filename: str,
                     content_type: str | None = None) -> "TimeseriesBuilder"

Names the file the export writes to, and optionally its content type.

Arguments:

filename str - The name of the output file.
content_type str | None - The content type to produce. Defaults to application/vnd.apache.parquet.

Returns:

TimeseriesBuilder - Returns itself to allow for method chaining.

Example:

builder.with_output_file("export.parquet")
builder.with_output_file("export.csv", "text/csv")

with_sort

def with_sort(sort: str) -> "TimeseriesBuilder"

Not supported for the Parquet export. The export endpoint decides the output order internally and cannot be changed, and any ‘sort’ field in the payload makes the platform reject the request as “Json is malformed”.

To read timeseries data in a given order, use the search builder instead: client.new_timeseries_search_builder().with_sort(""), where the identifier is one of the sorts declared in the timeseries definition (or its automatically exposed reverse). Note that sorting is also disabled server-side for CSV output.

Raises:

NotImplementedError - Always.

export

def export() -> "TimeseriesBuilder"

Selects the operation that starts an export of the timeseries data.

Returns:

TimeseriesBuilder - Returns itself to allow for method chaining.

Example:

builder.with_organization_name("organization").with_identifier(
"timeseries_identifier"
).export().build().execute()

export_status

def export_status() -> "TimeseriesBuilder"

Selects the operation that reports the state of the current export.

Unlike export(), it accepts no request body, so with_filter, with_select, with_limit and with_output_file are rejected here.

Returns:

TimeseriesBuilder - Returns itself to allow for method chaining.

Example:

builder.with_organization_name("organization").with_identifier(
"timeseries_identifier"
).export_status().build().execute()

build

def build() -> "TimeseriesBuilder"

Closes the chain and checks it, without sending the request.

Call it last, immediately before execute(). Use build_execute() instead to do both in one step; mixing the two raises.

Returns:

TimeseriesBuilder - Returns itself to allow for method chaining.

Raises:

Exception - If the chain is incomplete — no operation selected, or a required or forbidden method for that operation.

Example:

builder.export().build()

build_execute

def build_execute()

Closes the chain, checks it and sends the request in one step.

Returns:

dict[str, Any]: The same response as execute().

Raises:

ValueError - If combined with build() or with execute().

Example:

builder.with_organization_name("organization").with_identifier(
"timeseries_identifier"
).export().build_execute()

execute

def execute() -> Any

Sends the selected operation to the platform.

Returns:

dict[str, Any]: Always carries status_code, plus data on success or error with the response body on failure. For export(), 202 means the export was accepted and runs in the background, 204 that the timeseries holds no data, and 409 that another process is already exporting it. For export_status(), 200 carries the parsed state of the export; a 406 is retried for up to 20 seconds before being returned.

Raises:

Exception - If build() or build_execute() was not called first.
ValueError - If no operation was selected.

Example:

builder.with_organization_name("organization").with_identifier(
"timeseries_identifier"
).export().build().execute()

opengate_data.timeseries.find_timeseries

FindTimeseriesBuilder Objects

class FindTimeseriesBuilder(SearchBuilder)

Find time series Builder

with_expand

def with_expand(expand: str) -> "FindTimeseriesBuilder"

With expand, select the data field to show information, columns, context or columns.context.

Arguments:

expand str - The extra information to include: “columns”, “context” or “columns.context” for both.

Returns:

FindTimeseriesBuilder - Returns itself to allow for method chaining.

Raises:

TypeError - If the value is not a string.
ValueError - If the value is not one of the three accepted.

Example:

builder.with_expand("columns.context")

with_datastreams

def with_datastreams(datastreams: str) -> "FindTimeseriesBuilder"

With dataStreams, select the dataStreams to filter the Timeseries. To be accept and intepreted by the System the dataStream will be in format URL.

Arguments:

datastreams str - The datastreams to filter the timeseries by, as a comma-separated list in URL format.

Returns:

FindTimeseriesBuilder - Returns itself to allow for method chaining.

Raises:

TypeError - If the value is not a string.

Example:

builder.with_datastreams("provision.device.identifier")

with_organization_name

def with_organization_name(organization_name: str) -> "FindTimeseriesBuilder"

Set organization name

Arguments:

organization_name str - The name of the organization that owns the timeseries.

Returns:

FindTimeseriesBuilder - Returns itself to allow for method chaining.

Example:

builder.with_organization_name("organization_name")

with_format

def with_format(format_data: str) -> "FindTimeseriesBuilder"

Formats the flat entities data based on the specified format (‘csv’, ‘dict’, or ‘pandas’). By default, the data is returned as a dictionary.

Arguments:

format_data str - The format to use for the data.

Example:

builder.with_format(‘dict’) builder.with_format(‘pandas’)

Returns:

FindTimeseriesBuilder - Returns itself to allow for method chaining.

with_sort

def with_sort(sort: str) -> "FindTimeseriesBuilder"

Set sort identifier

Arguments:

sort str - The identifier of a sort declared in the timeseries definition.

with_identifier

def with_identifier(identifier: str) -> "FindTimeseriesBuilder"

set the timeseries identifier.

Arguments:

identifier str - The identifier of the timeseries.

Returns:

FindTimeseriesBuilder - Returns itself to allow for method chaining.

Example:

builder.with_identifier("timeseries_id")

with_config_file

def with_config_file(config_file: str,
                     section: str,
                     config_key: str,
                     prefer: str = "auto") -> "FindTimeseriesBuilder"

Reads a value from the INI and saves it as a source. ‘prefer’ controls whether the value will be interpreted as identifier, name, or auto (first id, then name).

Arguments:

config_file str - Path to the INI file to read.
section str - The section of the INI file the value lives in.
config_key str - The key holding the value.
prefer str - How to read the value: ‘identifier’, ’name’, or ‘auto’ to try the identifier first and fall back to the name. Defaults to ‘auto’.

with_name

def with_name(find_name: str) -> "FindTimeseriesBuilder"

Specify the name to find.

Arguments:

find_name str - The name of the timeseries.

Returns:

FindTimeseriesBuilder - Returns self for chaining.

Example:

builder.with_name('timeseries_name')

with_env

def with_env(env_key: str, prefer: str = "auto") -> "FindTimeseriesBuilder"

Use an environment variable as the source. ‘prefer’ can be:

‘identifier’ -> treat the value as an identifier
’name’ -> treat the value as a name
‘auto’ -> try identifier and, if not, name

Arguments:

env_key str - The name of the environment variable to read.
prefer str - How to read the value: ‘identifier’, ’name’, or ‘auto’ to try the identifier first and fall back to the name. Defaults to ‘auto’.

find_all

def find_all() -> "FindTimeseriesBuilder"

Searches for all available timeseries resources.

Returns:

FindTimeseriesBuilder - Returns the current instance to allow method chaining.

Example:

builder.with_organization_name('my_organization').find_all()

find_one

def find_one() -> "FindTimeseriesBuilder"

Searches for a single timeseries resource by its identifier.

This method prepares the request to find a specific timeseries based on its identifier. The identifier is obtained automatically if not explicitly defined or can be obtained from a configuration file or environment variables.

Returns:

FindTimeseriesBuilder - Returns the current instance to allow method chaining.

Example:

builder.with_organization_name('my_organization').with_organization_name("organization_name").with_format("dict").with_identifier("identifier").find_one().build().execute()

build

def build() -> "FindTimeseriesBuilder"

Finalizes the construction of the IoT collection configuration.

This method prepares the builder to execute the collection by ensuring all necessary configurations are set and validates the overall integrity of the build. It should be called before executing the collection to ensure that the configuration is complete and valid.

The build process involves checking that mandatory fields such as the device identifier are set. It also ensures that method calls that are incompatible with each other (like build and build_execute) are not both used.

Returns:

FindTimeseriesBuilder - Returns itself to allow for method chaining, enabling further actions like execute.

Raises:

ValueError - If required configurations are missing or if incompatible methods are used together.

Example:

builder.build()

build_execute

def build_execute()

Executes the timeseries search immediately after building the configuration.

This method is a shortcut that combines building and executing in a single step.

Returns:

dict - A dictionary containing the execution response which includes the status code and potentially other metadata about the execution.

Raises:

ValueError - If build has already been called on this builder instance.

Example:

builder.build_execute()

execute

def execute() -> Response

Execute the configured operation and return the response.

This method executes the operation that has been configured using the builder pattern. It ensures that the build method has been called and that it is the last method invoked before execute. Depending on the configured method (e.g., create, find, update, delete), it calls the appropriate internal execution method.

Returns:

requests.Response - The response object from the executed request.

Raises:

Exception - If the build method has not been called or if it is not the last method invoked before execute.
ValueError - If the configured method is unsupported.

Example:

builder.execute()