# Searching

<a id="opengate_data.searching.filter"></a>

## opengate\_data.searching.filter

<a id="opengate_data.searching.filter.FilterBuilder"></a>

### FilterBuilder Objects

```python
class FilterBuilder(Expressions)
```

Filter Builder

<a id="opengate_data.searching.filter.FilterBuilder.and_"></a>

---
#### and\_

```python
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_.*")
  )

<a id="opengate_data.searching.filter.FilterBuilder.or_"></a>

---
#### or\_

```python
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_.*")
  )

<a id="opengate_data.searching.filter.FilterBuilder.build"></a>

---
#### build

```python
def build()
```

Builds the final filter.

**Returns**:

- `dict` - The final filter.
  

**Raises**:

- `ValueError` - If there is an incomplete condition.
  

**Example**:

  builder.build()

<a id="opengate_data.searching.search_base"></a>

## opengate\_data.searching.search\_base

<a id="opengate_data.searching.search_base.SearchBuilderBase"></a>

### SearchBuilderBase Objects

```python
class SearchBuilderBase()
```

Search Base Builder

<a id="opengate_data.searching.search_base.SearchBuilderBase.build"></a>

---
#### build

```python
def build()
```

Finalizes the construction of the search configuration.

<a id="opengate_data.searching.search_base.SearchBuilderBase.build_execute"></a>

---
#### build\_execute

```python
def build_execute()
```

Short-cut for build().execute()

<a id="opengate_data.searching.search_base.SearchBuilderBase.with_format"></a>

---
#### with\_format

```python
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.

<a id="opengate_data.searching.search_base.SearchBuilderBase.with_flattened"></a>

---
#### with\_flattened

```python
def with_flattened() -> "SearchBuilderBase"
```

Flatten the data

**Returns**:

- `SearchBuilderBase` - Returns itself to allow for method chaining.

<a id="opengate_data.searching.search_base.SearchBuilderBase.with_utc"></a>

---
#### with\_utc

```python
def with_utc() -> "SearchBuilderBase"
```

Set UTC flag

**Returns**:

- `SearchBuilderBase` - Returns itself to allow for method chaining.

<a id="opengate_data.searching.search_base.SearchBuilderBase.with_summary"></a>

---
#### with\_summary

```python
def with_summary() -> "SearchBuilderBase"
```

Set summary flag

**Returns**:

- `SearchBuilderBase` - Returns itself to allow for method chaining.

<a id="opengate_data.searching.search_base.SearchBuilderBase.with_default_sorted"></a>

---
#### with\_default\_sorted

```python
def with_default_sorted() -> "SearchBuilderBase"
```

Set default sorted flag

**Returns**:

- `SearchBuilderBase` - Returns itself to allow for method chaining.

<a id="opengate_data.searching.search_base.SearchBuilderBase.with_case_sensitive"></a>

---
#### with\_case\_sensitive

```python
def with_case_sensitive() -> "SearchBuilderBase"
```

Set case-sensitive flag

**Returns**:

- `SearchBuilderBase` - Returns itself to allow for method chaining.

<a id="opengate_data.searching.select"></a>

## opengate\_data.searching.select

<a id="opengate_data.searching.select.SelectBuilder"></a>

### SelectBuilder Objects

```python
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", ...]

2. **Extended mode** (Structured search):
- `.add("path.to.resource", ["field", ("other", "alias")])`
- Produces:
[
{ "name": "...", "fields": [{ "field": "...", "alias": "..." }] }
]

3. **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.

<a id="opengate_data.searching.select.SelectBuilder.add"></a>

---
#### add

```python
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.

<a id="opengate_data.searching.select.SelectBuilder.add_column"></a>

---
#### add\_column

```python
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.

<a id="opengate_data.searching.select.SelectBuilder.build"></a>

---
#### build

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

<a id="opengate_data.searching.builder.rules_search"></a>

## opengate\_data.searching.builder.rules\_search

RulesSearchBuilder

<a id="opengate_data.searching.builder.rules_search.RulesSearchBuilder"></a>

### RulesSearchBuilder Objects

```python
class RulesSearchBuilder(SearchBuilderBase, SearchBuilder)
```

Rules Search Builder

<a id="opengate_data.searching.builder.rules_search.RulesSearchBuilder.with_format"></a>

---
#### with\_format

```python
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**:

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

<a id="opengate_data.searching.builder.rules_search.RulesSearchBuilder.execute"></a>

---
#### execute

```python
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**:

  ~~~python
  new_rules_search_builder.with_filter(filter).with_format("dict").build_execute()
  new_rules_search_builder.with_filter(filter).with_format("pandas").build_execute()
  ~~~

<a id="opengate_data.searching.builder.alarm_search"></a>

## opengate\_data.searching.builder.alarm\_search

AlarmSearchBuilder

<a id="opengate_data.searching.builder.alarm_search.AlarmSearchBuilder"></a>

### AlarmSearchBuilder Objects

```python
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**:

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

<a id="opengate_data.searching.builder.alarm_search.AlarmSearchBuilder.validate_builds"></a>

---
#### validate\_builds

```python
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.

<a id="opengate_data.searching.builder.alarm_search.AlarmSearchBuilder.execute"></a>

---
#### execute

```python
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**:

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

<a id="opengate_data.searching.builder.operations_search"></a>

## opengate\_data.searching.builder.operations\_search

OperationsBuilder

<a id="opengate_data.searching.builder.operations_search.OperationsSearchBuilder"></a>

### OperationsSearchBuilder Objects

```python
class OperationsSearchBuilder(SearchBuilderBase, SearchBuilder)
```

Builder Operations Search

<a id="opengate_data.searching.builder.operations_search.OperationsSearchBuilder.execute"></a>

---
#### execute

```python
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**:

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

<a id="opengate_data.searching.builder.datasets_search"></a>

## opengate\_data.searching.builder.datasets\_search

DatasetsSearchBuilder

<a id="opengate_data.searching.builder.datasets_search.DatasetsSearchBuilder"></a>

### DatasetsSearchBuilder Objects

```python
class DatasetsSearchBuilder(SearchBuilderBase, SearchBuilder)
```

Dataset Search Builder

<a id="opengate_data.searching.builder.datasets_search.DatasetsSearchBuilder.with_organization_name"></a>

---
#### with\_organization\_name

```python
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**:

  ~~~python
  builder.with_organization_name("organization_name")
  ~~~

<a id="opengate_data.searching.builder.datasets_search.DatasetsSearchBuilder.with_identifier"></a>

---
#### with\_identifier

```python
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**:

  ~~~python
  builder.with_identifier("identifier")
  ~~~

<a id="opengate_data.searching.builder.datasets_search.DatasetsSearchBuilder.with_utc"></a>

---
#### with\_utc

```python
def with_utc() -> "DatasetsSearchBuilder"
```

Set UTC

**Returns**:

- `DatasetsSearchBuilder` - Returns itself to allow for method chaining.
  

**Example**:

  ~~~python
  builder.with_utc()
  ~~~

<a id="opengate_data.searching.builder.datasets_search.DatasetsSearchBuilder.with_format"></a>

---
#### with\_format

```python
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**:

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

<a id="opengate_data.searching.builder.datasets_search.DatasetsSearchBuilder.with_sort"></a>

---
#### with\_sort

```python
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**:

  ~~~python
  builder.with_sort("sortByProvIdentifierDesc")
  ~~~

<a id="opengate_data.searching.builder.datasets_search.DatasetsSearchBuilder.add_sort_by"></a>

---
#### add\_sort\_by

```python
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.

<a id="opengate_data.searching.builder.datasets_search.DatasetsSearchBuilder.execute"></a>

---
#### execute

```python
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**:

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

<a id="opengate_data.searching.builder.datapoints_search"></a>

## opengate\_data.searching.builder.datapoints\_search

<a id="opengate_data.searching.builder.datapoints_search.DataPointsSearchBuilder"></a>

### DataPointsSearchBuilder Objects

```python
class DataPointsSearchBuilder(SearchBuilderBase, SearchBuilder)
```

Datapoints Search Builder

<a id="opengate_data.searching.builder.datapoints_search.DataPointsSearchBuilder.with_transpose"></a>

---
#### with\_transpose

```python
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**:

  ~~~python
  builder.with_transpose()
  ~~~

<a id="opengate_data.searching.builder.datapoints_search.DataPointsSearchBuilder.with_mapped_transpose"></a>

---
#### with\_mapped\_transpose

```python
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**:

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

<a id="opengate_data.searching.builder.datapoints_search.DataPointsSearchBuilder.execute"></a>

---
#### execute

```python
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**:

  ~~~python
  builder.execute()
  ~~~

<a id="opengate_data.searching.builder.timeseries_search"></a>

## opengate\_data.searching.builder.timeseries\_search

<a id="opengate_data.searching.builder.timeseries_search.TimeseriesSearchBuilder"></a>

### TimeseriesSearchBuilder Objects

```python
class TimeseriesSearchBuilder(SearchBuilderBase, SearchBuilder)
```

Timeseries Search Builder

<a id="opengate_data.searching.builder.timeseries_search.TimeseriesSearchBuilder.with_organization_name"></a>

---
#### with\_organization\_name

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

Set organization name

**Arguments**:

- `organization_name` _str_ - The name of the organization that owns the timeseries.

<a id="opengate_data.searching.builder.timeseries_search.TimeseriesSearchBuilder.with_identifier"></a>

---
#### with\_identifier

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

Set identifier

**Arguments**:

- `identifier` _str_ - The identifier of the timeseries to query.

<a id="opengate_data.searching.builder.timeseries_search.TimeseriesSearchBuilder.with_utc"></a>

---
#### with\_utc

```python
def with_utc() -> "TimeseriesSearchBuilder"
```

Set UTC flag for date-time parsing

<a id="opengate_data.searching.builder.timeseries_search.TimeseriesSearchBuilder.with_format"></a>

---
#### with\_format

```python
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'.

<a id="opengate_data.searching.builder.timeseries_search.TimeseriesSearchBuilder.with_sort"></a>

---
#### with\_sort

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

Set sort identifier

**Arguments**:

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

<a id="opengate_data.searching.builder.timeseries_search.TimeseriesSearchBuilder.execute"></a>

---
#### execute

```python
def execute()
```

Executes the timeseries search based on the built configuration.

<a id="opengate_data.searching.builder"></a>

## opengate\_data.searching.builder

<a id="opengate_data.searching.builder.entities_search"></a>

## opengate\_data.searching.builder.entities\_search

EntitiesSearchBuilder

<a id="opengate_data.searching.builder.entities_search.EntitiesSearchBuilder"></a>

### EntitiesSearchBuilder Objects

```python
class EntitiesSearchBuilder(SearchBuilderBase, SearchBuilder)
```

Entities Search Builder

<a id="opengate_data.searching.builder.entities_search.EntitiesSearchBuilder.execute"></a>

---
#### execute

```python
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**:

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

<a id="opengate_data.searching.search"></a>

## opengate\_data.searching.search

SearchBuilder

<a id="opengate_data.searching.search.SearchBuilder"></a>

### SearchBuilder Objects

```python
class SearchBuilder()
```

Search Builder

<a id="opengate_data.searching.search.SearchBuilder.with_filter"></a>

---
#### with\_filter

```python
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"}}
  ]
  })

<a id="opengate_data.searching.search.SearchBuilder.with_select"></a>

---
#### with\_select

```python
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.

<a id="opengate_data.searching.search.SearchBuilder.with_limit"></a>

---
#### with\_limit

```python
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)

<a id="opengate_data.searching.search.SearchBuilder.add_by_group"></a>

---
#### add\_by\_group

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

<a id="opengate_data.searching.search.SearchBuilder.add_sort_by"></a>

---
#### add\_sort\_by

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

<a id="opengate_data.searching"></a>

## opengate\_data.searching