# Timeseries

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

## opengate\_data.timeseries.timeseries

Provision Timeseries Builder

<a id="opengate_data.timeseries.timeseries.TimeseriesBuilder"></a>

### TimeseriesBuilder Objects

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

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

<a id="opengate_data.timeseries.timeseries.TimeseriesBuilder.with_organization_name"></a>

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

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

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

<a id="opengate_data.timeseries.timeseries.TimeseriesBuilder.with_identifier"></a>

---
#### with\_identifier

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

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

<a id="opengate_data.timeseries.timeseries.TimeseriesBuilder.with_callback"></a>

---
#### with\_callback

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

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

<a id="opengate_data.timeseries.timeseries.TimeseriesBuilder.with_output_file"></a>

---
#### with\_output\_file

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

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

<a id="opengate_data.timeseries.timeseries.TimeseriesBuilder.with_sort"></a>

---
#### with\_sort

```python
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("<sortIdentifier>"),
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.

<a id="opengate_data.timeseries.timeseries.TimeseriesBuilder.export"></a>

---
#### export

```python
def export() -> "TimeseriesBuilder"
```

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

**Returns**:

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

**Example**:

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

<a id="opengate_data.timeseries.timeseries.TimeseriesBuilder.export_status"></a>

---
#### export\_status

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

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

<a id="opengate_data.timeseries.timeseries.TimeseriesBuilder.build"></a>

---
#### build

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

  ~~~python
  builder.export().build()
  ~~~

<a id="opengate_data.timeseries.timeseries.TimeseriesBuilder.build_execute"></a>

---
#### build\_execute

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

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

<a id="opengate_data.timeseries.timeseries.TimeseriesBuilder.execute"></a>

---
#### execute

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

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

<a id="opengate_data.timeseries.find_timeseries"></a>

## opengate\_data.timeseries.find\_timeseries

<a id="opengate_data.timeseries.find_timeseries.FindTimeseriesBuilder"></a>

### FindTimeseriesBuilder Objects

```python
class FindTimeseriesBuilder(SearchBuilder)
```

Find time series Builder

<a id="opengate_data.timeseries.find_timeseries.FindTimeseriesBuilder.with_expand"></a>

---
#### with\_expand

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

  ~~~python
  builder.with_expand("columns.context")
  ~~~

<a id="opengate_data.timeseries.find_timeseries.FindTimeseriesBuilder.with_datastreams"></a>

---
#### with\_datastreams

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

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

<a id="opengate_data.timeseries.find_timeseries.FindTimeseriesBuilder.with_organization_name"></a>

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

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

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

<a id="opengate_data.timeseries.find_timeseries.FindTimeseriesBuilder.with_format"></a>

---
#### with\_format

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

<a id="opengate_data.timeseries.find_timeseries.FindTimeseriesBuilder.with_sort"></a>

---
#### with\_sort

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

Set sort identifier

**Arguments**:

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

<a id="opengate_data.timeseries.find_timeseries.FindTimeseriesBuilder.with_identifier"></a>

---
#### with\_identifier

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

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

<a id="opengate_data.timeseries.find_timeseries.FindTimeseriesBuilder.with_config_file"></a>

---
#### with\_config\_file

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

<a id="opengate_data.timeseries.find_timeseries.FindTimeseriesBuilder.with_name"></a>

---
#### with\_name

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

  ~~~python
  builder.with_name('timeseries_name')
  ~~~

<a id="opengate_data.timeseries.find_timeseries.FindTimeseriesBuilder.with_env"></a>

---
#### with\_env

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

<a id="opengate_data.timeseries.find_timeseries.FindTimeseriesBuilder.find_all"></a>

---
#### find\_all

```python
def find_all() -> "FindTimeseriesBuilder"
```

Searches for all available timeseries resources.

**Returns**:

- `FindTimeseriesBuilder` - Returns the current instance to allow method chaining.
  

**Example**:

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

<a id="opengate_data.timeseries.find_timeseries.FindTimeseriesBuilder.find_one"></a>

---
#### find\_one

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

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

<a id="opengate_data.timeseries.find_timeseries.FindTimeseriesBuilder.build"></a>

---
#### build

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

  ~~~python
  builder.build()
  ~~~

<a id="opengate_data.timeseries.find_timeseries.FindTimeseriesBuilder.build_execute"></a>

---
#### build\_execute

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

  ~~~python
  builder.build_execute()
  ~~~

<a id="opengate_data.timeseries.find_timeseries.FindTimeseriesBuilder.execute"></a>

---
#### execute

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

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

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

## opengate\_data.timeseries