Sequences

Metadata

Retrieve a sequence by id

SequencesAPI.retrieve(id: int | None = None, external_id: str | None = None) Sequence | None

Retrieve a single sequence by id.

Parameters
  • id (int | None) – ID

  • external_id (str | None) – External ID

Returns

Requested sequence or None if it does not exist.

Return type

Sequence | None

Examples

Get sequence by id:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.sequences.retrieve(id=1)

Get sequence by external id:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.sequences.retrieve()

Retrieve multiple sequences by id

SequencesAPI.retrieve_multiple(ids: Sequence[int] | None = None, external_ids: SequenceNotStr[str] | None = None, ignore_unknown_ids: bool = False) SequenceList

Retrieve multiple sequences by id.

Parameters
  • ids (Sequence[int] | None) – IDs

  • external_ids (SequenceNotStr[str] | None) – External IDs

  • ignore_unknown_ids (bool) – Ignore IDs and external IDs that are not found rather than throw an exception.

Returns

The requested sequences.

Return type

SequenceList

Examples

Get sequences by id:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.sequences.retrieve_multiple(ids=[1, 2, 3])

Get sequences by external id:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.sequences.retrieve_multiple(external_ids=["abc", "def"])

List sequences

SequencesAPI.list(name: str | None = None, external_id_prefix: str | None = None, metadata: dict[str, str] | None = None, asset_ids: Sequence[int] | None = None, asset_subtree_ids: int | Sequence[int] | None = None, asset_subtree_external_ids: str | SequenceNotStr[str] | None = None, data_set_ids: int | Sequence[int] | None = None, data_set_external_ids: str | SequenceNotStr[str] | None = None, created_time: dict[str, Any] | TimestampRange | None = None, last_updated_time: dict[str, Any] | TimestampRange | None = None, limit: int | None = 25) SequenceList

List sequences

Parameters
  • name (str | None) – Filter out sequences that do not have this exact name.

  • external_id_prefix (str | None) – Filter out sequences that do not have this string as the start of the externalId

  • metadata (dict[str, str] | None) – Filter out sequences that do not match these metadata fields and values (case-sensitive). Format is {“key1”:”value1”,”key2”:”value2”}.

  • asset_ids (Sequence[int] | None) – Filter out sequences that are not linked to any of these assets.

  • asset_subtree_ids (int | Sequence[int] | None) – Asset subtree id or list of asset subtree ids to filter on.

  • asset_subtree_external_ids (str | SequenceNotStr[str] | None) – Asset subtree external id or list of asset subtree external ids to filter on.

  • data_set_ids (int | Sequence[int] | None) – Return only sequences in the specified data set(s) with this id / these ids.

  • data_set_external_ids (str | SequenceNotStr[str] | None) – Return only sequences in the specified data set(s) with this external id / these external ids.

  • created_time (dict[str, Any] | TimestampRange | None) – Range between two timestamps. Possible keys are min and max, with values given as time stamps in ms.

  • last_updated_time (dict[str, Any] | TimestampRange | None) – Range between two timestamps. Possible keys are min and max, with values given as time stamps in ms.

  • limit (int | None) – Max number of sequences to return. Defaults to 25. Set to -1, float(“inf”) or None to return all items.

Returns

The requested sequences.

Return type

SequenceList

Examples

List sequences:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.sequences.list(limit=5)

Iterate over sequences:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> for seq in client.sequences:
...     seq # do something with the sequence

Iterate over chunks of sequences to reduce memory load:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> for seq_list in client.sequences(chunk_size=2500):
...     seq_list # do something with the sequences

Aggregate sequences

SequencesAPI.aggregate(filter: SequenceFilter | dict | None = None) list[CountAggregate]

Aggregate sequences

Parameters

filter (SequenceFilter | dict | None) – Filter on sequence filter with exact match

Returns

List of sequence aggregates

Return type

list[CountAggregate]

Examples

Aggregate sequences:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.sequences.aggregate(filter={"external_id_prefix": "prefix"})

Aggregate Sequences Count

SequencesAPI.aggregate_count(advanced_filter: Filter | dict | None = None, filter: SequenceFilter | dict | None = None) int

Count of sequences matching the specified filters and search.

Parameters
  • advanced_filter (Filter | dict | None) – The filter to narrow down the sequences to count.

  • filter (SequenceFilter | dict | None) – The filter to narrow down sequences to count requiring exact match.

Returns

The number of sequences matching the specified filters and search.

Return type

int

Examples

Count the number of time series in your CDF project:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> count = client.sequences.aggregate_count()

Count the number of sequences with external id prefixed with “mapping:” in your CDF project:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import filters
>>> from cognite.client.data_classes.sequences import SequenceProperty
>>> client = CogniteClient()
>>> is_mapping = filters.Prefix(SequenceProperty.external_id, "mapping:")
>>> count = client.sequences.aggregate_count(advanced_filter=is_mapping)

Aggregate Sequences Value Cardinality

SequencesAPI.aggregate_cardinality_values(property: SequenceProperty | str | list[str], advanced_filter: Filter | dict | None = None, aggregate_filter: AggregationFilter | dict | None = None, filter: SequenceFilter | dict | None = None) int

Find approximate property count for sequences.

Parameters
  • property (SequenceProperty | str | list[str]) – The property to count the cardinality of.

  • advanced_filter (Filter | dict | None) – The filter to narrow down the sequences to count cardinality.

  • aggregate_filter (AggregationFilter | dict | None) – The filter to apply to the resulting buckets.

  • filter (SequenceFilter | dict | None) – The filter to narrow down the sequences to count requiring exact match.

Returns

The number of properties matching the specified filters and search.

Return type

int

Examples

Count the number of different values for the metadata key “efficiency” used for sequences in your CDF project:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes.sequences import SequenceProperty
>>> client = CogniteClient()
>>> count = client.sequences.aggregate_cardinality_values(SequenceProperty.metadata_key("efficiency"))

Count the number of timezones (metadata key) for sequences with the word “critical” in the description in your CDF project, but exclude timezones from america:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import filters, aggregations as aggs
>>> from cognite.client.data_classes.sequences import SequenceProperty
>>> client = CogniteClient()
>>> not_america = aggs.Not(aggs.Prefix("america"))
>>> is_critical = filters.Search(SequenceProperty.description, "critical")
>>> timezone_count = client.sequences.aggregate_cardinality_values(
...     SequenceProperty.metadata_key("timezone"),
...     advanced_filter=is_critical,
...     aggregate_filter=not_america)

Aggregate Sequences Property Cardinality

SequencesAPI.aggregate_cardinality_properties(path: SequenceProperty | str | list[str], advanced_filter: Filter | dict | None = None, aggregate_filter: AggregationFilter | dict | None = None, filter: SequenceFilter | dict | None = None) int

Find approximate paths count for sequences.

Parameters
  • path (SequenceProperty | str | list[str]) – The scope in every document to aggregate properties. The only value allowed now is [“metadata”]. It means to aggregate only metadata properties (aka keys).

  • advanced_filter (Filter | dict | None) – The filter to narrow down the sequences to count cardinality.

  • aggregate_filter (AggregationFilter | dict | None) – The filter to apply to the resulting buckets.

  • filter (SequenceFilter | dict | None) – The filter to narrow down the sequences to count requiring exact match.

Returns

The number of properties matching the specified filters and search.

Return type

int

Examples

Count the number of different metadata keys in your CDF project:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes.sequences import SequenceProperty
>>> client = CogniteClient()
>>> count = client.sequences.aggregate_cardinality_values(SequenceProperty.metadata)

Aggregate Sequences Unique Values

SequencesAPI.aggregate_unique_values(property: SequenceProperty | str | list[str], advanced_filter: Filter | dict | None = None, aggregate_filter: AggregationFilter | dict | None = None, filter: SequenceFilter | dict | None = None) UniqueResultList

Get unique paths with counts for sequences.

Parameters
  • property (SequenceProperty | str | list[str]) – The property to group by.

  • advanced_filter (Filter | dict | None) – The filter to narrow down the sequences to count cardinality.

  • aggregate_filter (AggregationFilter | dict | None) – The filter to apply to the resulting buckets.

  • filter (SequenceFilter | dict | None) – The filter to narrow down the sequences to count requiring exact match.

Returns

List of unique values of sequences matching the specified filters and search.

Return type

UniqueResultList

Examples

Get the timezones (metadata key) with count for your sequences in your CDF project:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes.sequences import SequenceProperty
>>> client = CogniteClient()
>>> result = client.sequences.aggregate_unique_values(SequenceProperty.metadata_key("timezone"))
>>> print(result.unique)

Get the different metadata keys with count used for sequences created after 2020-01-01 in your CDF project:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import filters
>>> from cognite.client.data_classes.sequences import SequenceProperty
>>> from cognite.client.utils import timestamp_to_ms
>>> from datetime import datetime
>>> client = CogniteClient()
>>> created_after_2020 = filters.Range(SequenceProperty.created_time, gte=timestamp_to_ms(datetime(2020, 1, 1)))
>>> result = client.sequences.aggregate_unique_values(SequenceProperty.metadata, advanced_filter=created_after_2020)
>>> print(result.unique)

Get the different metadata keys with count for sequences updated after 2020-01-01 in your CDF project, but exclude all metadata keys that starts with “test”:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes.sequences import SequenceProperty
>>> from cognite.client.data_classes import aggregations as aggs, filters
>>> client = CogniteClient()
>>> not_test = aggs.Not(aggs.Prefix("test"))
>>> created_after_2020 = filters.Range(SequenceProperty.last_updated_time, gte=timestamp_to_ms(datetime(2020, 1, 1)))
>>> result = client.sequences.aggregate_unique_values(SequenceProperty.metadata, advanced_filter=created_after_2020, aggregate_filter=not_test)
>>> print(result.unique)

Aggregate Sequences Unique Properties

SequencesAPI.aggregate_unique_properties(path: SequenceProperty | str | list[str], advanced_filter: Filter | dict | None = None, aggregate_filter: AggregationFilter | dict | None = None, filter: SequenceFilter | dict | None = None) UniqueResultList

Find approximate unique sequence properties.

Parameters
  • path (SequenceProperty | str | list[str]) – The scope in every document to aggregate properties. The only value allowed now is [“metadata”]. It means to aggregate only metadata properties (aka keys).

  • advanced_filter (Filter | dict | None) – The filter to narrow down the sequences to count cardinality.

  • aggregate_filter (AggregationFilter | dict | None) – The filter to apply to the resulting buckets.

  • filter (SequenceFilter | dict | None) – The filter to narrow down the sequences to count requiring exact match.

Returns

List of unique values of sequences matching the specified filters and search.

Return type

UniqueResultList

Examples

Get the metadata keys with count for your sequences in your CDF project:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes.sequences import SequenceProperty
>>> client = CogniteClient()
>>> result = client.sequences.aggregate_unique_properties(SequenceProperty.metadata)

Search for sequences

SequencesAPI.search(name: str | None = None, description: str | None = None, query: str | None = None, filter: SequenceFilter | dict | None = None, limit: int = 25) SequenceList

Search for sequences. Primarily meant for human-centric use-cases and data exploration, not for programs, since matching and ordering may change over time. Use the list function if stable or exact matches are required.

Parameters
  • name (str | None) – Prefix and fuzzy search on name.

  • description (str | None) – Prefix and fuzzy search on description.

  • query (str | None) – 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’

  • filter (SequenceFilter | dict | None) – Filter to apply. Performs exact match on these fields.

  • limit (int) – Max number of results to return.

Returns

The search result as a SequenceList

Return type

SequenceList

Examples

Search for a sequence:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.sequences.search(name="some name")

Create a sequence

SequencesAPI.create(sequence: Sequence | SequenceWrite) Sequence
SequencesAPI.create(sequence: Sequence[Sequence] | Sequence[SequenceWrite]) SequenceList

Create one or more sequences.

Parameters

sequence (Sequence | SequenceWrite | Sequence[Sequence] | Sequence[SequenceWrite]) – Sequence or list of Sequence to create. The Sequence columns parameter is a list of objects with fields externalId (external id of the column, when omitted, they will be given ids of ‘column0, column1, …’), valueType (data type of the column, either STRING, LONG, or DOUBLE, with default DOUBLE), name, description, metadata (optional fields to describe and store information about the data in the column). Other fields will be removed automatically, so a columns definition from a different sequence object can be passed here.

Returns

The created sequence(s).

Return type

Sequence | SequenceList

Examples

Create a new sequence:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import SequenceWrite, SequenceColumnWrite
>>> client = CogniteClient()
>>> column_def = [
...     SequenceColumnWrite(value_type="String", external_id="user", description="some description"),
...     SequenceColumnWrite(value_type="Double", external_id="amount")
... ]
>>> seq = client.sequences.create(SequenceWrite(external_id="my_sequence", columns=column_def))

Create a new sequence with the same column specifications as an existing sequence:

>>> seq2 = client.sequences.create(SequenceWrite(external_id="my_copied_sequence", columns=column_def))

Delete sequences

SequencesAPI.delete(id: int | Sequence[int] | None = None, external_id: str | SequenceNotStr[str] | None = None, ignore_unknown_ids: bool = False) None

Delete one or more sequences.

Parameters
  • id (int | Sequence[int] | None) – Id or list of ids

  • external_id (str | SequenceNotStr[str] | None) – External ID or list of external ids

  • ignore_unknown_ids (bool) – Ignore IDs and external IDs that are not found rather than throw an exception.

Examples

Delete sequences by id or external id:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> client.sequences.delete(id=[1,2,3], external_id="3")

Filter sequences

SequencesAPI.filter(filter: Filter | dict, sort: SortSpec | list[SortSpec] | None = None, limit: int | None = 25) SequenceList

Advanced filter sequences

Advanced filter lets you create complex filtering expressions that combine simple operations, such as equals, prefix, exists, etc., using boolean operators and, or, and not. It applies to basic fields as well as metadata.

Parameters
  • filter (Filter | dict) – Filter to apply.

  • sort (SortSpec | list[SortSpec] | None) – The criteria to sort by. Can be up to two properties to sort by default to ascending order.

  • limit (int | None) – Maximum number of results to return. Defaults to 25. Set to -1, float(“inf”) or None to return all items.

Returns

List of sequences that match the filter criteria.

Return type

SequenceList

Examples

Find all sequences with asset id ‘123’ and metadata key ‘type’ equals ‘efficiency’ and return them sorted by created time:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import filters as flt
>>> client = CogniteClient()
>>> asset_filter = flt.Equals("asset_id", 123)
>>> is_efficiency = flt.Equals(["metadata", "type"], "efficiency")
>>> res = client.time_series.filter(filter=flt.And(asset_filter, is_efficiency), sort="created_time")

Note that you can check the API documentation above to see which properties you can filter on with which filters.

To make it easier to avoid spelling mistakes and easier to look up available properties for filtering and sorting, you can also use the SequenceProperty and SortableSequenceProperty enums.

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import filters as flt
>>> from cognite.client.data_classes.sequences import SequenceProperty, SortableSequenceProperty
>>> client = CogniteClient()
>>> asset_filter = flt.Equals(SequenceProperty.asset_id, 123)
>>> is_efficiency = flt.Equals(SequenceProperty.metadata_key("type"), "efficiency")
>>> res = client.time_series.filter(
...     filter=flt.And(asset_filter, is_efficiency),
...     sort=SortableSequenceProperty.created_time)

Update sequences

SequencesAPI.update(item: Sequence | SequenceWrite | SequenceUpdate) Sequence
SequencesAPI.update(item: Sequence[Sequence | SequenceWrite | SequenceUpdate]) SequenceList

Update one or more sequences.

Parameters

item (Sequence | SequenceWrite | SequenceUpdate | Sequence[Sequence | SequenceWrite | SequenceUpdate]) – Sequences to update

Returns

Updated sequences.

Return type

Sequence | SequenceList

Examples

Update a sequence that you have fetched. This will perform a full update of the sequences:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.sequences.retrieve(id=1)
>>> res.description = "New description"
>>> res = client.sequences.update(res)

Perform a partial update on a sequence, updating the description and adding a new field to metadata:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import SequenceUpdate
>>> client = CogniteClient()
>>> my_update = SequenceUpdate(id=1).description.set("New description").metadata.add({"key": "value"})
>>> res = client.sequences.update(my_update)

Updating column definitions

Currently, updating the column definitions of a sequence is only supported through partial update, using add, remove and modify methods on the columns property.

Add a single new column:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import SequenceUpdate, SequenceColumn
>>> client = CogniteClient()
>>>
>>> my_update = SequenceUpdate(id=1).columns.add(SequenceColumn(value_type ="String",external_id="user", description ="some description"))
>>> res = client.sequences.update(my_update)

Add multiple new columns:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import SequenceUpdate, SequenceColumn
>>> client = CogniteClient()
>>>
>>> column_def = [
...     SequenceColumn(value_type ="String",external_id="user", description ="some description"),
...     SequenceColumn(value_type="Double", external_id="amount")]
>>> my_update = SequenceUpdate(id=1).columns.add(column_def)
>>> res = client.sequences.update(my_update)

Remove a single column:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import SequenceUpdate
>>> client = CogniteClient()
>>>
>>> my_update = SequenceUpdate(id=1).columns.remove("col_external_id1")
>>> res = client.sequences.update(my_update)

Remove multiple columns:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import SequenceUpdate
>>> client = CogniteClient()
>>>
>>> my_update = SequenceUpdate(id=1).columns.remove(["col_external_id1","col_external_id2"])
>>> res = client.sequences.update(my_update)

Update existing columns:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import SequenceUpdate, SequenceColumnUpdate
>>> client = CogniteClient()
>>>
>>> column_updates = [
...     SequenceColumnUpdate(external_id="col_external_id_1").external_id.set("new_col_external_id"),
...     SequenceColumnUpdate(external_id="col_external_id_2").description.set("my new description"),
... ]
>>> my_update = SequenceUpdate(id=1).columns.modify(column_updates)
>>> res = client.sequences.update(my_update)

Upsert sequences

SequencesAPI.upsert(item: Sequence[Sequence | SequenceWrite], mode: Literal['patch', 'replace'] = 'patch') SequenceList
SequencesAPI.upsert(item: Sequence | SequenceWrite, mode: Literal['patch', 'replace'] = 'patch') Sequence
Upsert sequences, i.e., update if it exists, and create if it does not exist.

Note this is a convenience method that handles the upserting for you by first calling update on all items, and if any of them fail because they do not exist, it will create them instead.

For more details, see Upsert.

Parameters
  • item (Sequence | SequenceWrite | Sequence[Sequence | SequenceWrite]) – Sequence or list of sequences to upsert.

  • mode (Literal["patch", "replace"]) – Whether to patch or replace in the case the sequences are existing. If you set ‘patch’, the call will only update fields with non-null values (default). Setting ‘replace’ will unset any fields that are not specified.

Returns

The upserted sequence(s).

Return type

Sequence | SequenceList

Examples

Upsert for sequences:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import Sequence
>>> client = CogniteClient()
>>> existing_sequence = client.sequences.retrieve(id=1)
>>> existing_sequence.description = "New description"
>>> new_sequence = Sequence(external_id="new_sequence", description="New sequence")
>>> res = client.sequences.upsert([existing_sequence, new_sequence], mode="replace")

Rows

Retrieve data

SequencesDataAPI.retrieve(*, external_id: str, start: int = 0, end: int | None = None, columns: SequenceNotStr[str] | None = None, limit: int | None = None) SequenceRows
SequencesDataAPI.retrieve(*, external_id: SequenceNotStr[str], start: int = 0, end: int | None = None, columns: SequenceNotStr[str] | None = None, limit: int | None = None) SequenceRowsList
SequencesDataAPI.retrieve(*, id: int, start: int = 0, end: int | None = None, columns: SequenceNotStr[str] | None = None, limit: int | None = None) SequenceRows
SequencesDataAPI.retrieve(*, id: Sequence[int], start: int = 0, end: int | None = None, columns: SequenceNotStr[str] | None = None, limit: int | None = None) SequenceRowsList

Retrieve data from a sequence

Parameters
  • external_id (str | SequenceNotStr[str] | None) – The external id of the sequence to retrieve from.

  • id (int | Sequence[int] | None) – The internal if the sequence to retrieve from.

  • start (int) – Row number to start from (inclusive).

  • end (int | None) – Upper limit on the row number (exclusive). Set to None or -1 to get all rows until end of sequence.

  • columns (SequenceNotStr[str] | None) – List of external id for the columns of the sequence. If ‘None’ is passed, all columns will be retrieved.

  • limit (int | None) – Maximum number of rows to return per sequence. Pass None to fetch all (possibly limited by ‘end’).

  • **kwargs (Any) – To support deprecated argument ‘column_external_ids’, will be removed in the next major version. Use ‘columns’ instead.

Returns

SequenceRows if a single identifier was given, else SequenceDataList

Return type

SequenceRows | SequenceRowsList

Examples

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.sequences.data.retrieve(id=1)
>>> tuples = [(r,v) for r,v in res.items()] # You can use this iterator in for loops and list comprehensions,
>>> single_value = res[23] # ... get the values at a single row number,
>>> col = res.get_column(external_id='columnExtId') # ... get the array of values for a specific column,
>>> df = res.to_pandas() # ... or convert the result to a dataframe

Insert rows into a sequence

SequencesDataAPI.insert(rows: SequenceRows | dict[int, Sequence[int | float | str]] | Sequence[tuple[int, Sequence[int | float | str]]] | Sequence[dict[str, Any]], columns: SequenceNotStr[str] | None = None, id: int | None = None, external_id: str | None = None, **kwargs: Any) None

Insert rows into a sequence

Parameters
  • rows (SequenceRows | dict[int, Sequence[int | float | str]] | Sequence[tuple[int, Sequence[int | float | str]]] | Sequence[dict[str, Any]]) – The rows you wish to insert. Can either be a list of tuples, a list of {“rowNumber”:… ,”values”: …} objects, a dictionary of rowNumber: data, or a SequenceData object. See examples below.

  • columns (SequenceNotStr[str] | None) – List of external id for the columns of the sequence.

  • id (int | None) – Id of sequence to insert rows into.

  • external_id (str | None) – External id of sequence to insert rows into.

  • **kwargs (Any) – To support deprecated argument ‘column_external_ids’, will be removed in the next major version. Use ‘columns’ instead.

Examples

Your rows of data can be a list of tuples where the first element is the rownumber and the second element is the data to be inserted:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import Sequence, SequenceColumn
>>> client = CogniteClient()
>>> seq = client.sequences.create(Sequence(columns=[SequenceColumn(value_type="String", external_id="col_a"),
...     SequenceColumn(value_type="Double", external_id ="col_b")]))
>>> data = [(1, ['pi',3.14]), (2, ['e',2.72]) ]
>>> client.sequences.data.insert(columns=["col_a","col_b"], rows=data, id=1)

They can also be provided as a list of API-style objects with a rowNumber and values field:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> data = [{"rowNumber": 123, "values": ['str',3]}, {"rowNumber": 456, "values": ["bar",42]} ]
>>> client.sequences.data.insert(data, id=1, columns=["col_a","col_b"]) # implicit columns are retrieved from metadata

Or they can be a given as a dictionary with row number as the key, and the value is the data to be inserted at that row:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> data = {123 : ['str',3], 456 : ['bar',42] }
>>> client.sequences.data.insert(columns=['stringColumn','intColumn'], rows=data, id=1)

Finally, they can be a SequenceData object retrieved from another request. In this case columns from this object are used as well.

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> data = client.sequences.data.retrieve(id=2,start=0,end=10)
>>> client.sequences.data.insert(rows=data, id=1,columns=None)

Insert a pandas dataframe into a sequence

SequencesDataAPI.insert_dataframe(dataframe: pandas.DataFrame, id: int | None = None, external_id: str | None = None, dropna: bool = True) None

Insert a Pandas dataframe.

The index of the dataframe must contain the row numbers. The names of the remaining columns specify the column external ids. The sequence and columns must already exist.

Parameters
  • dataframe (pandas.DataFrame) – Pandas DataFrame object containing the sequence data.

  • id (int | None) – Id of sequence to insert rows into.

  • external_id (str | None) – External id of sequence to insert rows into.

  • dropna (bool) – Whether to drop all NaN rows before inserting.

Examples

Multiply data in the sequence by 2:

>>> from cognite.client import CogniteClient
>>> import pandas as pd
>>> client = CogniteClient()
>>> df = pd.DataFrame({'col_a': [1, 2, 3], 'col_b': [4, 5, 6]}, index=[1, 2, 3])
>>> client.sequences.data.insert_dataframe(df, id=1)

Delete rows from a sequence

SequencesDataAPI.delete(rows: Sequence[int], id: int | None = None, external_id: str | None = None) None

Delete rows from a sequence

Parameters
  • rows (Sequence[int]) – List of row numbers.

  • id (int | None) – Id of sequence to delete rows from.

  • external_id (str | None) – External id of sequence to delete rows from.

Examples

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> client.sequences.data.delete(id=1, rows=[1,2,42])

Delete a range of rows from a sequence

SequencesDataAPI.delete_range(start: int, end: int | None, id: int | None = None, external_id: str | None = None) None

Delete a range of rows from a sequence. Note this operation is potentially slow, as retrieves each row before deleting.

Parameters
  • start (int) – Row number to start from (inclusive).

  • end (int | None) – Upper limit on the row number (exclusive). Set to None or -1 to delete all rows until end of sequence.

  • id (int | None) – Id of sequence to delete rows from.

  • external_id (str | None) – External id of sequence to delete rows from.

Examples

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> client.sequences.data.delete_range(id=1, start=0, end=None)

Sequence Data classes

class cognite.client.data_classes.sequences.Sequence(id: int | None = None, name: str | None = None, description: str | None = None, asset_id: int | None = None, external_id: str | None = None, metadata: dict[str, Any] | None = None, columns: Sequence[SequenceColumn] | None = None, created_time: int | None = None, last_updated_time: int | None = None, data_set_id: int | None = None, cognite_client: CogniteClient | None = None)

Information about the sequence stored in the database. This is the reading version of the class, it is used for retrieving data from the CDF.

Parameters
  • id (int | None) – Unique cognite-provided identifier for the sequence

  • name (str | None) – Name of the sequence

  • description (str | None) – Description of the sequence

  • asset_id (int | None) – Optional asset this sequence is associated with

  • external_id (str | None) – The external ID provided by the client. Must be unique for the resource type.

  • metadata (dict[str, Any] | None) – Custom, application-specific metadata. String key -> String value. The maximum length of the key is 32 bytes, the value 512 bytes, with up to 16 key-value pairs.

  • columns (Sequence[SequenceColumn] | None) – List of column definitions

  • created_time (int | None) – Time when this sequence was created in CDF in milliseconds since Jan 1, 1970.

  • last_updated_time (int | None) – The last time this sequence was updated in CDF, in milliseconds since Jan 1, 1970.

  • data_set_id (int | None) – Data set that this sequence belongs to

  • cognite_client (CogniteClient | None) – The client to associate with this object.

class cognite.client.data_classes.sequences.SequenceColumn(external_id: str | None = None, name: str | None = None, description: str | None = None, value_type: ValueType = 'Double', metadata: dict[str, Any] | None = None, created_time: int | None = None, last_updated_time: int | None = None)

Bases: SequenceColumnCore

This represents a column in a sequence. It is used for reading only.

Parameters
  • external_id (str | None) – The external ID provided by the client. Must be unique for the resource type.

  • name (str | None) – Name of the column

  • description (str | None) – Description of the column

  • value_type (ValueType) – The type of the column. It can be String, Double or Long.

  • metadata (dict[str, Any] | None) – Custom, application-specific metadata. String key -> String value. Maximum length of key is 32 bytes, value 512 bytes, up to 16 key-value pairs.

  • created_time (int | None) – Time when this column was created in CDF in milliseconds since Jan 1, 1970.

  • last_updated_time (int | None) – The last time this column was updated in CDF, in milliseconds since Jan 1, 1970.

as_write() SequenceColumnWrite

Returns a writeable version of this column.

class cognite.client.data_classes.sequences.SequenceColumnCore(external_id: str | None = None, name: str | None = None, description: str | None = None, value_type: ValueType = 'Double', metadata: dict[str, Any] | None = None)

Bases: WriteableCogniteResource[SequenceColumnWrite], ABC

This represents a column in a sequence.

Parameters
  • external_id (str | None) – The external ID provided by the client. Must be unique for the resource type.

  • name (str | None) – Name of the column

  • description (str | None) – Description of the column

  • value_type (ValueType) – The type of the column. It can be String, Double or Long.

  • metadata (dict[str, Any] | None) – Custom, application-specific metadata. String key -> String value. The maximum length of key is 32 bytes, value 512 bytes, up to 16 key-value pairs.

class cognite.client.data_classes.sequences.SequenceColumnList(resources: Collection[Any], cognite_client: CogniteClient | None = None)

Bases: CogniteResourceList[SequenceColumn], ExternalIDTransformerMixin

as_write() SequenceColumnWriteList

Returns a writeable version of this column list.

property value_types: list[ValueType]

Retrieves list of column value types

Returns

List of column value types

Return type

list[ValueType]

class cognite.client.data_classes.sequences.SequenceColumnUpdate(id: int | None = None, external_id: str | None = None)

Bases: CogniteUpdate

This class is used to update a sequence column.

class cognite.client.data_classes.sequences.SequenceColumnWrite(external_id: str, name: str | None = None, description: str | None = None, value_type: ValueType = 'Double', metadata: dict[str, Any] | None = None)

Bases: SequenceColumnCore

This represents a column in a sequence. This is used for writing only.

Parameters
  • external_id (str) – The external ID provided by the client. Must be unique for the resource type.

  • name (str | None) – Name of the column

  • description (str | None) – Description of the column

  • value_type (ValueType) – The type of the column. It can be String, Double or Long.

  • metadata (dict[str, Any] | None) – Custom, application-specific metadata. String key -> String value. The maximum length of key is 32 bytes, value 512 bytes, up to 16 key-value pairs.

as_write() SequenceColumnWrite

Returns this SequenceColumnWrite.

class cognite.client.data_classes.sequences.SequenceColumnWriteList(resources: Collection[Any], cognite_client: CogniteClient | None = None)

Bases: CogniteResourceList[SequenceColumnWrite], ExternalIDTransformerMixin

property value_types: list[ValueType]

Retrieves list of column value types

Returns

List of column value types

Return type

list[ValueType]

class cognite.client.data_classes.sequences.SequenceCore(name: str | None = None, description: str | None = None, asset_id: int | None = None, external_id: str | None = None, metadata: dict[str, Any] | None = None, data_set_id: int | None = None)

Bases: WriteableCogniteResource[SequenceWrite], ABC

Information about the sequence stored in the database

Parameters
  • name (str | None) – Name of the sequence

  • description (str | None) – Description of the sequence

  • asset_id (int | None) – Optional asset this sequence is associated with

  • external_id (str | None) – The external ID provided by the client. Must be unique for the resource type.

  • metadata (dict[str, Any] | None) – Custom, application-specific metadata. String key -> String value. The maximum length of the key is 32 bytes, the value 512 bytes, with up to 16 key-value pairs.

  • data_set_id (int | None) – Data set that this sequence belongs to

class cognite.client.data_classes.sequences.SequenceData(id: int | None = None, external_id: str | None = None, rows: Sequence[dict] | Sequence[SequenceRow] | None = None, row_numbers: Sequence[int] | None = None, values: Sequence[Sequence[int | str | float]] | None = None, columns: Sequence[dict[str, Any]] | SequenceColumnList | None = None)

Bases: SequenceRows

cognite.client.data_classes.sequences.SequenceDataList

alias of SequenceRowsList

class cognite.client.data_classes.sequences.SequenceFilter(name: str | None = None, external_id_prefix: str | None = None, metadata: dict[str, Any] | None = None, asset_ids: Sequence[int] | None = None, asset_subtree_ids: Sequence[dict[str, Any]] | None = None, created_time: dict[str, Any] | TimestampRange | None = None, last_updated_time: dict[str, Any] | TimestampRange | None = None, data_set_ids: Sequence[dict[str, Any]] | None = None)

Bases: CogniteFilter

No description.

Parameters
  • name (str | None) – Return only sequences with this exact name.

  • external_id_prefix (str | None) – Filter by this (case-sensitive) prefix for the external ID.

  • metadata (dict[str, Any] | None) – Filter the sequences by metadata fields and values (case-sensitive). Format is {“key1”:”value1”,”key2”:”value2”}.

  • asset_ids (Sequence[int] | None) – Return only sequences linked to one of the specified assets.

  • asset_subtree_ids (Sequence[dict[str, Any]] | None) – Only include sequences that have a related asset in a subtree rooted at any of these assetIds (including the roots given). If the total size of the given subtrees exceeds 100,000 assets, an error will be returned.

  • created_time (dict[str, Any] | TimestampRange | None) – Range between two timestamps.

  • last_updated_time (dict[str, Any] | TimestampRange | None) – Range between two timestamps.

  • data_set_ids (Sequence[dict[str, Any]] | None) – Only include sequences that belong to these datasets.

class cognite.client.data_classes.sequences.SequenceList(resources: Collection[Any], cognite_client: CogniteClient | None = None)

Bases: WriteableCogniteResourceList[SequenceWrite, Sequence], IdTransformerMixin

as_write() SequenceWriteList

Returns a writeable version of this sequence list.

class cognite.client.data_classes.sequences.SequenceProperty(value)

Bases: EnumProperty

An enumeration.

class cognite.client.data_classes.sequences.SequenceRow(row_number: int, values: Sequence[Optional[Union[int, str, float]]])

Bases: CogniteResource

This class represents a row in a sequence. It is used for both read and write.

Parameters
  • row_number (int) – The row number for this row.

  • values (Sequence[RowValues]) – List of values in the order defined in the columns field. Number of items must match. Null is accepted for missing values. String values must be no longer than 256 characters.

class cognite.client.data_classes.sequences.SequenceRows(rows: Sequence[SequenceRow], columns: SequenceColumnList, id: int | None = None, external_id: str | None = None)

Bases: CogniteResource

An object representing a list of rows from a sequence.

Parameters
  • rows (Sequence[SequenceRow]) – The sequence rows.

  • columns (SequenceColumnList) – The column information.

  • id (int | None) – Identifier of the sequence the data belong to

  • external_id (str | None) – External id of the sequence the data belong to

property column_external_ids: list[str]

Retrieves list of column external ids for the sequence, for use in e.g. data retrieve or insert methods.

Returns

List of sequence column external ids.

Return type

list[str]

property column_value_types: list[ValueType]

Retrieves list of column value types.

Returns

List of column value types

Return type

list[ValueType]

dump(camel_case: bool = True) dict[str, Any]

Dump the sequence data into a json serializable Python data type.

Parameters

camel_case (bool) – Use camelCase for attribute names. Defaults to True.

Returns

A dictionary representing the instance.

Return type

dict[str, Any]

get_column(external_id: str) list[RowValues]

Get a column by external_id.

Parameters

external_id (str) – External id of the column.

Returns

A list of values for that column in the sequence

Return type

list[RowValues]

items() Iterator[tuple[int, list[RowValues]]]

Returns an iterator over tuples of (row number, values).

to_pandas(column_names: ColumnNames = 'columnExternalId') pandas.DataFrame

Convert the sequence data into a pandas DataFrame.

Parameters

column_names (ColumnNames) – Which field(s) to use as column header. Can use “externalId”, “id”, “columnExternalId”, “id|columnExternalId” or “externalId|columnExternalId”.

Returns

The dataframe.

Return type

pandas.DataFrame

property values: list[list[RowValues]]

Returns a list of lists of values

class cognite.client.data_classes.sequences.SequenceRowsList(resources: Collection[Any], cognite_client: CogniteClient | None = None)

Bases: CogniteResourceList[SequenceRows]

to_pandas(key: Literal['id', 'external_id'] = 'external_id', column_names: Literal['externalId', 'id', 'columnExternalId', 'id|columnExternalId', 'externalId|columnExternalId'] = 'externalId|columnExternalId', concat: Literal[True] = True) pandas.DataFrame
to_pandas(key: Literal['external_id'] = 'external_id', column_names: Literal['externalId', 'id', 'columnExternalId', 'id|columnExternalId', 'externalId|columnExternalId'] = 'externalId|columnExternalId', concat: Literal[False] = False) dict[str, pandas.DataFrame]
to_pandas(key: Literal['id'], column_names: Literal['externalId', 'id', 'columnExternalId', 'id|columnExternalId', 'externalId|columnExternalId'] = 'externalId|columnExternalId', concat: Literal[False] = False) dict[int, pandas.DataFrame]

Convert the sequence data list into a pandas DataFrame. Each column will be a sequence.

Parameters
  • key (Literal["id", "external_id"]) – If concat = False, this decides which field to use as key in the dictionary. Defaults to “external_id”.

  • column_names (ColumnNames) – Which field to use as column header. Can use any combination of “externalId”, “columnExternalId”, “id” and other characters as a template.

  • concat (bool) – Whether to concatenate the sequences into a single DataFrame or return a dictionary of DataFrames. Defaults to False.

Returns

The sequence data list as a pandas DataFrame.

Return type

pandas.DataFrame | dict[str, pandas.DataFrame] | dict[int, pandas.DataFrame]

class cognite.client.data_classes.sequences.SequenceUpdate(id: int | None = None, external_id: str | None = None)

Bases: CogniteUpdate

No description.

Parameters
  • id (int) – A server-generated ID for the object.

  • external_id (str) – The external ID provided by the client. Must be unique for the resource type.

class cognite.client.data_classes.sequences.SequenceWrite(columns: Sequence[SequenceColumnWrite], name: str | None = None, description: str | None = None, asset_id: int | None = None, external_id: str | None = None, metadata: dict[str, Any] | None = None, data_set_id: int | None = None)

Bases: SequenceCore

Information about the sequence stored in the database. This is the writing version of the class, it is used for inserting data into the CDF.

Parameters
  • columns (Sequence[SequenceColumnWrite]) – List of column definitions

  • name (str | None) – Name of the sequence

  • description (str | None) – Description of the sequence

  • asset_id (int | None) – Optional asset this sequence is associated with

  • external_id (str | None) – The external ID provided by the client. Must be unique for the resource type.

  • metadata (dict[str, Any] | None) – Custom, application-specific metadata. String key -> String value. Th maximum length of key is 32 bytes, value 512 bytes, up to 16 key-value pairs.

  • data_set_id (int | None) – Data set that this sequence belongs to

as_write() SequenceWrite

Returns this SequenceWrite.

dump(camel_case: bool = True) dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters

camel_case (bool) – Use camelCase for attribute names. Defaults to True.

Returns

A dictionary representation of the instance.

Return type

dict[str, Any]

class cognite.client.data_classes.sequences.SequenceWriteList(resources: Collection[Any], cognite_client: CogniteClient | None = None)

Bases: CogniteResourceList[SequenceWrite], ExternalIDTransformerMixin

class cognite.client.data_classes.sequences.SortableSequenceProperty(value)

Bases: EnumProperty

An enumeration.