Cognite

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)

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.
cognite.config.get_base_url(api_version=None)

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

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

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

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

v05.dto.AssetResponse

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

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.

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.

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.

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.

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. .. attribute:: 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.

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.

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, step=None)

Bases: object

Data Transfer Object for a time series.

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

str – Asset that this time series belongs to.

description

str – Description of the time series.

securityCategories

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

tag_id

str – Unique ID of time series.

datapoints

List[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

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:

str

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, 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:
  • name (str) – The name of the timeseries 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:

v05.dto.DatapointsResponse

cognite.v05.timeseries.get_datapoints_frame(time_series, aggregates, granularity, start=None, 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.
  • 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

Note

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, **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, 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[v05.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(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, **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.

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_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.
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:

timeseries (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.

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

str – Asset that this time series belongs to.

description

str – Description of the time series.

securityCategories

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