Searching

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_base

SearchBuilderBase Objects

class SearchBuilderBase()

Search Base Builder

build

def build()

Finalizes the construction of the search configuration.

build_execute

def build_execute()

Short-cut for build().execute()

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:

SearchBuilderBase - 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:

Simple mode (Datasets, Timeseries search):

.add("field_name")
Produces: [“field1”, “field2”, …]

Extended mode (Structured search):

.add("path.to.resource", ["field", ("other", "alias")])
Produces: [ { “name”: “…”, “fields”: [{ “field”: “…”, “alias”: “…” }] } ]

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

opengate_data.searching.builder.rules_search

RulesSearchBuilder

RulesSearchBuilder Objects

class RulesSearchBuilder(SearchBuilderBase, 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:

RulesSearchBuilder - Returns itself to allow for method chaining.

Example:

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

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_format("dict").build_execute()
new_rules_search_builder.with_filter(filter).with_format("pandas").build_execute()

opengate_data.searching.builder.alarm_search

AlarmSearchBuilder

AlarmSearchBuilder Objects

class AlarmSearchBuilder(SearchBuilderBase, SearchBuilder)

Alarm Search Builder

Searches the alarms raised by the platform’s rules, over /v80/search/entities/alarms. Compose the query with the inherited with_filter, with_select, with_limit and with_format methods, then close it with build() and execute(), or with build_execute().

Example:

builder = client.new_alarm_search_builder()
filter_open = client.new_filter_builder().eq("alarm.status", "OPEN").build()
builder.with_filter(filter_open).with_format("pandas").build_execute()

validate_builds

def validate_builds()

Checks the combination of methods called before the search is sent.

Returns:

AlarmSearchBuilder - Returns itself to allow for method chaining.

Raises:

ValueError - If with_format received something other than “dict”, “csv” or “pandas”.
Exception - If “csv” is combined with with_limit, or used without with_select — the CSV output needs to know its columns.

execute

def execute()

Executes the alarm search based on the built configuration.

with_summary() switches the request to /search/entities/alarms/summary and returns the aggregated counters instead of the alarms themselves.

Returns:

str | pandas.DataFrame: A JSON string for the “dict” format, raw text for “csv”, or a DataFrame of flattened records for “pandas”.

Raises:

Exception - If build() was not the last call before execute(), or if neither build() nor build_execute() was called.

Example:

builder.with_filter(filter_open).with_format("dict").build().execute()

opengate_data.searching.builder.operations_search

OperationsBuilder

OperationsSearchBuilder Objects

class OperationsSearchBuilder(SearchBuilderBase, SearchBuilder)

Builder Operations Search

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").build().execute()
new_operations_search_builder.with_filter(filter).with_format("pandas").build().execute()
new_operations_search_builder.with_filter(filter).with_format("dict").build().execute()

opengate_data.searching.builder.datasets_search

DatasetsSearchBuilder

DatasetsSearchBuilder Objects

class DatasetsSearchBuilder(SearchBuilderBase, SearchBuilder)

Dataset Search Builder

with_organization_name

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

Set organization name

Arguments:

organization_name str - The name of the organization that owns the data set.

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

Arguments:

identifier str - The identifier of the data set to query.

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

with_sort

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

Set the sort identifier.

The value must be the identifier of one of the sorts declared in the dataset definition “sorts” section (the auto-generated reverse sorts are also valid). When omitted, results are sorted by the identifier column ascending.

The sort is sent in the payload for every format. NOTE: the platform currently ignores the sort for ‘csv’ and ‘pandas’ exports (a server/database limitation, not an SDK decision); it is still sent so the SDK stays forward-compatible if the backend starts honoring it.

Arguments:

sort str - The sort identifier declared in the dataset definition.

Returns:

DatasetsSearchBuilder - Returns itself to allow for method chaining.

Example:

builder.with_sort("sortByProvIdentifierDesc")

add_sort_by

def add_sort_by(field_name: str, order: str) -> "DatasetsSearchBuilder"

Deprecated for datasets. The dataset search API no longer accepts the object-based sort format; sorts are now declared in the dataset definition and referenced by identifier.

Raises:

NotImplementedError - Always. Use with_sort() instead.

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

opengate_data.searching.builder.datapoints_search

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]] - The mapping of complex data to flat columns. The main key is the column name, and its value another dictionary defining the mapping of the 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()

opengate_data.searching.builder.timeseries_search

TimeseriesSearchBuilder Objects

class TimeseriesSearchBuilder(SearchBuilderBase, SearchBuilder)

Timeseries Search Builder

with_organization_name

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

Set organization name

Arguments:

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

with_identifier

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

Set identifier

Arguments:

identifier str - The identifier of the timeseries to query.

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’).

Arguments:

format_data str - The format to return the data in: ‘dict’, ‘csv’ or ‘pandas’.

with_sort

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

Set sort identifier

Arguments:

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

execute

def execute()

Executes the timeseries search based on the built configuration.

opengate_data.searching.builder

opengate_data.searching.builder.entities_search

EntitiesSearchBuilder

EntitiesSearchBuilder Objects

class EntitiesSearchBuilder(SearchBuilderBase, SearchBuilder)

Entities Search Builder

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).build().execute()
new_entities_search_builder.with_filter(filter).with_format("pandas").build().execute()
new_entities_search_builder.with_filter(filter).with_format("dict").build().execute()

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