Config

Project Configuration Module.

This module allows you to set an api-key and a project for your python project.

cognite.config.configure_session(api_key='', project='', cookies=None, debug=False)

Sets session variables.

Parameters:
  • api_key (str) – Api-key for current project.
  • cookies (dict) – Cookies to pass with requests.
  • project (str) – Project name for current project.
  • debug (bool) – Whether or not to ouptut a debug log.
cognite.config.get_base_url()

Returns the current base url for requests made from the SDK. :param api_version: Version of API to use for base_url :type api_version: float

Returns:current base url.
Return type:str
cognite.config.get_config_variables(api_key, project)

Returns current project config variables unless other is specified.

Parameters:
  • api_key (str) – Other specified api-key.
  • project (str) – Other specified project name.
Returns:

api-key and project name belonging to current project unless other is specified.

Return type:

tuple

cognite.config.get_cookies(cookies=None)

Returns cookies set for the current session.

Returns:Cookies for current session.
Return type:dict
cognite.config.get_number_of_retries()

Returns the current number of retries attempted for requests made from the SDK.

Returns:current number of retries attempted for requests.
Return type:int
cognite.config.set_base_url(url=None)

Sets the base url for requests made from the SDK.

Parameters:url (str) – URL to set. Set this to None to use default url.
cognite.config.set_number_of_retries(retries: int = None)

Sets the number of retries attempted for requests made from the SDK.

Parameters:retries (int) – Number of retries to attempt. Set this to None to use default num of retries.

Preprocessing

Preprocessing module.

This module provides a number of preprocessing methods to further clean the data retrieved from the Cognite API.

cognite.preprocessing.fill_nan(dataframe)

Uses step interpolation to replace NaN values with the previous non-NaN value.

Parameters:dataframe (pandas.DataFrame) – Input dataframe.
Returns:Input dataframe with NaN values removed by forward fill.
Return type:pandas.DataFrame
cognite.preprocessing.make_index_even(dataframe)

Creates time index with evenly spaced intervals. Adds NaN to timestamps with missing values.

Parameters:dataframe (pandas.DataFrame) – Input dataframe.
Returns:Input dataframe with evenly spaced intervals.
Return type:pandas.DataFrame
cognite.preprocessing.merge_list_of_dataframes(dataframes)

Merges together a list of dataframes and creates a time index with evenly spaced intervals.

Adds NaN to timestamps with missing values.

Parameters:dataframes (list(pandas.DataFrame)) – Input dataframes.
Returns:Dataframes merged into one with evenly spaced intervals.
Return type:pandas.DataFrame
cognite.preprocessing.normalize(dataframe)

Centers and scales each column in the data frame to zero mean and unit variance.

Parameters:dataframe (pandas.DataFrame) – Input dataframe.
Returns:Normalized dataframe.
Return type:pandas.DataFrame
cognite.preprocessing.preprocess(dataframe, remove_leading_nan_rows=False, center_and_scale=False)

Performs a series of preprocessing steps on the given dataframe.

  1. Creates an evenly spaced time index
  2. Forward fills NaN values
  3. Either removes leading rows with nan values or removes columns with leading nan values
  4. Removes columns with zero variance
  5. Optionally centers and scales the dataframe to zero mean and unit variance.
Parameters:
  • dataframe (pandas.DataFrame) – Input dataframe.
  • remove_leading_nan_rows (bool, optional) – Whether or not to skip leading rows containing NaN values.
  • center_and_scale (bool, optional) – Whether or not to normalize the data.
Returns:

tuple containing:

pandas.DataFrame: Dataframe with zero-variance columns removed. numpy.array: Array of bools indicating which columns were kept.

Return type:

tuple

cognite.preprocessing.remove_nan_columns(dataframe)

Removes columns of data frame where any value is NaN.

Parameters:dataframe (pandas.DataFrame) – Input dataframe.
Returns:
tuple containing:
pandas.DataFrame: Dataframe with columns containing NaN values removed. numpy.array: Array of bools indicating which columns were kept.
Return type:tuple
cognite.preprocessing.remove_zero_variance_columns(dataframe)

Removes columns with zero variance.

Parameters:dataframe (pandas.DataFrame) – Input dataframe.
Returns:
tuple containing:
pandas.DataFrame: Dataframe with zero-variance columns removed. numpy.array: Array of bools indicating which columns were kept.
Return type:tuple

Data Transfer Service

class cognite.data_transfer_service.DataSpec(time_series_data_specs: List[cognite.data_transfer_service.TimeSeriesDataSpec] = None, files_data_spec: cognite.data_transfer_service.FilesDataSpec = None)

Bases: object

Object for specifying data when querying CDP.

Parameters:
Raises:

DataSpecValidationError – An error occurred while validating the data spec

classmethod from_JSON(json_repr)
to_JSON()
exception cognite.data_transfer_service.DataSpecValidationError

Bases: Exception

class cognite.data_transfer_service.DataTransferService(data_spec: cognite.data_transfer_service.DataSpec, project: str = None, api_key: str = None, cookies: Dict = None, num_of_processes: int = 10)

Bases: object

Create a Data Transfer Service object.

Fetch timeseries from the api.

get_dataframe(label: str = 'default', drop_agg_suffix: bool = True)
get_dataframes(drop_agg_suffix: bool = True)

Return a dictionary of dataframes indexed by label - one per data spec.

Parameters:drop_agg_suffix (bool) – If a time series has only one aggregate, drop the |<agg-func> suffix on those column names.
Returns:A label-indexed dictionary of data frames.
Return type:Dict[str, pd.DataFrame]
get_file(name)

Return files by name as specified in the DataSpec

Parameters:name (str) – Name of file
get_time_series_name(ts_label: str, dataframe_label: str = 'default')
class cognite.data_transfer_service.FilesDataSpec(file_ids: Dict[str, int])

Bases: object

Object for specifying data from the Files API when using a data spec.

Parameters:file_ids (Dict[str, int]) – Dictionary of fileNames -> fileIds
class cognite.data_transfer_service.TimeSeries(id: int, aggregates: List[str] = None, missing_data_strategy: str = None, label: str = None)

Bases: object

Object for specifying a specific time series from the TimeSeries API when using a data spec.

Parameters:
  • id (int) – id of time series to retrieve
  • aggregates (List[str]) – Local aggregate functions to apply
  • missing_data_strategy (str) – Missing data strategy to apply
  • label (str) – name of the column in the resulting data frame when passed to data transfer service.

Examples

When you supply a label the resulting data frames produced by data transfer service will use the label as column names.

class cognite.data_transfer_service.TimeSeriesDataSpec(time_series: List[cognite.data_transfer_service.TimeSeries], aggregates: List[str], granularity: str, missing_data_strategy: str = None, start: Union[str, int, datetime.datetime] = None, end: Union[str, int, datetime.datetime] = None, label: str = None)

Bases: object

Object for specifying data from the TimeSeries API when using a data spec.

Parameters:
  • time_series (List[data_transfer_service.TimeSeries]) – Time series
  • aggregates (List[str]) – List of aggregate functions
  • granularity (str) – Granularity of aggregates
  • missing_data_strategy (str) – Missing data strategy to apply, can be “linearInterpolation” or “ffill”
  • start (Union[str, int, datetime]) – Start time
  • end (Union[str, int, datetime]) – end time
  • label (str) – Label for this data spec

Examples

When you specify a label, data transfer service will exhibit the following behaviour:

ts_data_spec = TimeSeriesDataSpec(..., label="some_label")
data_spec = DataSpec([ts_data_spec], ...)
dts = DataTransferService(data_spec)
dataframes = dts.get_dataframes
my_df = dataframes["some_label"]

API v0.6

Analytics

Models

Models Module.

This module mirrors the Models API.

https://doc.cognitedata.com/0.6/models

cognite.v06.analytics.models.create_model(name: str, description: str = '', metadata: Dict[str, Any] = None, input_fields: List[str] = None, output_fields: List[str] = None, **kwargs)

Creates a new model

Parameters:
  • name (str) – Name of model
  • description (str) – Description
  • metadata (Dict[str, Any]) – Metadata about model
  • input_fields (List[str]) – List of input fields the model accepts
  • (List[str] (output_fields) – List of output fields the model produces
Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

The created model.

Return type:

Dict

cognite.v06.analytics.models.create_schedule(model_id: int, name: str, output_data_spec: Dict, input_data_spec: Dict, description: str = None, args: Dict = None, metadata: Dict = None, **kwargs)

Create a new schedule on a given model.

Parameters:
  • model_id (int) – Id of model to create schedule on
  • name (str) – Name of schedule
  • output_data_spec (Dict) – Specification of output. Example below.
  • input_data_spec (Dict) – Specification of input. Example below.
  • description (str) – Description for schedule
  • args (Dict) – Dictionary of keyword arguments to pass to predict method.
  • metadata (Dict) – Dictionary of metadata about schedule
Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

The created schedule.

Return type:

Dict

Examples

The output data spec must look like this:

{
    "timeSeries": [
        {
            "label": "string",
            "id": 123456789
        }
    ]
}

The input data spec must look like this. The local aggregate and the missingDataStrategy fields are optional:

{
    "windowSize": "1s",
    "stride": "1s",
    "missingDataStrategy": "",
    "timeSeries": [
      {
        "label": "string",
        "id": 0,
        "missingDataStrategy": "string",
        "aggregate": "string"
      }
    ],
    "aggregate": "string",
    "granularity": "string"
}
cognite.v06.analytics.models.create_source_package(name: str, package_name: str, available_operations: List[str], runtime_version: str, description: str = None, meta_data: Dict = None, file_path: str = None, **kwargs)

Upload a source package to the model hosting environment.

Parameters:
  • name (str) – Name of source package
  • package_name (str) – name of root package for model
  • available_operations (List[str]) – List of routines which this source package supports [“predict”, “train”]
  • runtime_version (str) – Version of environment in which the source-package should run. Currently only 0.1.
  • description (str) – Description for source package
  • meta_data (Dict) – User defined key value pair of additional information.
  • file_path (str) – File path of source package distribution. If not specified, a download url will be returned.
Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

Source package ID if file path was specified. Else, source package id and upload url.

Return type:

Dict

cognite.v06.analytics.models.delete_model(model_id: int, **kwargs)

Delete a model.

Will also delete all versions and schedules for this model.

Parameters:

model_id (int) – Delete model with this id.

Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

Empty Response

Return type:

Dict

cognite.v06.analytics.models.delete_schedule(schedule_id: int, **kwargs)

Delete a schedule by id.

Parameters:

schedule_id (int) – The id of the schedule to delete.

Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

Empty response

Return type:

Dict

cognite.v06.analytics.models.delete_source_package(source_package_id: int, **kwargs)

Delete source package by id.

Parameters:

source_package_id (int) – Id of soure package to delete.

Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

Empty response.

Return type:

Dict

cognite.v06.analytics.models.delete_version(model_id: int, version_id: int, **kwargs)

Delete a model version by id.

Parameters:
  • model_id (int) – Id of model which has the model version.
  • version_id (int) – Id of model version.
Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

The requested model version

Return type:

Dict

cognite.v06.analytics.models.get_model(model_id: int, **kwargs)

Get a model by id.

Parameters:

model_id (int) – Id of model to get.

Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

The requested model

Return type:

Dict

cognite.v06.analytics.models.get_models(**kwargs)

Get all models.

Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

List of models

Return type:

List[Dict]

cognite.v06.analytics.models.get_schedule(schedule_id: int, **kwargs)

Get a schedule by id.

Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

The requested schedule.

Return type:

Dict

cognite.v06.analytics.models.get_schedules(**kwargs)

Get all schedules.

Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

The requested schedules.

Return type:

List[Dict]

cognite.v06.analytics.models.get_source_package(source_package_id: int, **kwargs)

Get model source package by id.

Parameters:

source_package_id (int) – Id of soure package to get.

Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

The requested source package.

Return type:

Dict

cognite.v06.analytics.models.get_source_packages(**kwargs)

Get all model source packages.

Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

List of source packages.

Return type:

List[Dict]

cognite.v06.analytics.models.get_version(model_id: int, version_id: int, **kwargs)

Get a specific model version by id.

Parameters:
  • model_id (int) – Id of model which has the model version.
  • version_id (int) – Id of model version.
Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

The requested model version

Return type:

Dict

cognite.v06.analytics.models.get_versions(model_id: int, **kwargs)

Get all versions of a specific model.

Parameters:

model_id (int) – Get versions for the model with this id.

Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

List of model versions

Return type:

List[Dict]

cognite.v06.analytics.models.online_predict(model_id: int, version_id: int = None, instances: List = None, args: Dict[str, Any] = None, **kwargs)

Perform online prediction on a models active version or a specified version.

Parameters:
  • model_id (int) – Perform a prediction on the model with this id. Will use active version.
  • version_id (int) – Use this version instead of the active version. (optional)
  • instances (List) – List of JSON serializable instances to pass to your model one-by-one.
  • args (Dict[str, Any]) –
Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

List of predictions for each instance.

Return type:

List

cognite.v06.analytics.models.train_model_version(model_id: int, name: str, source_package_id: int, train_source_package_id: int = None, metadata: Dict = None, description: str = None, args: Dict[str, Any] = None, scale_tier: str = None, machine_type: str = None, **kwargs)

Train a new version of a model.

Parameters:
  • model_id (int) – Create a new version under the model with this id
  • name (str) – Name of model version. Must be unique on the model.
  • source_package_id (int) – Use the source package with this id
  • train_source_package_id (int) – Use this source package for training. If omitted, will default to source_package_id.
  • metadata (Dict[str, Any]) – Metadata about model version
  • description (str) – Description of model version
  • args (Dict[str, Any]) – Dictionary of arguments to pass to the training job.
  • scale_tier (str) – Which scale tier to use. Must be either “BASIC” or “CUSTOM”
  • machine_type (str) – Specify a machiene type Applies only if scale_tier is “CUSTOM”.
Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

The created model version.

Return type:

Dict

Time Series

Timeseries Module

This module mirrors the Timeseries API. It allows you to fetch data from the api and output it in various formats.

https://doc.cognitedata.com/0.6/#Cognite-API-Time-series

cognite.v06.time_series.get_multiple_time_series_by_id(ids, include_metadata=False, **kwargs)

Returns a TimeseriesResponse object containing the requested timeseries.

Parameters:

ids (List[int]) – IDs of timeseries to look up

Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

A data object containing the requested timeseries with several getter methods with different output formats.

Return type:

v05.dto.TimeSeriesResponse

cognite.v06.time_series.get_time_series_by_id(id, include_metadata=False, **kwargs)

Returns a TimeseriesResponse object containing the requested timeseries.

Parameters:
  • id (int) – ID of timeseries to look up
  • include_metadata (bool) – Decide if the metadata field should be returned or not. Defaults to False.
Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

A data object containing the requested timeseries.

Return type:

v05.dto.TimeSeriesResponse

cognite.v06.time_series.search_for_time_series(name=None, description=None, query=None, unit=None, is_string=None, is_step=None, metadata=None, asset_ids=None, asset_subtrees=None, min_created_time=None, max_created_time=None, min_last_updated_time=None, max_last_updated_time=None, **kwargs)

Returns a TimeSeriesResponse object containing the search results.

Parameters:
  • name (str) – Prefix and fuzzy search on name.
  • description (str) – Prefix and fuzzy search on description.
  • query (str) – Search on name and description using wildcard search on each of the words (separated by spaces). Retrieves results where at least on word must match. Example: “some other”
  • unit (str) – Filter on unit (case-sensitive)
  • is_string (bool) – Filter on whether the ts is a string ts or not.
  • is_step (bool) – Filter on whether the ts is a step ts or not.
  • metadata (Dict) – Filter out time series that do not match these metadata fields and values (case-sensitive). Format is {“key1”: “val1”, “key2”, “val2”}
  • asset_ids (List) – Filter out time series that are not linked to any of these assets. Format is [12,345,6,7890].
  • asset_subtrees (List) – Filter out time series that are not linked to assets in the subtree rooted at these assets. Format is [12,345,6,7890].
  • min_created_time (int) – Filter out time series with createdTime before this. Format is milliseconds since epoch.
  • max_created_time (int) – Filter out time series with createdTime after this. Format is milliseconds since epoch.
  • min_last_updated_time (int) – Filter out time series with lastUpdatedTime before this. Format is milliseconds since epoch.
  • max_last_updated_time (int) – Filter out time series with lastUpdatedTime after this. Format is milliseconds since epoch.
Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
  • sort (str) – “createdTime” or “lastUpdatedTime”. Field to be sorted. If not specified, results are sorted by relevance score.
  • dir (str) – “asc” or “desc”. Only applicable if sort is specified. Default ‘desc’.
  • limit (int) – Return up to this many results. Maximum is 1000. Default is 25.
  • offset (int) – Offset from the first result. Sum of limit and offset must not exceed 1000. Default is 0.
  • boost_name (bool) – Whether or not boosting name field. This option is experimental and can be changed.
Returns:

A data object containing the requested timeseries with several getter methods with different output formats.

Return type:

v05.dto.TimeSeriesResponse

Datapoints

Datapoints Module

This module mirrors the Datapoints API. It allows you to fetch data from the api and output it in various formats.

https://doc.cognitedata.com/0.6/#Cognite-API-Datapoints

cognite.v06.datapoints.get_datapoints(id, start, end=None, aggregates=None, granularity=None, **kwargs)

Returns a DatapointsObject containing a list of datapoints for the given query.

This method will automate paging for the user and return all data for the given time period.

Parameters:
  • id (int) – The unique id of the timeseries to retrieve data for.
  • start (Union[str, int, datetime]) – Get datapoints after this time. Format is N[timeunit]-ago where timeunit is w,d,h,m,s. E.g. ‘2d-ago’ will get everything that is up to 2 days old. Can also send time in ms since epoch or a datetime object which will be converted to ms since epoch UTC.
  • end (Union[str, int, datetime]) – Get datapoints up to this time. Same format as for start.
  • aggregates (list) – The list of aggregate functions you wish to apply to the data. Valid aggregate functions are: ‘average/avg, max, min, count, sum, interpolation/int, stepinterpolation/step’.
  • granularity (str) – The granularity of the aggregate values. Valid entries are : ‘day/d, hour/h, minute/m, second/s’, or a multiple of these indicated by a number as a prefix e.g. ‘12hour’.
Keyword Arguments:
 
  • include_outside_points (bool) – No description
  • processes (int) – Number of download processes to run in parallell. Defaults to number returned by cpu_count().
  • api_key (str) – Your api-key.
  • project (str) – Project name.
  • limit (str) – Max number of datapoints to return. If limit is specified, this method will not automate paging and will return a maximum of 100,000 dps.
Returns:

A data object containing the requested data with several getter methods with different output formats.

Return type:

v05.dto.DatapointsResponse

Sequences

Sequences Module

This module mirrors the Sequences API.

https://doc.cognitedata.com/api/0.6/#tag/Sequences

cognite.v06.sequences.delete_sequence_by_id(id: int, **kwargs)

Deletes the sequence with the given id.

Parameters:

id (int) – ID of the sequence to delete

Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.

Returns:

cognite.v06.sequences.get_data_from_sequence(id: int, inclusive_from: int = None, inclusive_to: int = None, limit: int = 100, column_ids: List[int] = None, **kwargs)

Gets data from the given sequence.

Parameters:
  • id (int) – id of the sequence.
  • inclusive_from (int) – Row number to get from (inclusive). If set to None, you’ll get data from the first row that exists.
  • inclusive_to (int) – Row number to get to (inclusive). If set to None, you’ll get data to the last row that exists (depending on the limit).
  • limit (int) – How many rows to return.
  • column_ids (List[int]) – ids of the columns to get data for.
Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

A data object containing the requested sequence.

Return type:

v06.dto.Sequence

cognite.v06.sequences.get_sequence_by_external_id(external_id: str, **kwargs)

Returns a Sequence object containing the requested sequence.

Parameters:

external_id (int) – External ID of the sequence to look up

Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

A data object containing the requested sequence.

Return type:

v06.dto.Sequence

cognite.v06.sequences.get_sequence_by_id(id: int, **kwargs)

Returns a Sequence object containing the requested sequence.

Parameters:

id (int) – ID of the sequence to look up

Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

A data object containing the requested sequence.

Return type:

v06.dto.Sequence

cognite.v06.sequences.post_data_to_sequence(id: int, rows: List[cognite.v06.dto.Row], **kwargs)

Posts data to a sequence.

Parameters:
  • id (int) – ID of the sequence.
  • rows (list) – List of rows with the data.
Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.

Returns:

cognite.v06.sequences.post_sequences(sequences: List[cognite.v06.dto.Sequence], **kwargs)

Create a new time series.

Parameters:

sequences (list[v06.dto.Sequence]) – List of sequence data transfer objects to create.

Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

The created sequence

DTO

Data Objects

This module contains data objects used to represent the data returned from the API.

class cognite.v06.dto.Column(id: int = None, name: str = None, external_id: str = None, value_type: str = None, metadata: dict = None)

Bases: object

Data transfer object for a column.

Parameters:
  • id (int) – ID of the column.
  • name (str) – Name of the column.
  • external_id (str) – External ID of the column.
  • value_type (str) – Data type of the column.
  • metadata (dict) – Custom, application specific metadata. String key -> String Value.
static from_JSON(the_column: dict)
class cognite.v06.dto.Row(row_number: int, values: List[cognite.v06.dto.RowValue])

Bases: object

Data transfer object for a row of data in a sequence.

Parameters:
  • row_number (int) – The row number for this row.
  • values (list) – The values in this row.
static from_JSON(the_row: dict)
get_row_as_csv()
class cognite.v06.dto.RowValue(column_id: int, value: str)

Bases: object

Data transfer object for the value in a row in a sequence.

Parameters:
  • column_id (int) – The ID of the column that this value is for.
  • value (str) – The actual value.
static from_JSON(the_row_value: dict)
class cognite.v06.dto.Sequence(id: int = None, name: str = None, external_id: str = None, asset_id: int = None, columns: List[cognite.v06.dto.Column] = None, description: str = None, metadata: dict = None)

Bases: object

Data transfer object for a sequence.

Parameters:
  • id (int) – ID of the sequence.
  • name (str) – Name of the sequence.
  • external_id (str) – External ID of the sequence.
  • asset_id (int) – ID of the asset the sequence is connected to, if any.
  • columns (List[Column]) – List of columns in the sequence.
  • description (str) – Description of the sequence.
  • metadata (dict) – Custom, application specific metadata. String key -> String Value.
static from_JSON(the_sequence: dict)
class cognite.v06.dto.SequenceDataRequest(inclusive_from: int, inclusive_to: int, limit: int = 100, column_ids: List[int] = None)

Bases: object

Data transfer object for requesting sequence data.

Parameters:
  • inclusive_from (int) – Row number to get from (inclusive).
  • inclusive_to (int) – Row number to get to (inclusive).
  • limit (int) – How many rows to return.
  • column_ids (List[int]) – ids of the columns to get data for.
class cognite.v06.dto.SequenceDataResponse(rows: List[cognite.v06.dto.Row])

Bases: object

Data transfer object for the data in a sequence, used when receiving data.

Parameters:rows (list) – List of rows with the data.
static from_JSON(the_data: dict)
to_json()

Returns data as a json object

to_pandas()

Returns data as a pandas dataframe

API v0.5

Assets

Assets Module.

This module mirrors the Assets API.

https://doc.cognitedata.com/0.5/#Cognite-API-Assets

cognite.v05.assets.delete_assets(asset_ids: List[int], **kwargs)

Delete a list of assets.

Parameters:

asset_ids (list[int]) – List of IDs of assets to delete.

Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

An empty response.

cognite.v05.assets.get_asset(asset_id, **kwargs)

Returns the asset with the provided assetId.

Parameters:

asset_id (int) – The asset id of the top asset to get.

Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

A data object containing the requested assets with several getter methods with different output formats.

Return type:

v05.dto.AssetResponse

cognite.v05.assets.get_asset_subtree(asset_id, depth=None, **kwargs)

Returns asset subtree of asset with provided assetId.

Parameters:
  • asset_id (int) – The asset id of the top asset to get.
  • depth (int) – Get subassets this many levels below the top asset.
Keyword Arguments:
 
  • limit (int) – The maximum nuber of assets to be returned.
  • cursor (str) – Cursor to use for paging through results.
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

A data object containing the requested assets with several getter methods with different output formats.

Return type:

v05.dto.AssetListResponse

cognite.v05.assets.get_assets(name=None, path=None, description=None, metadata=None, depth=None, fuzziness=None, **kwargs)

Returns assets matching provided description.

Parameters:
  • name (str) – The name of the asset(s) to get.
  • path (str) – The path of the subtree to search in.
  • description (str) – Search query.
  • metadata (dict) – The metadata values used to filter the results.
  • depth (int) – Get sub assets up oto this many levels below the specified path.
  • fuzziness (int) – The degree of fuzziness in the name matching.
Keyword Arguments:
 
  • autopaging (bool) – Whether or not to automatically page through results. If set to true, limit will be disregarded. Defaults to False.
  • limit (int) – The maximum number of assets to be returned.
  • cursor (str) – Cursor to use for paging through results.
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

A data object containing the requested assets with several getter methods with different output formats.

Return type:

v05.dto.AssetListResponse

cognite.v05.assets.post_assets(assets: List[cognite.v05.dto.Asset], **kwargs)

Insert a list of assets.

Parameters:

assets (list[v05.dto.Asset]) – List of asset data transfer objects.

Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

A data object containing the posted assets with several getter methods with different output formats.

Return type:

v05.dto.AssetListResponse

cognite.v05.assets.search_for_assets(name=None, description=None, query=None, metadata=None, asset_subtrees=None, min_created_time=None, max_created_time=None, min_last_updated_time=None, max_last_updated_time=None, **kwargs)

Search for assets.

Parameters:
  • name – Prefix and fuzzy search on name.
  • str (description) – Prefix and fuzzy search on description.
  • query (str) – Search on name and description using wildcard search on each of the words (separated by spaces). Retrieves results where at least one word must match. Example: ‘some other’
  • metadata (dict) – Filter out assets that do not match these metadata fields and values (case-sensitive). Format is {“key1”:”value1”,”key2”:”value2”}.
  • asset_subtrees (List[int]) – Filter out assets that are not linked to assets in the subtree rooted at these assets. Format is [12,345,6,7890].
  • min_created_time (str) – Filter out assets with createdTime before this. Format is milliseconds since epoch.
  • max_created_time (str) – Filter out assets with createdTime after this. Format is milliseconds since epoch.
  • min_last_updated_time (str) – Filter out assets with lastUpdatedtime before this. Format is milliseconds since epoch.
  • max_last_updated_time (str) – Filter out assets with lastUpdatedtime after this. Format is milliseconds since epoch.
Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
  • sort (str) – Field to be sorted.
  • dir (str) – Sort direction (desc or asc)
  • limit (int) – Return up to this many results. Max is 1000, default is 25.
  • offset (int) – Offset from the first result. Sum of limit and offset must not exceed 1000. Default is 0.
  • boost_name (str) – Whether or not boosting name field. This option is experimental and can be changed.
Returns:

v05.dto.EventListResponse.

Data Transfer Objects

Data Objects

This module contains data objects used to represent the data returned from the API. These objects have at least the following output formats:

  • to_pandas(): Returns pandas dataframe
  • to_ndarray(): Numpy array
  • to_json(): Json format
class cognite.v05.dto.Asset(name, parent_id=None, description=None, metadata=None, ref_id=None, parent_name=None, parent_ref_id=None)

Bases: object

Data transfer object for assets.

Parameters:
  • name (str) – Name of asset. Often referred to as tag.
  • parent_id (int) – ID of parent asset, if any.
  • description (str) – Description of asset.
  • metadata (dict) – Custom , application specific metadata. String key -> String Value.
  • ref_id (str) – Reference ID used only in post request to disambiguate references to duplicate names.
  • parent_name (str) – Name of parent, this parent must exist in the same POST request.
  • parent_ref_id (list(int)) – Reference ID of parent, to disambiguate if multiple nodes have the same name.
class cognite.v05.dto.AssetListResponse(internal_representation)

Bases: cognite.v05.dto.CogniteDataObject

Assets Response Object

to_json()

Returns data as a json object

to_pandas()

Returns data as a pandas dataframe

class cognite.v05.dto.AssetResponse(internal_representation)

Bases: cognite.v05.dto.CogniteDataObject

to_json()

Returns data as a json object

to_pandas()

Returns data as a pandas dataframe

class cognite.v05.dto.CogniteDataObject(internal_representation)

Bases: object

Abstract Cognite Data Object

This abstract class provides a skeleton for all data objects in this module. All data objects should inherit this class.

next_cursor()

Returns next cursor to use for paging through results

previous_cursor()

Returns previous cursor

to_json()

Returns data as a json object

to_ndarray()

Returns data as a numpy array

to_pandas()

Returns data as a pandas dataframe

class cognite.v05.dto.Datapoint(timestamp, value)

Bases: object

Data transfer object for datapoints.

Parameters:
  • timestamp (int, datetime) – The data timestamp in milliseconds since the epoch (Jan 1, 1970) or as a datetime object.
  • value (string) – The data value, Can be string or numeric depending on the metric.
class cognite.v05.dto.DatapointDepth(depth, value)

Bases: object

Data transfer object for Depth datapoints.

Parameters:
  • depth (double) – The depth (in m) of the datapoint
  • value (string) – The data value, Can be string or numeric depending on the metric.
class cognite.v05.dto.DatapointsQuery(name, aggregates=None, granularity=None, start=None, end=None, limit=None)

Bases: object

Data Query Object for Datapoints.

Parameters:
  • name (str) – Unique name of the time series.
  • aggregates (list) – The aggregate functions to be returned. Use default if null. An empty string must be sent to get raw data if the default is a set of aggregate functions.
  • granularity (str) – The granularity size and granularity of the aggregates.
  • start (str, int, datetime) – Get datapoints after this time. Format is N[timeunit]-ago where timeunit is w,d,h,m,s. Example: ‘2d-ago’ will get everything that is up to 2 days old. Can also send time in ms since epoch or as a datetime object.
  • end (str, int, datetime) – Get datapoints up to this time. The format is the same as for start.
class cognite.v05.dto.DatapointsResponse(internal_representation)

Bases: cognite.v05.dto.CogniteDataObject

Datapoints Response Object.

to_json()

Returns data as a json object

to_pandas()

Returns data as a pandas dataframe

class cognite.v05.dto.DatapointsResponseIterator(datapoints_objects)

Bases: object

Iterator for Datapoints Response Objects.

class cognite.v05.dto.Event(start_time=None, end_time=None, description=None, type=None, sub_type=None, metadata=None, asset_ids=None)

Bases: object

Data transfer object for events.

Parameters:
  • start_time (int) – Start time of the event in ms since epoch.
  • end_time (int) – End time of the event in ms since epoch.
  • description (str) – Textual description of the event.
  • type (str) – Type of the event, e.g. ‘failure’.
  • sub_type (str) – Subtype of the event, e.g. ‘electrical’.
  • metadata (dict) – Customizable extra data about the event.
  • asset_ids (list[int]) – List of Asset IDs of related equipments that this event relates to.
class cognite.v05.dto.EventListResponse(internal_representation)

Bases: cognite.v05.dto.CogniteDataObject

Event List Response Object.

to_json()

Returns data as a json object

to_pandas()

Returns data as a pandas dataframe

class cognite.v05.dto.EventResponse(internal_representation)

Bases: cognite.v05.dto.CogniteDataObject

Event Response Object.

to_json()

Returns data as a json object

to_pandas()

Returns data as a pandas dataframe

class cognite.v05.dto.FileInfoResponse(internal_representation)

Bases: cognite.v05.dto.CogniteDataObject

File Info Response Object.

Parameters:
  • id (int) – ID given by the API to the file.
  • file_name (str) – File name. Max length is 256.
  • directory (str) – Directory containing the file. Max length is 512.
  • source (dict) – Source that this file comes from. Max length is 256.
  • file_type (str) – File type. E.g. pdf, css, spreadsheet, .. Max length is 64.
  • metadata (dict) – Customized data about the file.
  • asset_ids (list[str]) – Names of assets related to this file.
  • uploaded (bool) – Whether or not the file is uploaded.
  • uploaded_at (int) – Epoc thime (ms) when the file was uploaded succesfully.
to_json()

Returns data as a json object

to_pandas()

Returns data as a pandas dataframe

class cognite.v05.dto.FileListResponse(internal_representation)

Bases: cognite.v05.dto.CogniteDataObject

File List Response Object

to_json()

Returns data as a json object

to_pandas()

Returns data as a pandas dataframe

class cognite.v05.dto.LatestDatapointResponse(internal_representation)

Bases: cognite.v05.dto.CogniteDataObject

Latest Datapoint Response Object.

to_json()

Returns data as a json object

to_ndarray()

Returns data as a numpy array

to_pandas()

Returns data as a pandas dataframe

class cognite.v05.dto.RawResponse(internal_representation)

Bases: cognite.v05.dto.CogniteDataObject

Raw Response Object.

to_json()

Returns data as a json object

to_pandas()

Returns data as a pandas dataframe

class cognite.v05.dto.RawRow(key, columns)

Bases: object

DTO for a row in a raw database.

The Raw API is a simple key/value-store. Each row in a table in a raw database consists of a unique row key and a set of columns.

Parameters:
  • key (str) – Unique key for the row.
  • columns (int) – A key/value-map consisting of the values in the row.
repr_json()
class cognite.v05.dto.TagMatchingResponse(internal_representation)

Bases: cognite.v05.dto.CogniteDataObject

Tag Matching Response Object.

In addition to the standard output formats this data object also has a to_list() method which returns a list of names of the tag matches.

to_json()

Returns data as a json object

to_list(first_matches_only=True)

Returns a list representation of the matches.

Parameters:first_matches_only (bool) – Boolean determining whether or not to return only the top match for each tag.
Returns:list of matched tags.
Return type:list
to_pandas()

Returns data as a pandas dataframe

class cognite.v05.dto.TimeSeries(name, is_string=False, metadata=None, unit=None, asset_id=None, description=None, security_categories=None, is_step=None)

Bases: object

Data Transfer Object for a time series.

Parameters:
  • name (str) – Unique name of time series.
  • is_string (bool) – Whether the time series is string valued or not.
  • metadata (dict) – Metadata.
  • unit (str) – Physical unit of the time series.
  • asset_id (int) – Asset that this time series belongs to.
  • description (str) – Description of the time series.
  • security_categories (list(int)) – Security categories required in order to access this time series.
  • is_step (bool) – Whether or not the time series is a step series.
class cognite.v05.dto.TimeSeriesResponse(internal_representation)

Bases: cognite.v05.dto.CogniteDataObject

Time series Response Object

to_json()

Returns data as a json object

to_pandas()

Returns data as a pandas dataframe

class cognite.v05.dto.TimeseriesWithDatapoints(name, datapoints)

Bases: object

Data transfer object for a timeseries with datapoints.

Parameters:
  • name (str) – Unique ID of time series.
  • datapoints (List[v05.dto.Datapoint]) – List of datapoints in the timeseries.

Events

Events Module

This module mirrors the Events API. It allows you to get, post, update, and delete events.

https://doc.cognitedata.com/0.5/#Cognite-API-Events

cognite.v05.events.delete_events(event_ids, **kwargs)

Deletes a list of events.

Parameters:

event_ids (List[int]) – List of ids of events to delete.

Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

An empty response.

cognite.v05.events.get_event(event_id, **kwargs)

Returns a EventResponse containing an event matching the id.

Parameters:

event_id (int) – The event id.

Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

A data object containing the requested event.

Return type:

v05.dto.EventResponse

cognite.v05.events.get_events(type=None, sub_type=None, asset_id=None, **kwargs)

Returns an EventListReponse object containing events matching the query.

Parameters:
  • type (str) – Type (class) of event, e.g. ‘failure’.
  • sub_type (str) – Sub-type of event, e.g. ‘electrical’.
  • asset_id (str) – Return events associated with this assetId.
Keyword Arguments:
 
  • sort (str) – Sort descending or ascending. Default ‘ASC’.
  • cursor (str) – Cursor to use for paging through results.
  • limit (int) – Return up to this many results. Maximum is 10000. Default is 25.
  • has_description (bool) – Return only events that have a textual description. Default null. False gives only those without description.
  • min_start_time (string) – Only return events from after this time.
  • max_start_time (string) – Only return events form before this time.
  • api_key (str) – Your api-key.
  • project (str) – Project name.
  • autopaging (bool) – Whether or not to automatically page through results. If set to true, limit will be disregarded. Defaults to False.
Returns:

A data object containing the requested event.

Return type:

v05.dto.EventListResponse

cognite.v05.events.post_events(events, **kwargs)

Adds a list of events and returns an EventListResponse object containing created events.

Parameters:

events (List[v05.dto.Event]) – List of events to create.

Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

v05.dto.EventListResponse

cognite.v05.events.search_for_events(description=None, type=None, subtype=None, min_start_time=None, max_start_time=None, min_end_time=None, max_end_time=None, min_created_time=None, max_created_time=None, min_last_updated_time=None, max_last_updated_time=None, metadata=None, asset_ids=None, asset_subtrees=None, **kwargs)

Search for events.

Parameters:

str (description) – Prefix and fuzzy search on description.

Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
  • type (str) – Filter on type (case-sensitive).
  • subtype (str) – Filter on subtype (case-sensitive).
  • min_start_time (str) – Filter out events with startTime before this. Format is milliseconds since epoch.
  • max_start_time (str) – Filter out events with startTime after this. Format is milliseconds since epoch.
  • min_end_time (str) – Filter out events with endTime before this. Format is milliseconds since epoch.
  • max_end_time (str) – Filter out events with endTime after this. Format is milliseconds since epoch.
  • min_created_time (str) – Filter out events with createdTime before this. Format is milliseconds since epoch.
  • max_created_time (str) – Filter out events with createdTime after this. Format is milliseconds since epoch.
  • min_last_updated_time (str) – Filter out events with lastUpdatedtime before this. Format is milliseconds since epoch.
  • max_last_updated_time (str) – Filter out events with lastUpdatedtime after this. Format is milliseconds since epoch.
  • metadata (dict) – Filter out events that do not match these metadata fields and values (case-sensitive). Format is {“key1”:”value1”,”key2”:”value2”}.
  • asset_ids (List[int]) – Filter out events that are not linked to any of these assets. Format is [12,345,6,7890].
  • asset_subtrees (List[int]) – Filter out events that are not linked to assets in the subtree rooted at these assets. Format is [12,345,6,7890].
  • sort (str) – Field to be sorted.
  • dir (str) – Sort direction (desc or asc)
  • limit (int) – Return up to this many results. Max is 1000, default is 25.
  • offset (int) – Offset from the first result. Sum of limit and offset must not exceed 1000. Default is 0.
Returns:

v05.dto.EventListResponse.

Files

Files Module

This module mirrors the Files API. It allows you to manage files in GCP.

https://doc.cognitedata.com/0.5/#Cognite-API-Files

cognite.v05.files.delete_files(file_ids, **kwargs)

Delete

Parameters:

file_ids (list[int]) – List of IDs of files to delete.

Keyword Arguments:
 
  • api_key (str) – Your api key.
  • project (str) – Your project.
Returns:

List of files deleted and files that failed to delete.

cognite.v05.files.download_file(id, get_contents=False, **kwargs)

Get list of files matching query.

Parameters:
  • id (int) – Path to file to upload, if omitted a upload link will be returned.
  • get_contents (bool, optional) – Boolean to determince whether or not to return file contents as string. Default is False and download url is returned.
Keyword Arguments:
 
  • api_key (str, optional) – Your api-key.
  • project (str, optional) – Project name.
Returns:

Download link if get_contents is False else file contents.

Return type:

bytes

cognite.v05.files.get_file_info(id, **kwargs)

Returns information about a file.

Parameters:

id (int) – Id of the file.

Keyword Arguments:
 
  • api_key (str, optional) – Your api-key.
  • project (str, optional) – Project name.
Returns:

A data object containing the requested file information.

Return type:

v05.dto.FileInfoResponse

cognite.v05.files.list_files(name=None, directory=None, file_type=None, source=None, **kwargs)

Get list of files matching query.

Parameters:
  • name (str, optional) – List all files with this name.
  • directory (str, optional) – Directory to list files from.
  • source (str, optional) – List files coming from this source.
  • file_type (str, optional) – Type of files to list.
Keyword Arguments:
 
  • api_key (str, optional) – Your api-key.
  • project (str, optional) – Project name.
  • asset_id (list) – Returns all files associated with this asset id.
  • sort (str) – Sort descending or ascending. ‘ASC’ or ‘DESC’.
  • limit (int) – Number of results to return.
  • is_uploaded (bool) – List only uploaded files if true. If false, list only other files. If not set, list all files without considering whether they are uploaded or not.
  • autopaging (bool) – Whether or not to automatically page through results. If set to true, limit will be disregarded. Defaults to False.
  • cursor (str) – Cursor to use for paging through results.
Returns:

A data object containing the requested files information.

Return type:

v05.dto.FileListResponse

cognite.v05.files.upload_file(file_name, file_path=None, directory=None, source=None, file_type=None, content_type=None, **kwargs)

Upload metadata about a file and get an upload link.

The link will expire after 30 seconds if not resumable. A resumable upload link is default. Such a link is one-time use and expires after one week. For more information, check this link: https://cloud.google.com/storage/docs/json_api/v1/how-tos/resumable-upload. Use PUT request to upload file with the link returned.

If file_path is specified, the file will be uploaded directly by the SDK.

Parameters:
  • file_name (str) – File name. Max length is 256.
  • file_path (str, optional) – Path of file to upload, if omitted a upload link will be returned.
  • content_type (str, optional) – MIME type of your file. Required if file_path is specified.
  • directory (str, optional) – Directory containing the file. Max length is 512.
  • source (str, optional) – Source that this file comes from. Max length is 256.
  • file_type (str, optional) – File type. E.g. pdf, css, spreadsheet, .. Max length is 64.
Keyword Arguments:
 
  • api_key (str, optional) – Your api-key.
  • project (str, optional) – Project name.
  • metadata (dict) – Customized data about the file.
  • asset_ids (list) – IDs of assets related to this file.
  • resumable (bool) – Whether to generate a resumable URL or not. Default is true.
  • overwrite (bool) – Whether to overwrite existing data if duplicate or not. Default is false.
Returns:

A dictionary containing the field fileId and optionally also uploadURL if file_path is omitted.

Return type:

dict

Raw

Raw Module

This module mirrors the Raw API. It allows the user to handle raw data.

https://doc.cognitedata.com/0.5/#Cognite-API-Cloud-Raw

cognite.v05.raw.create_databases(database_names: list, api_key=None, project=None)

Creates databases in the Raw API and returns the created databases.

Parameters:
  • database_names (list) – A list of databases to create.
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

A data object containing the requested data with several getter methods with different output formats.

Return type:

v05.dto.RawResponse

cognite.v05.raw.create_rows(database_name: str = None, table_name: str = None, rows: List[cognite.v05.dto.RawRow] = None, api_key=None, project=None, ensure_parent=False, use_gzip=False)

Creates tables in the given Raw API database.

Parameters:
  • database_name (str) – The database to create rows in.
  • table_name (str) – The table names to create rows in.
  • rows (list[v05.dto.RawRow]) – The rows to create.
  • api_key (str) – Your api-key.
  • project (str) – Project name.
  • ensure_parent (bool) – Create database/table if it doesn’t exist already
  • use_gzip (bool) – Compress content using gzip
Returns:

An empty response

cognite.v05.raw.create_tables(database_name: str = None, table_names: list = None, api_key=None, project=None)

Creates tables in the given Raw API database.

Parameters:
  • database_name (str) – The database to create tables in.
  • table_names (list) – The table names to create.
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

A data object containing the requested data with several getter methods with different output formats.

Return type:

v05.dto.RawResponse

cognite.v05.raw.delete_databases(database_names: list, recursive: bool = False, api_key=None, project=None)

Deletes databases in the Raw API.

Parameters:
  • database_names (list) – A list of databases to delete.
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

An empty response.

cognite.v05.raw.delete_rows(database_name: str = None, table_name: str = None, rows: List[cognite.v05.dto.RawRow] = None, api_key=None, project=None)

Deletes rows in the Raw API.

Parameters:
  • database_name (str) – The database to create tables in.
  • table_name (str) – The table name where the rows are at.
  • rows (list) – The rows to delete.
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

An empty response.

cognite.v05.raw.delete_tables(database_name: str = None, table_names: list = None, api_key=None, project=None)

Deletes databases in the Raw API.

Parameters:
  • database_name (str) – The database to create tables in.
  • table_names (list) – The table names to create.
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

An empty response.

cognite.v05.raw.get_databases(limit: int = None, cursor: str = None, api_key=None, project=None)

Returns a RawObject containing a list of raw databases.

Parameters:
  • limit (int) – A limit on the amount of results to return.
  • cursor (str) – A cursor can be provided to navigate through pages of results.
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

A data object containing the requested data with several getter methods with different output formats.

Return type:

v05.dto.RawResponse

cognite.v05.raw.get_row(database_name: str = None, table_name: str = None, row_key: str = None, api_key=None, project=None)

Returns a RawObject containing a list of rows.

Parameters:
  • database_name (str) – The database name to retrieve rows from.
  • table_name (str) – The table name to retrieve rows from.
  • row_key (str) – The key of the row to fetch.
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

A data object containing the requested data with several getter methods with different output formats.

Return type:

v05.dto.RawResponse

cognite.v05.raw.get_rows(database_name: str = None, table_name: str = None, limit: int = None, cursor: str = None, api_key=None, project=None)

Returns a RawObject containing a list of rows.

Parameters:
  • database_name (str) – The database name to retrieve rows from.
  • table_name (str) – The table name to retrieve rows from.
  • limit (int) – A limit on the amount of results to return.
  • cursor (str) – A cursor can be provided to navigate through pages of results.
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

A data object containing the requested data with several getter methods with different output formats.

Return type:

v05.dto.RawResponse

cognite.v05.raw.get_tables(database_name: str = None, limit: int = None, cursor: str = None, api_key=None, project=None)

Returns a RawObject containing a list of tables in a raw database.

Parameters:
  • database_name (str) – The database name to retrieve tables from.
  • limit (int) – A limit on the amount of results to return.
  • cursor (str) – A cursor can be provided to navigate through pages of results.
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

A data object containing the requested data with several getter methods with different output formats.

Return type:

v05.dto.RawResponse

Tagmatching

Tag Matching Module

This module mirrors the Tag Matching API. It allows the user to search for tag id matches.

https://doc.cognitedata.com/0.5/#Cognite-API-Tag-Matching

cognite.v05.tagmatching.tag_matching(tag_ids, fuzzy_threshold=0, platform=None, **kwargs)

Returns a TagMatchingObject containing a list of matched tags for the given query.

This method takes an arbitrary string as argument and performs fuzzy matching with a user defined threshold toward tag ids in the system.

Parameters:
  • tag_ids (list) – The tag_ids to retrieve matches for.
  • fuzzy_threshold (int) – The threshold to use when searching for matches. A fuzzy threshold of 0 means you only want to accept perfect matches. Must be >= 0.
  • platform (str) – The platform to search on.
Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

A data object containing the requested data with several getter methods with different output formats.

Return type:

v05.dto.TagMatchingResponse

Timeseries

Timeseries Module

This module mirrors the Timeseries API. It allows you to fetch data from the api and output it in various formats.

https://doc.cognitedata.com/0.5/#Cognite-API-Time-series

cognite.v05.timeseries.delete_time_series(name, **kwargs)

Delete a timeseries.

Parameters:

name (str) – Name of timeseries to delete.

Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

An empty response.

cognite.v05.timeseries.get_datapoints(name, start, end=None, aggregates=None, granularity=None, **kwargs)

Returns a DatapointsObject containing a list of datapoints for the given query.

This method will automate paging for the user and return all data for the given time period.

Parameters:
  • name (str) – The name of the timeseries to retrieve data for.
  • start (Union[str, int, datetime]) – Get datapoints after this time. Format is N[timeunit]-ago where timeunit is w,d,h,m,s. E.g. ‘2d-ago’ will get everything that is up to 2 days old. Can also send time in ms since epoch or a datetime object which will be converted to ms since epoch UTC.
  • end (Union[str, int, datetime]) – Get datapoints up to this time. Same format as for start.
  • aggregates (list) – The list of aggregate functions you wish to apply to the data. Valid aggregate functions are: ‘average/avg, max, min, count, sum, interpolation/int, stepinterpolation/step’.
  • granularity (str) – The granularity of the aggregate values. Valid entries are : ‘day/d, hour/h, minute/m, second/s’, or a multiple of these indicated by a number as a prefix e.g. ‘12hour’.
Keyword Arguments:
 
  • include_outside_points (bool) – No description
  • protobuf (bool) – Download the data using the binary protobuf format. Only applicable when getting raw data. Defaults to True.
  • processes (int) – Number of download processes to run in parallell. Defaults to number returned by cpu_count().
  • api_key (str) – Your api-key.
  • project (str) – Project name.
  • limit (str) – Max number of datapoints to return. If limit is specified, this method will not automate paging and will return a maximum of 100,000 dps.
Returns:

A data object containing the requested data with several getter methods with different output formats.

Return type:

v05.dto.DatapointsResponse

cognite.v05.timeseries.get_datapoints_frame(time_series, aggregates, granularity, start, end=None, **kwargs)

Returns a pandas dataframe of datapoints for the given timeseries all on the same timestamps.

This method will automate paging for the user and return all data for the given time period.

Parameters:
  • time_series (list) – The list of timeseries names to retrieve data for. Each timeseries can be either a string containing the timeseries or a dictionary containing the names of thetimeseries and a list of specific aggregate functions.
  • aggregates (list) – The list of aggregate functions you wish to apply to the data for which you have not specified an aggregate function. Valid aggregate functions are: ‘average/avg, max, min, count, sum, interpolation/int, stepinterpolation/step’.
  • granularity (str) – The granularity of the aggregate values. Valid entries are : ‘day/d, hour/h, minute/m, second/s’, or a multiple of these indicated by a number as a prefix e.g. ‘12hour’.
  • start (Union[str, int, datetime]) – Get datapoints after this time. Format is N[timeunit]-ago where timeunit is w,d,h,m,s. E.g. ‘2d-ago’ will get everything that is up to 2 days old. Can also send time in ms since epoch or a datetime object which will be converted to ms since epoch UTC.
  • end (Union[str, int, datetime]) – Get datapoints up to this time. Same format as for start.
Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
  • cookies (dict) – Cookies.
  • limit (str) – Max number of rows to return. If limit is specified, this method will not automate paging and will return a maximum of 100,000 rows.
  • processes (int) – Number of download processes to run in parallell. Defaults to number returned by cpu_count().
Returns:

A pandas dataframe containing the datapoints for the given timeseries. The datapoints for all the timeseries will all be on the same timestamps.

Return type:

pandas.DataFrame

Examples

The timeseries parameter can take a list of strings and/or dicts on the following formats:

Using strings:
    ['<timeseries1>', '<timeseries2>']

Using dicts:
    [{'name': '<timeseries1>', 'aggregates': ['<aggfunc1>', '<aggfunc2>']},
    {'name': '<timeseries2>', 'aggregates': []}]

Using both:
    ['<timeseries1>', {'name': '<timeseries2>', 'aggregates': ['<aggfunc1>', '<aggfunc2>']}]
cognite.v05.timeseries.get_latest(name, before=None, **kwargs)

Returns a LatestDatapointObject containing the latest datapoint for the given timeseries.

Parameters:

name (str) – The name of the timeseries to retrieve data for.

Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

A data object containing the requested data with several getter methods with different output formats.

Return type:

v05.dto.LatestDatapointsResponse

cognite.v05.timeseries.get_multi_time_series_datapoints(datapoints_queries, start, end=None, aggregates=None, granularity=None, **kwargs)

Returns a list of DatapointsObjects each of which contains a list of datapoints for the given timeseries.

This method will automate paging for the user and return all data for the given time period(s).

Parameters:
  • datapoints_queries (list[v05.dto.DatapointsQuery]) – The list of DatapointsQuery objects specifying which timeseries to retrieve data for.
  • start (Union[str, int, datetime]) – Get datapoints after this time. Format is N[timeunit]-ago where timeunit is w,d,h,m,s. E.g. ‘2d-ago’ will get everything that is up to 2 days old. Can also send time in ms since epoch or a datetime object which will be converted to ms since epoch UTC.
  • end (Union[str, int, datetime]) – Get datapoints up to this time. Same format as for start.
  • aggregates (list, optional) – The list of aggregate functions you wish to apply to the data. Valid aggregate functions are: ‘average/avg, max, min, count, sum, interpolation/int, stepinterpolation/step’.
  • granularity (str) – The granularity of the aggregate values. Valid entries are : ‘day/d, hour/h, minute/m, second/s’, or a multiple of these indicated by a number as a prefix e.g. ‘12hour’.
Keyword Arguments:
 
  • include_outside_points (bool) – No description.
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

A list of data objects containing the requested data with several getter methods with different output formats.

Return type:

list(v05.dto.DatapointsResponse)

cognite.v05.timeseries.get_timeseries(prefix=None, description=None, include_metadata=False, asset_id=None, path=None, **kwargs)

Returns a TimeseriesObject containing the requested timeseries.

Parameters:
  • prefix (str) – List timeseries with this prefix in the name.
  • description (str) – Filter timeseries taht contains this string in its description.
  • include_metadata (bool) – Decide if the metadata field should be returned or not. Defaults to False.
  • asset_id (int) – Get timeseries related to this asset.
  • path (str) – Get timeseries under this asset path branch.
Keyword Arguments:
 
  • limit (int) – Number of results to return.
  • api_key (str) – Your api-key.
  • project (str) – Project name.
  • autopaging (bool) – Whether or not to automatically page through results. If set to true, limit will be disregarded. Defaults to False.
Returns:

A data object containing the requested timeseries with several getter methods with different output formats.

Return type:

v05.dto.TimeSeriesResponse

cognite.v05.timeseries.live_data_generator(name, update_frequency=1, **kwargs)

Generator function which continously polls latest datapoint of a timeseries and yields new datapoints.

Parameters:
  • name (str) – Name of timeseries to get latest datapoints for.
  • update_frequency (float) – Frequency to pull for data in seconds.
Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Yields:

dict – Dictionary containing timestamp and value of latest datapoint.

cognite.v05.timeseries.post_datapoints(name, datapoints: List[cognite.v05.dto.Datapoint], **kwargs)

Insert a list of datapoints.

Parameters:
  • name (str) – Name of timeseries to insert to.
  • datapoints (list[v05.dto.Datapoint) – List of datapoint data transfer objects to insert.
Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

An empty response.

cognite.v05.timeseries.post_datapoints_frame(data, **kwargs)

Write a dataframe

Parameters:

dataframe (DataFrame) – Pandas DataFrame Object containing the timeseries

Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

An empty response.

cognite.v05.timeseries.post_multi_tag_datapoints(timeseries_with_datapoints: List[cognite.v05.dto.TimeseriesWithDatapoints], **kwargs)

Insert data into multiple timeseries.

Parameters:

timeseries_with_datapoints (List[v05.dto.TimeseriesWithDatapoints]) – The timeseries with data to insert.

Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
  • use_gzip (bool) – Whether or not to gzip the request
Returns:

An empty response.

cognite.v05.timeseries.post_time_series(time_series: List[cognite.v05.dto.TimeSeries], **kwargs)

Create a new time series.

Parameters:

time_series (list[v05.dto.TimeSeries]) – List of time series data transfer objects to create.

Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

An empty response.

cognite.v05.timeseries.update_time_series(time_series: List[cognite.v05.dto.TimeSeries], **kwargs)

Update an existing time series.

For each field that can be updated, a null value indicates that nothing should be done.

Parameters:

time_series (list[v05.dto.TimeSeries]) – List of time series data transfer objects to update.

Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

An empty response.

API v0.4

Assets

Assets Module.

This module mirrors the Assets API.

https://doc.cognitedata.com/0.4/#Cognite-API-Assets

cognite.v04.assets.delete_assets(asset_ids: List[int], **kwargs)

Delete a list of assets.

Parameters:

asset_ids (list[v04.dto.Asset]) – List of IDs of assets to delete.

Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

An empty response.

cognite.v04.assets.get_asset_subtree(asset_id='', depth=None, **kwargs)

Returns assets with provided assetId.

Parameters:
  • asset_id (str) – The asset id of the top asset to get.
  • depth (int) – Get subassets this many levels below the top asset.
Keyword Arguments:
 
  • limit (int) – The maximum nuber of assets to be returned.
  • cursor (str) – Cursor to use for paging through results.
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

A data object containing the requested assets with several getter methods with different output formats.

Return type:

v04.dto.AssetResponse

cognite.v04.assets.get_assets(name=None, path=None, description=None, metadata=None, depth=None, fuzziness=None, **kwargs)

Returns assets matching provided description.

Parameters:
  • name (str) – The name of the asset(s) to get.
  • path (str) – The path of the subtree to search in.
  • description (str) – Search query.
  • metadata (str) – The metadata values used to filter the results.
  • depth (int) – Get sub assets up oto this many levels below the specified path.
  • fuzziness (int) – The degree of fuzziness in the name matching.
Keyword Arguments:
 
  • limit (int) – The maximum number of assets to be returned.
  • cursor (str) – Cursor to use for paging through results.
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

A data object containing the requested assets with several getter methods with different output formats.

Return type:

v04.dto.AssetResponse

cognite.v04.assets.post_assets(assets: List[cognite.v04.dto.Asset], **kwargs)

Insert a list of assets.

Parameters:

assets (list[v04.dto.Asset]) – List of asset data transfer objects.

Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

A data object containing the posted assets with several getter methods with different output formats.

Return type:

v04.dto.AssetResponse

Cloud Storage

Cloud Storage Module

This module mirrors the Cloud Storage API. It allows you to manage files in cloud storage.

https://doc.cognitedata.com/0.4/#Cognite-API-Cloud-Storage

cognite.v04.cloud_storage.delete_files(file_ids, **kwargs)

Delete

Parameters:

file_ids (list[int]) – List of IDs of files to delete.

Keyword Arguments:
 
  • api_key (str) – Your api key.
  • project (str) – Your project.
Returns:

List of files deleted and files that failed to delete.

Return type:

list

cognite.v04.cloud_storage.download_file(id, get_contents=False, **kwargs)

Get list of files matching query.

Parameters:
  • id (int) – Path to file to upload, if omitted a upload link will be returned.
  • get_contents (bool, optional) – Boolean to determince whether or not to return file contents as string. Default is False and download url is returned.
Keyword Arguments:
 
  • api_key (str, optional) – Your api-key.
  • project (str, optional) – Project name.
Returns:

Download link if get_contents is False else file contents.

Return type:

str

cognite.v04.cloud_storage.get_file_info(id, **kwargs)

Returns information about a file.

Parameters:

id (int) – Id of the file.

Keyword Arguments:
 
  • api_key (str, optional) – Your api-key.
  • project (str, optional) – Project name.
Returns:

A data object containing the requested file information.

Return type:

v04.dto.FileInfoResponse

cognite.v04.cloud_storage.list_files(name=None, directory=None, file_type=None, source=None, **kwargs)

Get list of files matching query.

Parameters:
  • name (str, optional) – List all files with this name.
  • directory (str, optional) – Directory to list files from.
  • source (str, optional) – List files coming from this source.
  • file_type (str, optional) – Type of files to list.
Keyword Arguments:
 
  • api_key (str, optional) – Your api-key.
  • project (str, optional) – Project name.
  • tag_id (list) – Returns all files associated with this tagId.
  • sort (str) – Sort descending or ascending. ‘ASC’ or ‘DESC’.
  • limit (int) – Number of results to return.
  • autopaging (bool) – Whether or not to automatically page through results. If set to true, limit will be disregarded. Defaults to False.
Returns:

A data object containing the requested files information.

Return type:

v04.dto.FileListResponse

cognite.v04.cloud_storage.upload_file(file_name, file_path=None, directory=None, source=None, file_type=None, content_type=None, **kwargs)

Upload metadata about a file and get an upload link.

The link will expire after 30 seconds if not resumable. A resumable upload link is default. Such a link is one-time use and expires after one week. For more information, check this link: https://cloud.google.com/storage/docs/json_api/v1/how-tos/resumable-upload. Use PUT request to upload file with the link returned.

If file_path is specified, the file will be uploaded directly by the SDK.

Parameters:
  • file_name (str) – File name. Max length is 256.
  • file_path (str, optional) – Path of file to upload, if omitted a upload link will be returned.
  • content_type (str, optional) – MIME type of your file. Required if file_path is specified.
  • directory (str, optional) – Directory containing the file. Max length is 512.
  • source (str, optional) – Source that this file comes from. Max length is 256.
  • file_type (str, optional) – File type. E.g. pdf, css, spreadsheet, .. Max length is 64.
Keyword Arguments:
 
  • api_key (str, optional) – Your api-key.
  • project (str, optional) – Project name.
  • metadata (dict) – Customized data about the file.
  • tag_ids (list) – IDs (tagIds) of equipment related to this file.
  • resumable (bool) – Whether to generate a resumable URL or not. Default is true.
  • overwrite (bool) – Whether to overwrite existing data if duplicate or not. Default is false.
Returns:

A dictionary containing the field fileId and optionally also uploadURL if file_path is omitted.

Return type:

dict

Data Transfer Objects

Data Objects

This module contains data objects used to represent the data returned from the API. These objects have at least the following output formats:

  • to_pandas(): Returns pandas dataframe
  • to_ndarray(): Numpy array
  • to_json(): Json format
class cognite.v04.dto.Asset(name, parent_id=None, description=None, metadata=None, ref_id=None, parent_name=None, parent_ref_id=None)

Bases: object

Data transfer object for assets.

name

str – Name of asset. Often referred to as tag.

parent_id

int – ID of parent asset, if any.

description

str – Description of asset.

metadata

dict – Custom , application specific metadata. String key -> String Value.

ref_id

str – Reference ID used only in post request to disambiguate references to duplicate names.

parent_name

str – Name of parent, this parent must exist in the same POST request.

parent_ref_id

list(int) – Reference ID of parent, to disambiguate if multiple nodes have the same name.

class cognite.v04.dto.AssetResponse(internal_representation)

Bases: cognite.v04.dto.CogniteDataObject

Assets Response Object

to_json()

Returns data as a json object

to_pandas()

Returns data as a pandas dataframe

class cognite.v04.dto.CogniteDataObject(internal_representation)

Bases: object

Abstract Cognite Data Object

This abstract class provides a skeleton for all data objects in this module. All data objects should inherit this class.

next_cursor()

Returns next cursor to use for paging through results

previous_cursor()

Returns previous cursor

to_json()

Returns data as a json object

to_ndarray()

Returns data as a numpy array

to_pandas()

Returns data as a pandas dataframe

class cognite.v04.dto.Datapoint(timestamp, value)

Bases: object

Data transfer object for datapoints.

timestamp

int, datetime – The data timestamp in milliseconds since the epoch (Jan 1, 1970) or as a datetime object.

value

string – The data value, Can be string or numeric depending on the metric.

class cognite.v04.dto.DatapointsQuery(tag_id, aggregates=None, granularity=None, start=None, end=None, limit=None)

Bases: object

Data Query Object for Datapoints.

tag_id

str – Unique ID of time series.

aggregates

list – The aggregate functions to be returned. Use default if null. An empty list must be sent to get raw data if the default is a set of aggregate functions.

granularity

str – The granularity size and granularity of the aggregates.

start

str, int, datetime – Get datapoints after this time. Format is N[timeunit]-ago where timeunit is w,d,h,m,s. Example: ‘2d-ago’ will get everything that is up to 2 days old. Can also send time in ms since epoch or as a datetime object.

end

str, int, datetime – Get datapoints up to this time. The format is the same as for start.

class cognite.v04.dto.DatapointsResponse(internal_representation)

Bases: cognite.v04.dto.CogniteDataObject

Datapoints Response Object.

to_json()

Returns data as a json object

to_pandas()

Returns data as a pandas dataframe

class cognite.v04.dto.DatapointsResponseIterator(datapoints_objects)

Bases: object

Iterator for Datapoints Response Objects.

class cognite.v04.dto.FileInfoResponse(internal_representation)

Bases: cognite.v04.dto.CogniteDataObject

File Info Response Object.

id

int – ID given by the API to the file.

file_name

str – File name. Max length is 256.

directory

str – Directory containing the file. Max length is 512.

source

dict – Source that this file comes from. Max length is 256.

file_type

str – File type. E.g. pdf, css, spreadsheet, .. Max length is 64.

metadata

dict – Customizd data about the file.

tag_ids

list[str] – IDs of equipment related to this file.

uploaded

bool – Whether or not the file is uploaded.

uploaded_at

int – Epoc thime (ms) when the file was uploaded succesfully.

to_json()

Returns data as a json object

to_pandas()

Returns data as a pandas dataframe

class cognite.v04.dto.FileListResponse(internal_representation)

Bases: cognite.v04.dto.CogniteDataObject

to_json()

Returns data as a json object

to_pandas()

Returns data as a pandas dataframe

class cognite.v04.dto.LatestDatapointResponse(internal_representation)

Bases: cognite.v04.dto.CogniteDataObject

Latest Datapoint Response Object.

to_json()

Returns data as a json object

to_ndarray()

Returns data as a numpy array

to_pandas()

Returns data as a pandas dataframe

class cognite.v04.dto.RawResponse(internal_representation)

Bases: cognite.v04.dto.CogniteDataObject

Raw Response Object.

to_json()

Returns data as a json object

to_pandas()

Returns data as a pandas dataframe

class cognite.v04.dto.RawRow(key, columns)

Bases: object

DTO for a row in a raw database.

The Raw API is a simple key/value-store. Each row in a table in a raw database consists of a unique row key and a set of columns.

key

str – Unique key for the row.

columns

int – A key/value-map consisting of the values in the row.

repr_json()
class cognite.v04.dto.TagMatchingResponse(internal_representation)

Bases: cognite.v04.dto.CogniteDataObject

Tag Matching Response Object.

In addition to the standard output formats this data object also has a to_list() method which returns a list of names of the tag matches.

to_json()

Returns data as a json object

to_list(first_matches_only=True)

Returns a list representation of the matches.

Parameters:first_matches_only (bool) – Boolean determining whether or not to return only the top match for each tag.
Returns:list of matched tags.
Return type:list
to_pandas()

Returns data as a pandas dataframe

class cognite.v04.dto.TimeSeries(tag_id, is_string=False, metadata=None, unit=None, asset_id=None, description=None, security_categories=None, step=None)

Bases: object

Data Transfer Object for a timeseries.

Parameters:
  • tag_id (str) – Unique ID of time series.
  • is_string (bool) – Whether the time series is string valued or not.
  • metadata (dict) – Metadata.
  • unit (str) – Physical unit of the time series.
  • asset_id (int) – Asset that this time series belongs to.
  • description (str) – Description of the time series.
  • security_categories (list(int)) – Security categories required in order to access this time series.
  • step (bool) – Whether or not the time series is a step series.
class cognite.v04.dto.TimeSeriesResponse(internal_representation)

Bases: cognite.v04.dto.CogniteDataObject

Time series Response Object

to_json()

Returns data as a json object

to_pandas()

Returns data as a pandas dataframe

class cognite.v04.dto.TimeseriesWithDatapoints(tagId, datapoints)

Bases: object

Data transfer object for a timeseries with datapoints.

tag_id

str – Unique ID of time series.

datapoints

List[v04.dto.Datapoint] – List of datapoints in the timeseries.

Raw

Raw Module

This module mirrors the Raw API. It allows the user to handle raw data.

https://doc.cognitedata.com/0.4/#Cognite-API-Cloud-Raw

cognite.v04.raw.create_databases(database_names: list, api_key=None, project=None)

Creates databases in the Raw API and returns the created databases.

Parameters:
  • database_names (list) – A list of databases to create.
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

A data object containing the requested data with several getter methods with different output formats.

Return type:

v04.dto.RawResponse

cognite.v04.raw.create_rows(database_name: str = None, table_name: str = None, rows: List[cognite.v04.dto.RawRow] = None, api_key=None, project=None, ensure_parent=False, use_gzip=False)

Creates tables in the given Raw API database.

Parameters:
  • database_name (str) – The database to create rows in.
  • table_name (str) – The table names to create rows in.
  • rows (list[v04.dto.RawRow]) – The rows to create.
  • api_key (str) – Your api-key.
  • project (str) – Project name.
  • ensure_parent (bool) – Create database/table if it doesn’t exist already
  • use_gzip (bool) – Compress content using gzip
Returns:

An empty response

cognite.v04.raw.create_tables(database_name: str = None, table_names: list = None, api_key=None, project=None)

Creates tables in the given Raw API database.

Parameters:
  • database_name (str) – The database to create tables in.
  • table_names (list) – The table names to create.
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

A data object containing the requested data with several getter methods with different output formats.

Return type:

v04.dto.RawResponse

cognite.v04.raw.delete_databases(database_names: list, recursive: bool = False, api_key=None, project=None)

Deletes databases in the Raw API.

Parameters:
  • database_names (list) – A list of databases to delete.
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

An empty response.

cognite.v04.raw.delete_rows(database_name: str = None, table_name: str = None, rows: List[cognite.v04.dto.RawRow] = None, api_key=None, project=None)

Deletes rows in the Raw API.

Parameters:
  • database_name (str) – The database to create tables in.
  • table_name (str) – The table name where the rows are at.
  • rows (list) – The rows to delete.
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

An empty response.

cognite.v04.raw.delete_tables(database_name: str = None, table_names: list = None, api_key=None, project=None)

Deletes databases in the Raw API.

Parameters:
  • database_name (str) – The database to create tables in.
  • table_names (list) – The table names to create.
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

An empty response.

cognite.v04.raw.get_databases(limit: int = None, cursor: str = None, api_key=None, project=None)

Returns a RawObject containing a list of raw databases.

Parameters:
  • limit (int) – A limit on the amount of results to return.
  • cursor (str) – A cursor can be provided to navigate through pages of results.
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

A data object containing the requested data with several getter methods with different output formats.

Return type:

v04.dto.RawResponse

cognite.v04.raw.get_row(database_name: str = None, table_name: str = None, row_key: str = None, api_key=None, project=None)

Returns a RawResponse Object containing a list of rows.

Parameters:
  • database_name (str) – The database name to retrieve rows from.
  • table_name (str) – The table name to retrieve rows from.
  • row_key (str) – The key of the row to fetch.
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

A data object containing the requested data with several getter methods with different output formats.

Return type:

v04.dto.RawResponse

cognite.v04.raw.get_rows(database_name: str = None, table_name: str = None, limit: int = None, cursor: str = None, api_key=None, project=None)

Returns a RawResponse Object containing a list of rows.

Parameters:
  • database_name (str) – The database name to retrieve rows from.
  • table_name (str) – The table name to retrieve rows from.
  • limit (int) – A limit on the amount of results to return.
  • cursor (str) – A cursor can be provided to navigate through pages of results.
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

A data object containing the requested data with several getter methods with different output formats.

Return type:

v04.dto.RawResponse

cognite.v04.raw.get_tables(database_name: str = None, limit: int = None, cursor: str = None, api_key=None, project=None)

Returns a RawObject containing a list of tables in a raw database.

Parameters:
  • database_name (str) – The database name to retrieve tables from.
  • limit (int) – A limit on the amount of results to return.
  • cursor (str) – A cursor can be provided to navigate through pages of results.
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

A data object containing the requested data with several getter methods with different output formats.

Return type:

v04.dto.RawResponse

Tagmatching

Tag Matching Module

This module mirrors the Tag Matching API. It allows the user to search for tag id matches.

https://doc.cognitedata.com/0.4/#Cognite-API-Tag-Matching

cognite.v04.tagmatching.tag_matching(tag_ids, fuzzy_threshold=0, platform=None, **kwargs)

Returns a TagMatchingObject containing a list of matched tags for the given query.

This method takes an arbitrary string as argument and performs fuzzy matching with a user defined threshold toward tag ids in the system.

Parameters:
  • tag_ids (list) – The tag_ids to retrieve matches for.
  • fuzzy_threshold (int) – The threshold to use when searching for matches. A fuzzy threshold of 0 means you only want to accept perfect matches. Must be >= 0.
  • platform (str) – The platform to search on.
Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

A data object containing the requested data with several getter methods with different output formats.

Return type:

v04.dto.TagMatchingResponse

Timeseries

Timeseries Module

This module mirrors the Timeseries API. It allows you to fetch data from the api and output it in various formats.

https://doc.cognitedata.com/0.4/#Cognite-API-Time-series

cognite.v04.timeseries.get_datapoints(tag_id, aggregates=None, granularity=None, start=None, end=None, **kwargs)

Returns a DatapointsObject containing a list of datapoints for the given query.

This method will automate paging for the user and return all data for the given time period.

Parameters:
  • tag_id (str) – The tag_id to retrieve data for.
  • aggregates (list) – The list of aggregate functions you wish to apply to the data. Valid aggregate functions are: ‘average/avg, max, min, count, sum, interpolation/int, stepinterpolation/step’.
  • granularity (str) – The granularity of the aggregate values. Valid entries are : ‘day/d, hour/h, minute/m, second/s’, or a multiple of these indicated by a number as a prefix e.g. ‘12hour’.
  • start (Union[str, int, datetime]) – Get datapoints after this time. Format is N[timeunit]-ago where timeunit is w,d,h,m,s. E.g. ‘2d-ago’ will get everything that is up to 2 days old. Can also send time in ms since epoch or a datetime object which will be converted to ms since epoch UTC.
  • end (Union[str, int, datetime]) – Get datapoints up to this time. Same format as for start.
Keyword Arguments:
 
  • protobuf (bool) – Download the data using the binary protobuf format. Only applicable when getting raw data. Defaults to True.
  • processes (int) – Number of download processes to run in parallell. Defaults to number returned by cpu_count().
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

A data object containing the requested data with several getter methods with different output formats.

Return type:

v04.dto.DatapointsResponse

cognite.v04.timeseries.get_datapoints_frame(tag_ids, aggregates, granularity, start=None, end=None, **kwargs)

Returns a pandas dataframe of datapoints for the given tag_ids all on the same timestamps.

This method will automate paging for the user and return all data for the given time period.

Parameters:
  • tag_ids (list) – The list of tag_ids to retrieve data for. Each tag_id can be either a string containing the tag_id or a dictionary containing the tag_id and a list of specific aggregate functions.
  • aggregates (list) – The list of aggregate functions you wish to apply to the data for which you have not specified an aggregate function. Valid aggregate functions are: ‘average/avg, max, min, count, sum, interpolation/int, stepinterpolation/step’.
  • granularity (str) – The granularity of the aggregate values. Valid entries are : ‘day/d, hour/h, minute/m, second/s’, or a multiple of these indicated by a number as a prefix e.g. ‘12hour’.
  • start (Union[str, int, datetime]) – Get datapoints after this time. Format is N[timeunit]-ago where timeunit is w,d,h,m,s. E.g. ‘2d-ago’ will get everything that is up to 2 days old. Can also send time in ms since epoch or a datetime object which will be converted to ms since epoch UTC.
  • end (Union[str, int, datetime]) – Get datapoints up to this time. Same format as for start.
Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
  • processes (int) – Number of download processes to run in parallell. Defaults to number returned by cpu_count().
Returns:

A pandas dataframe containing the datapoints for the given tag_ids. The datapoints for all the tag_ids will all be on the same timestamps.

Return type:

pandas.DataFrame

Note

The tag_ids parameter can take a list of strings and/or dicts on the following formats:

Using strings:
    ['<tag_id1>', '<tag_id2>']

Using dicts:
    [{'tagId': '<tag_id1>', 'aggregates': ['<aggfunc1>', '<aggfunc2>']},
    {'tagId': '<tag_id2>', 'aggregates': []}]

Using both:
    ['<tagid1>', {'tagId': '<tag_id2>', 'aggregates': ['<aggfunc1>', '<aggfunc2>']}]
cognite.v04.timeseries.get_latest(tag_id, **kwargs)

Returns a LatestDatapointObject containing the latest datapoint for the given tag_id.

Parameters:

tag_id (str) – The tag_id to retrieve data for.

Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

A data object containing the requested data with several getter methods with different output formats.

Return type:

v04.dto.LatestDatapointsResponse

cognite.v04.timeseries.get_multi_tag_datapoints(datapoints_queries, aggregates=None, granularity=None, start=None, end=None, **kwargs)

Returns a list of DatapointsObjects each of which contains a list of datapoints for the given timeseries.

This method will automate paging for the user and return all data for the given time period(s).

Parameters:
  • datapoints_queries (list[v04.dto.DatapointsQuery]) – The list of DatapointsQuery objects specifying which timeseries to retrieve data for.
  • aggregates (list, optional) – The list of aggregate functions you wish to apply to the data. Valid aggregate functions are: ‘average/avg, max, min, count, sum, interpolation/int, stepinterpolation/step’.
  • granularity (str) – The granularity of the aggregate values. Valid entries are : ‘day/d, hour/h, minute/m, second/s’, or a multiple of these indicated by a number as a prefix e.g. ‘12hour’.
  • start (Union[str, int, datetime]) – Get datapoints after this time. Format is N[timeunit]-ago where timeunit is w,d,h,m,s. E.g. ‘2d-ago’ will get everything that is up to 2 days old. Can also send time in ms since epoch or a datetime object which will be converted to ms since epoch UTC.
  • end (Union[str, int, datetime]) – Get datapoints up to this time. Same format as for start.
Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

A list of data objects containing the requested data with several getter methods with different output formats.

Return type:

list(v04.dto.DatapointsResponse)

cognite.v04.timeseries.get_timeseries(prefix=None, description=None, include_metadata=False, asset_id=None, path=None, **kwargs)

Returns a TimeseriesObject containing the requested timeseries.

Parameters:
  • prefix (str) – List timeseries with this prefix in the name.
  • description (str) – Filter timeseries taht contains this string in its description.
  • include_metadata (bool) – Decide if the metadata field should be returned or not. Defaults to False.
  • asset_id (int) – Get timeseries related to this asset.
  • path (str) – Get timeseries under this asset path branch.
Keyword Arguments:
 
  • limit (int) – Number of results to return.
  • api_key (str) – Your api-key.
  • project (str) – Project name.
  • autopaging (bool) – Whether or not to automatically page through results. If set to true, limit will be disregarded. Defaults to False.
Returns:

A data object containing the requested timeseries with several getter methods with different output formats.

Return type:

v04.dto.TimeSeriesResponse

cognite.v04.timeseries.post_datapoints(tag_id, datapoints: List[cognite.v04.dto.Datapoint], **kwargs)

Insert a list of datapoints.

Parameters:
  • tag_id (str) – ID of timeseries to insert to.
  • datapoints (list[v04.dto.Datapoint) – List of datapoint data transfer objects to insert.
Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

An empty response.

cognite.v04.timeseries.post_multi_tag_datapoints(timeseries_with_datapoints: List[cognite.v04.dto.TimeseriesWithDatapoints], **kwargs)

Insert data into multiple timeseries.

Parameters:

timeseries_with_datapoints (List[v04.dto.TimeseriesWithDatapoints]) – The timeseries with data to insert.

Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

An empty response.

cognite.v04.timeseries.post_time_series(time_series: List[cognite.v04.dto.TimeSeries], **kwargs)

Create a new time series.

Parameters:

timeseries (list[v04.dto.TimeSeries]) – List of time series data transfer objects to create.

Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

An empty response.

cognite.v04.timeseries.update_time_series(time_series: List[cognite.v04.dto.TimeSeries], **kwargs)

Update an existing time series.

For each field that can be updated, a null value indicates that nothing should be done.

Parameters:

timeseries (list[v04.dto.TimeSeries]) – List of time series data transfer objects to update.

Keyword Arguments:
 
  • api_key (str) – Your api-key.
  • project (str) – Project name.
Returns:

An empty response.