Searching

opengate_data.searching

opengate_data.searching.builder

DataPointsSearchBuilder Objects

class DataPointsSearchBuilder(SearchBuilderBase, SearchBuilder)

Datapoints Search Builder

with_transpose
def with_transpose() -> 'DataPointsSearchBuilder'

Enables transposing the data in the result.

This function allows the data returned by the search to be transposed, meaning that rows and columns are swapped. This can be useful for certain data analyses where it is preferred to have datastreams as columns and entities as rows.

Notes:

This function can only be used with the ‘pandas’ format.

Returns:

  • DataPointsSearchBuilder - Returns the builder instance to allow for method chaining.

Example:

builder.with_transpose()

with_mapped_transpose
def with_mapped_transpose(
        mapping: dict[str, dict[str, str]]) -> 'DataPointsSearchBuilder'

Enables transposing the data with a specific mapping.

This function allows the data returned by the search to be transposed and mapped according to a provided mapping dictionary. The mapping specifies how complex data should be transformed into flat columns.

Arguments:

mapping (dict[str, dict[str, str]]): A dictionary that defines the mapping of complex data to flat columns. The main key is the column name, and the value is another dictionary that defines the mapping of substructures.

Notes:

This function can only be used with the ‘pandas’ format.

Returns:

  • DataPointsSearchBuilder - Returns the builder instance to allow for method chaining.

Example:

complexData = {
- `'device.communicationModules[].subscription.address'` - {
- `'type'` - 'type',
- `'IP'` - 'value'
}
}
builder.with_mapped_transpose(complexData)

execute
def execute()

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()

DatasetsSearchBuilder

DatasetsSearchBuilder Objects

class DatasetsSearchBuilder(SearchBuilder)

Dataset Search Builder

with_organization_name
def with_organization_name(organization_name: str) -> 'DatasetsSearchBuilder'

Set organization name

Arguments:

organization_name (str):

Returns:

  • DatasetsSearchBuilder - Returns itself to allow for method chaining.

Example:

builder.with_organization_name("organization_name")

with_identifier
def with_identifier(identifier: str) -> 'DatasetsSearchBuilder'

Set identifier

Returns:

  • DatasetsSearchBuilder - Returns itself to allow for method chaining.

Example:

builder.with_identifier("identifier")

with_utc
def with_utc() -> 'DatasetsSearchBuilder'

Set UTC

Returns:

  • DatasetsSearchBuilder - Returns itself to allow for method chaining.

Example:

builder.with_utc()

with_format
def with_format(format_data: str) -> 'DatasetsSearchBuilder'

Formats the flat entities data based on the specified format (‘csv’, ‘dict’, or ‘pandas’).

Arguments:

  • format_data str - The format to use for the data.

Returns:

  • DatasetsSearchBuilder - Returns itself to allow for method chaining.

Example:

builder.with_format("dict")
builder.with_format("pandas")
builder.with_format("csv")

build
def build() -> 'DatasetsSearchBuilder'

Finalizes the construction of the operation search 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:

  • DatasetsSearchBuilder - 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.

Notes:

This method should be used as a final step before execute to prepare the operations search configuration. It does not modify the state but ensures that the builder’s state is ready for execution.

Example:

builder.build()

build_execute
def build_execute()

Executes the data sets 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:

new_data_sets_search_builder.with_format("csv").with_organization_name(organization).build_execute()
new_data_sets_search_builder.with_filter(filter).with_organization_name(organization).with_format("pandas").build_execute()
new_data_sets_search_builder.with_filter(filter).with_organization_name(organization).with_format("dict").build_execute()

execute
def execute()

Executes the data set search based on the built configuration.

Returns:

dict, csv or dataframe: The response data in the specified format.

Raises:

  • Exception - If the build() method was not called before execute().

Example:

new_data_sets_search_builder.with_format("csv").with_organization_name(organization).build().execute()
new_data_sets_search_builder.with_filter(filter).with_organization_name(organization).with_format("pandas").build().execute()
new_data_sets_search_builder.with_filter(filter).with_organization_name(organization).with_format("dict").build().execute()

EntitiesSearchBuilder

EntitiesSearchBuilder Objects

class EntitiesSearchBuilder(SearchBuilderBase, SearchBuilder)

Entities Search Builder

build
def build() -> 'EntitiesSearchBuilder'

Finalizes the construction of the entity search 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.

Example:

builder.build()

Returns:

  • EntitiesSearchBuilder - 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.

Notes:

This method should be used as a final step before execute to prepare the entities search configuration. It does not modify the state but ensures that the builder’s state is ready for execution.

Example:

builder.build()

build_execute
def build_execute()

Executes the entities 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:

new_entities_search_builder.with_format("csv").with_select(select).with_organization_name(organization).build_execute()
new_entities_search_builder.with_filter(filter).with_organization_name(organization).with_format("pandas").build_execute()
new_entities_search_builder.with_filter(filter).with_organization_name(organization).with_format("dict").build_execute()

execute
def execute()

Executes the entities search based on the built configuration.

Returns:

dict, csv or dataframe: The response data in the specified format.

Raises:

  • Exception - If the build() method was not called before execute().

Example:

new_entities_search_builder.with_format("csv").with_select(select).with_organization_name(organization).build().execute()
new_entities_search_builder.with_filter(filter).with_organization_name(organization).with_format("pandas").build().execute()
new_entities_search_builder.with_filter(filter).with_organization_name(organization).with_format("dict").build().execute()

OperationsBuilder

OperationsSearchBuilder Objects

class OperationsSearchBuilder(SearchBuilderBase, SearchBuilder)

Builder Operations Search

build
def build()

Finalizes the construction of the operations search 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.

Example:

builder.build()

Returns:

  • OperationsSearchBuilder - 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.

Notes:

This method should be used as a final step before execute to prepare the operations search configuration. It does not modify the state but ensures that the builder’s state is ready for execution.

Example:

builder.build()

build_execute
def build_execute()

Executes the operation 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:

new_operations_search_builder.with_format("csv").with_organization_name(organization).build_execute()
new_operations_search_builder.with_filter(filter).with_organization_name(organization).with_format("pandas").build_execute()
new_operations_search_builder.with_filter(filter).with_organization_name(organization).with_format("dict").build_execute()

execute
def execute()

Executes the operation search based on the built configuration.

Returns:

dict, csv or dataframe: The response data in the specified format.

Raises:

  • Exception - If the build() method was not called before execute().

Example:

new_operations_search_builder.with_format("csv").with_organization_name(organization).build().execute()
new_operations_search_builder.with_filter(filter).with_organization_name(organization).with_format("pandas").build().execute()
new_operations_search_builder.with_filter(filter).with_organization_name(organization).with_format("dict").build().execute()

RulesSearchBuilder

RulesSearchBuilder Objects

class RulesSearchBuilder(SearchBuilder)

Rules Search Builder

with_format
def with_format(format_data: str) -> 'RulesSearchBuilder'

Formats the flat entities data based on the specified format (‘dict’, or ‘pandas’).

Arguments:

  • format_data str - The format to use for the data.

Returns:

  • EntitiesSearchBuilder - Returns itself to allow for method chaining.

Example:

builder.with_format("dict")
builder.with_format("pandas")

build
def build() -> 'RulesSearchBuilder'

Finalizes the construction of the datapoints search 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.

Returns:

  • DataPointsSearchBuilder - Returns itself to allow for method chaining.

Raises:

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

Example:

builder.build()

build_execute
def build_execute()

Executes the datapoints 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:

new_rules_search_builder.with_filter(filter).with_organization_name(organization).with_format("pandas").build_execute()
new_entities_search_builder.with_filter(filter).with_organization_name(organization).with_format("dict").build_execute()

execute
def execute()

Executes the rule search based on the built configuration.

Returns:

  • dict - The response data.

Raises:

  • Exception - If the build() method was not called before execute().

Example:

new_rules_search_builder.with_filter(filter).with_organization_name(organization).with_format("dict").build_execute()
new_rules_search_builder.with_filter(filter).with_organization_name(organization).with_format("pandas").build_execute()

TimeseriesSearchBuilder Objects

class TimeseriesSearchBuilder(SearchBuilder)

Timeseries Search Builder

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

Set organization name

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

Set identifier

with_utc
def with_utc() -> "TimeseriesSearchBuilder"

Set UTC flag for date-time parsing

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

Formats the timeseries data based on the specified format (‘csv’, ‘dict’, or ‘pandas’).

build
def build() -> "TimeseriesSearchBuilder"

Finalizes the construction of the timeseries search configuration.

build_execute
def build_execute()

Executes the timeseries search immediately after building the configuration.

execute
def execute()

Executes the timeseries search based on the built configuration.

opengate_data.searching.filter

FilterBuilder Objects

class FilterBuilder(Expressions)

Filter Builder

and_
def and_(*conditions)

Combines conditions using the logical AND operator.

Arguments:

  • *conditions - The conditions to combine.

Returns:

  • FilterBuilder - Returns itself to allow for method chaining.

Example:

builder.and_(eq(“device.operationalStatus”, “NORMAL”), like(“device.name”, “device_.*”) )

or_
def or_(*conditions)

Combines conditions using the logical OR operator.

Arguments:

  • *conditions - The conditions to combine.

Returns:

  • FilterBuilder - Returns itself to allow for method chaining.

Example:

builder.or_(eq(“device.operationalStatus”, “NORMAL”), like(“device.name”, “device_.*”) )

build
def build()

Builds the final filter.

Returns:

  • dict - The final filter.

Raises:

  • ValueError - If there is an incomplete condition.

Example:

builder.build()

opengate_data.searching.search

SearchBuilder

SearchBuilder Objects

class SearchBuilder()

Search Builder

with_filter
def with_filter(filter_data: dict) -> 'SearchBuilder'

Adds a filter to the search.

Arguments:

  • filter_data Union[dict, FilterBuilder] - The filter data to apply. Can be a dictionary or a FilterBuilder instance.

Returns:

  • SearchBuilder - Returns itself to allow for method chaining.

Example:

search_builder.with_filter(filter_builder.build()) search_builder.with_filter({

  • "and" - [
  • {"eq" - {“device.operationalStatus”: “NORMAL”}},
  • {"like" - {“device.communicationModules[].mobile.imei”: “351873000102290”}} ] })

with_select
def with_select(select_data: list[dict]) -> 'SearchBuilder'

Adds selection criteria to the search.

Arguments:

  • select_data list[dict] | SelectBuilder - The selection criteria to apply. Can be a list of dictionaries or a SelectBuilder instance.

Returns:

  • SearchBuilder - Returns itself to allow for method chaining.

with_limit
def with_limit(size: int, start: int = None) -> 'SearchBuilder'

Adds pagination parameters to the search.

Arguments:

  • size int - The number of entities to retrieve per page. Limit size value 1000
  • start int, optional - Page number you request. By default, is 1.

Returns:

  • SearchBuilder - Returns itself to allow for method chaining.

Example:

search_builder.with_limit(1000, 2)

add_by_group
def add_by_group(field_name: str) -> 'SearchBuilder'

Adds a field to the group.

Arguments:

  • field_name str - The name of the field to group by.

Returns:

  • SearchBuilder - Returns itself to allow for method chaining.

Example:

builder.add_by_group(“provision.device.model”) builder.add_by_group(“provision.device.software”)

add_sort_by
def add_sort_by(field_name: str, order: str) -> 'SearchBuilder'

Adds a field to the sort.

Arguments:

  • field_name str - The name of the field to sort by.
  • order str - The order of sorting, either ‘ASCENDING’ or ‘DESCENDING’.

Returns:

  • SearchBuilder - Returns itself to allow for method chaining.

Example:

builder.add_sort_by(“datapoints._current.at”, “DESCENDING”) builder.add_sort_by(“devices._current.at”, “ASCENDING”)

opengate_data.searching.search_base

SearchBuilderBase Objects

class SearchBuilderBase()

Search Base Builder

with_format
def with_format(format_data: str) -> 'SearchBuilderBase'

Formats the flat entities data based on the specified format (‘csv’, ‘dict’, or ‘pandas’).

Arguments:

  • format_data str - The format to use for the data.

Example:

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

Returns:

  • SearchBuilderBase - Returns itself to allow for method chaining.

with_flattened
def with_flattened() -> 'SearchBuilderBase'

Flatten the data

Returns:

  • SearchBuilderBase - Returns itself to allow for method chaining.

with_utc
def with_utc() -> 'SearchBuilderBase'

Set UTC flag

Returns:

  • SearchBuilderBase - Returns itself to allow for method chaining.

with_summary
def with_summary() -> 'SearchBuilderBase'

Set summary flag

Returns:

  • SearchBuilderBase - Returns itself to allow for method chaining.

with_default_sorted
def with_default_sorted() -> 'SearchBuilderBase'

Set default sorted flag

Returns:

  • SearchBuilderBase - Returns itself to allow for method chaining.

with_case_sensitive
def with_case_sensitive() -> 'SearchBuilderBase'

Set case-sensitive flag

Returns:

  • SearchBuilder - Returns itself to allow for method chaining.

opengate_data.searching.select

SelectBuilder Objects

class SelectBuilder()

A flexible builder for constructing SELECT clauses for several OpenGate entities.

This builder supports three independent modes, which cannot be mixed inside the same instance:

  1. Simple mode (Datasets, Timeseries search):
  • .add("field_name")
  • Produces: [“field1”, “field2”, …]
  1. Extended mode (Structured search):
  • .add("path.to.resource", ["field", ("other", "alias")])
  • Produces: [ { “name”: “…”, “fields”: [{ “field”: “…”, “alias”: “…” }] } ]
  1. Column mode (Timeseries EXPORT):
  • .add_column("FIRST")
  • .add_column("bucket_id", output={"parquet": {"type": "INT"}})
  • Produces: [ { “column”: “FIRST” }, { “column”: “bucket_id”, “output”: {…} } ]

You cannot mix modes. Each builder instance must use only one mode.

Examples:

Simple mode: SelectBuilder().add(“Gross”).add(“Temp”)

Extended mode: SelectBuilder().add(“provision.device.identifier”, [(“value”, “id”), “date”])

Column mode (Timeseries Export): SelectBuilder().add_column(“FIRST”).add_column(“LAST”)

Use .build() to retrieve the final SELECT list.

add
def add(name: str, fields=None)

Add a SELECT entry in either simple or extended mode.

Arguments:

  • name str - Field name (simple mode) or entity name (extended mode).
  • fields list, optional - Only for extended mode; list of strings or tuples (field, alias).

Returns:

  • SelectBuilder - fluent API.

add_column
def add_column(column_name: str, output: dict | None = None)

Add a Timeseries Export column entry.

Produces backend-compatible objects like: { “column”: “FIRST” } { “column”: “bucket_id”, “output”: {…} }

Arguments:

  • column_name str - Name of the export column.
  • output dict, optional - Optional output descriptor such as: { “parquet”: { “type”: “INT” } } { “name”: “serial_number”, “parquet”: { “type”: “STRING” } }

Returns:

  • SelectBuilder - fluent API.

build
def build()

Return the constructed SELECT list.

Raises:

  • ValueError - If no select elements were added.

Returns:

  • list - Dicts (column mode), strings (simple mode) or dicts (extended mode).