# Upgrade

In this article:

Upgrade JavaScript SDK 2.x to 3.x
Upgrade JavaScript SDK 1.x to 2.x
- Constructor
- Changes

# Upgrade JavaScript SDK 2.x to 3.x

How to upgrade from SDK version 2.x to 3.x.

# Renamed interfaces

Some TypeScript interfaces have been renamed to have consistency between different resource types. Among the most used ones are:

GetTimeSeriesMetadataDTO -> Timeseries
PostTimeSeriesMetadataDTO -> ExternalTimeseries
DatapointsGetAggregateDatapoint -> DatapointAggregates
FilesMetadata -> FileInfo

You can find a comprehensive list in the changelog (opens new window).

# Events aggregate endpoints moved to a sub-API

client.events.aggregate(...) -> client.events.aggregate.count()
client.events.uniqueValuesAggregate(...) -> client.events.aggregate.uniqueValues(...)

# Timestamp-to-Date auto-conversion

The JavaScript SDK automatically converts response timestamp values to date objects. This caused a bug (opens new window) in the Raw API. The fix can introduce a breaking change if you use the Raw API, and possibly in other places.

# Helper classes removed

AssetClass, TimeSeriesClass, TimeSeriesList and AssetList contained some helper methods that have been removed.

Most of these helpers can be easily re-implemented using other SDK calls.

Some examples:

Asset.delete()

public async delete(options: DeleteOptions = {}) {
  return this.client.assets.delete(
    [{ id: this.id }],
    options
  );
}

1
2
3
4
5
6

Asset.subtree()

public async subtree() {
  const { items } = await client.assets.list({
    filter: {
      assetSubtreeIds: [{ id: this.id }],
    }
  });
}

1
2
3
4
5
6
7

TimeSeriesList.getAllDatapoints(...)

public getAllDatapoints = async (options: DatapointsMultiQueryBase = {}) => {
  const tsIds = this.map(({ id }) => ({ id }));
  return this.client.datapoints.retrieve({
    items: tsIds,
    ...options,
  });
};

1
2
3
4
5
6
7

# Removed client.assets.retrieveSubtree(...)

Copies the functionality of Asset.subtree() (read above).

# Change filter passing to client.timeseries.list

The function previously took a TimeseriesFilter as input, and now takes a TimeseriesFilterQuery which corresponds closely to the API spec. All filter related fields should now be in the filter object.

# Example:

// Old way
const timeseries = await client.timeseries.list({
  assetIds: [1, 2],
  unit: 'liter',
  limit: 100,
});
//New way
const timeseries = await client.timeseries.list({
  filter: { assetIds: [1, 2], unit: 'liter' },
  limit: 100,
});

1
2
3
4
5
6
7
8
9
10
11
12

# Upgrade JavaScript SDK 1.x to 2.x

How to upgrade from SDK version 1.x to 2.x.

# Constructor

In 2.x.x you need to create a new SDK instance before you can use the SDK:

const client = new CogniteClient({ appId: 'YOUR APPLICATION NAME' });

Next, you need to authenticate your client by calling one of these methods on the client:

With API key:

client.loginWithApiKey({ project, apiKey });

With OAuth:

client.loginWithOAuth({
  project: 'publicdata',
});

1
2
3

For more info about OAuth-authentication, see here.

# Changes

1.x.x	2.x.x
AUTHENTICATION
`sdk.Login.authorize(...)`	See constructor-section
`sdk.Login.loginWithApiKey(...)`	See constructor-section
`sdk.Logout.logout()`	Removed
`sdk.Logout.retrieveLogoutUrl(...)`	Removed
ASSETS
`sdk.Assets.create([...])`	`client.assets.create([...])`
`sdk.Assets.retrieve(123)`	`client.assets.retrieve([{id: 123}])`
`sdk.Assets.retrieveMultiple([123, 456])`	`client.assets.retrieve([{id: 123}, {id: 456}])`
`sdk.Assets.update(id, changes)`	`client.assets.update([{id, update: changes}])`
`sdk.Assets.updateMultiple([{id, ...changes}])`	`client.assets.update([{id, update: changes}])`
`sdk.Assets.overwriteMultiple(...)`	Removed
`sdk.Assets.delete([id])`	`client.assets.delete([{id: 123}])`
`sdk.Assets.list({name: 'abc'})`	`client.assets.list({filter: {name: 'abc'}}).autoPagingToArray({limit: 1000})`
`sdk.Assets.listDescendants(id, params)`	Not implemented yet. Follow issue here (opens new window)
`sdk.Assets.search({name: 'abc'})`	`client.assets.search({search: {name: 'abc'})`
TIME SERIES
`sdk.TimeSeries.create([...])`	`client.timeseries.create([...])`
`sdk.TimeSeries.retrieve(123)`	`client.timeseries.retrieve([{id: 123}])`
`sdk.TimeSeries.retrieveMultiple([123, 456])`	`client.timeseries.retrieve([{id: 123}, {id: 456}])`
`sdk.TimeSeries.update(id, changes)`	`client.timeseries.update([{id, update: changes}])`
`sdk.TimeSeries.updateMultiple([{id, ...changes}])`	`client.timeseries.update([{id, update: changes}])`
`sdk.TimeSeries.list({limit: 20})`	`client.timeseries.list().autoPagingToArray({limit: 20})`
`sdk.TimeSeries.search({name: 'abc'})`	`client.timeseries.search({search: {name: 'abc'}})`
DATA POINTS
`sdk.Datapoints.insert(id, datapoints)`	`client.datapoints.insert([{id, datapoints}])`
`sdk.Datapoints.insertByName(...)`	Removed
`sdk.Datapoints.insertMultiple([{name, datapoints}])`	Not supported using name. Use IDs instead: `client.datapoints.insert([{id, datapoints}])`
`sdk.Datapoints.retrieve(id, params)`	`client.datapoints.retrieve({items: [{id}], ...params})`
`sdk.Datapoints.retrieveByName(...)`	Removed (use ID instead)
`sdk.Datapoints.retrieveMultiple(...)`	Not directly supported. Use `client.datapoints.retrieve`
`sdk.Datapoints.retrieveLatest(name, before)`	Use IDs: `client.datapoints.retrieveLatest([{id, before}])`
`client.datapoints.retrieveCSV(...)`	Removed
`sdk.Datapoints.delete(name, timestamp)`	Use IDs: `client.datapoints.delete([{id, inclusiveBegin: timestamp, exclusiveEnd: timestamp}])`
`sdk.Datapoints.deleteRange(name, inclusiveBegin, exclusiveEnd)`	Use IDs: `client.datapoints.delete([{id, inclusiveBegin, exclusiveEnd}])`
EVENTS
`sdk.Events.create([...])`	`client.events.create([...])`
`sdk.Events.retrieve(id)`	`client.events.retrieve([{id}])`
`sdk.Events.retrieveMultiple([123, 456])`	`client.events.retrieve([{id: 123}, {id: 456}])`
`sdk.Events.update([{id, ...changes}])`	`client.events.update([{id, update: changes}])`
`sdk.Events.delete([id])`	`client.events.delete([{id}])`
`sdk.Events.list({limit: 20})`	`client.events.list().autoPagingToArray({limit: 20})`
`sdk.Events.search({name: 'abc'})`	`client.events.search({search: {name: 'abc'}})`
FILES
`sdk.Files.upload(fileMetadata, params)`	`client.files.upload(fileMetadata, fileContent?, overwrite?, waitUntilAcknowledged?)`
`sdk.Files.download(id)`	`client.files.getDownloadUrls([{id}])`
`sdk.Files.retrieveMetadata(id)`	`client.files.retrieve([{id}])`
`sdk.Files.retrieveMultipleMetadata([123, 456])`	`client.files.retrieve([{id: 123}, {id: 456}])`
`sdk.Files.updateMetadata(id, changes)`	`client.files.update([{id, update: changes}])`
`sdk.Files.updateMultipleMetadata([id, ...changes])`	`client.files.update([{id, update: changes}])`
`sdk.Files.delete([id])`	`client.files.delete([{id}])`
`sdk.Files.list({limit: 20})`	`client.files.list().autoPagingToArray({limit: 20})`
`sdk.Files.search({name: 'abc'})`	`client.files.search({search: {name: 'abc'}})`
`sdk.Files.replaceMetadata(...)`	Removed
3D
`sdk.ThreeD.createAssetMappings(modelId, revisionId, mappings)`	`client.assetMappings3D.create(modelId, revisionId, mappings)`
`sdk.ThreeD.createModels([name])`	`client.models3D.create([{name}])`
`sdk.ThreeD.createRevisions(modelId, revisions)`	`client.revisions3D.create(modelId, revisions)`
`sdk.ThreeD.retrieveFile(fileId, responseType)`	`client.files3D.retrieve(fileId)`
`sdk.ThreeD.retrieveModel(modelId)`	`client.models3D.retrieve(modelId)`
`sdk.ThreeD.retrieveRevision(modelId, revisionId)`	`client.models3D.retrieve(modelId, revisionId)`
`sdk.ThreeD.updateModels({id, name})`	`client.models3D.update([{id, update: {name}])`
`sdk.ThreeD.updateRevisions(modelId, {id, ...changes})`	`client.revisions3D.update(modelId, [{id, update: changes])`
`sdk.ThreeD.updateRevisionThumbnail(...)`	`client.revisions3D.updateThumbnail(modelId, revisionId, fileId)`
`sdk.ThreeD.deleteModels([id])`	`client.models3D.delete([{id}])`
`sdk.ThreeD.deleteRevisions(modelId, [id])`	`client.revisions3D.delete(modelId, [{id}])`
`sdk.ThreeD.deleteAssetMappings(modelId, revisionId, mappings)`	`client.assetMappings3D.delete(modelId, revisionId, mappings)`
`sdk.ThreeD.listAssetMappings(modelId, revisionId, params)`	`client.assetMappings3D.list(modelId, revisionId, params).autoPagingToArray()`
`sdk.ThreeD.listModels(params)`	`client.models3D.list(params).autoPagingToArray()`
`sdk.ThreeD.listNodes(modelId, revisionId, params)`	`client.revisions3D.list3DNodes(modelId, revisionId, params).autoPagingToArray()`
`sdk.ThreeD.listNodeAncestors(modelId, revisionId, params)`	`client.revisions3D.list3DNodeAncestors(modelId, revisionId, nodeId, params).autoPagingToArray()`
`sdk.ThreeD.listRevisions(modelId, params)`	`client.revisions3D.list(modelId, params).autoPagingToArray()`
`sdk.ThreeD.listSectors(modelId, revisionId, params)`	`client.viewer3D.listRevealSectors3D(modelId, revisionId, params).autoPagingToArray()`