Calculate the result of a function on time series

Calculate the result of a function on time series.

Info:: You can read the guide to synthetic time series in our documentation.

Parameters:

expressions (str | sympy.Basic | Sequence[str] | Sequence[sympy.Basic]) – Functions to be calculated. Supports both strings and sympy expressions. Strings can have either the API ts{} syntax, or contain variable names to be replaced using the variables parameter.
start (int | str | datetime.datetime) – Inclusive start.
end (int | str | datetime.datetime) – Exclusive end.
limit (int | None) – Number of datapoints per expression to retrieve.
variables (Mapping[str | sympy.Symbol, str | NodeId | TimeSeries | TimeSeriesWrite] | None) – An optional map of symbol replacements.
aggregate (str | None) – use this aggregate when replacing entries from variables, does not affect time series given in the ts{} syntax.
granularity (str | None) – use this granularity with the aggregate.
target_unit (str | None) – use this target_unit when replacing entries from variables, does not affect time series given in the ts{} syntax.
target_unit_system (str | None) – Same as target_unit, but with unit system (e.g. SI). Only one of target_unit and target_unit_system can be specified.
timezone (str | datetime.timezone | ZoneInfo | None) – The timezone to use when aggregating datapoints. For aggregates of granularity ‘hour’ and longer, which time zone should we align to. Align to the start of the hour, start of the day or start of the month. For time zones of type Region/Location, the aggregate duration can vary, typically due to daylight saving time. For time zones of type UTC+/-HH:MM, use increments of 15 minutes. Default: “UTC” (None)

Returns:

A SyntheticDatapointsList object containing the calculated data.

Return type:

SyntheticDatapoints | SyntheticDatapointsList

Examples

Execute a synthetic time series query with an expression. Here we sum three time series plus a constant. The first is referenced by ID, the second by external ID, and the third by instance ID:

>>> from cognite.client import CogniteClient, AsyncCogniteClient
>>> client = CogniteClient()
>>> # async_client = AsyncCogniteClient()  # another option
>>> expression = '''
...     123
...     + ts{id:123}
...     + ts{externalId:'abc'}
...     + ts{space:'my-space',externalId:'my-ts-xid'}
... '''
>>> dps = client.time_series.data.synthetic.query(
...     expressions=expression, start="2w-ago", end="now"
... )

You can also specify variables for an easier query syntax:

>>> from cognite.client.data_classes.data_modeling.ids import NodeId
>>> ts = client.time_series.retrieve(id=123)
>>> variables = {
...     "A": ts,
...     "B": "my_ts_external_id",
...     "C": NodeId("my-space", "my-ts-xid"),
... }
>>> dps = client.time_series.data.synthetic.query(
...     expressions="A+B+C", start="2w-ago", end="2w-ahead", variables=variables
... )

Use sympy to build complex expressions:

>>> from sympy import symbols, cos, sin
>>> x, y = symbols("x y")
>>> dps = client.time_series.data.synthetic.query(
...     [sin(x), y * cos(x)],
...     start="2w-ago",
...     end="now",
...     variables={x: "foo", y: "bar"},
...     aggregate="interpolation",
...     granularity="15m",
...     target_unit="temperature:deg_c",
...     timezone="Europe/Oslo",  # can also use this format: 'UTC+05:30'
... )