Package com.cognite.client

Class Assets

java.lang.Object
com.cognite.client.Assets
All Implemented Interfaces:
ListSource<Asset>
public abstract class Assets extends Object implements ListSource<Asset>
This class represents the Cognite assets api endpoint. It provides methods for reading and writing Asset.

  • Field Details

    • LOG

      protected static final org.slf4j.Logger LOG

  • Constructor Details

    • Assets

      public Assets()

  • Method Details

    • of

      public static Assets of(CogniteClient client)
      Constructs a new Assets object using the provided client configuration. This method is intended for internal use--SDK clients should always use CogniteClient as the entry point to this class.
      Parameters:
      client - The CogniteClient to use for configuration settings.
      Returns:
      the assets api object.

    • list

      public Iterator<List<Asset>> list() throws Exception
      Returns all Asset objects.

      Example:

       
     List<Asset> listAssetsResults = new ArrayList<>();
     client.assets()
             .list()
             .forEachRemaining(listAssetsResults::addAll);
      API Reference - Filter assets
      Throws:
      Exception
      See Also:

    • list

      public Iterator<List<Asset>> list(Request requestParameters) throws Exception
      Returns all Asset objects that matches the filters set in the Request. The results are paged through / iterated over via an Iterator--the entire results set is not buffered in memory, but streamed in "pages" from the Cognite api. If you need to buffer the entire results set, then you have to stream these results into your own data structure. The assets are retrieved using multiple, parallel request streams towards the Cognite api. The number of parallel streams are set in the ClientConfig.

      Example:

       
      List<Asset> listAssetsResults = new ArrayList<>();
      client.assets()
              .list(Request.create()
                             .withFilterParameter("source", "source"))
              .forEachRemaining(listAssetsResults::addAll);
      API Reference - Filter assets
      Specified by:
      list in interface ListSource<Asset>
      Parameters:
      requestParameters - the filters to use for retrieving the assets.
      Returns:
      an Iterator to page through the results set.
      Throws:
      Exception
      See Also:

    • list

      public Iterator<List<Asset>> list(Request requestParameters, String... partitions) throws Exception
      Returns all Asset objects that matches the filters set in the Request for the specified partitions. This is method is intended for advanced use cases where you need direct control over the individual partitions. For example, when using the SDK in a distributed computing environment. The results are paged through / iterated over via an Iterator--the entire results set is not buffered in memory, but streamed in "pages" from the Cognite api. If you need to buffer the entire results set, then you have to stream these results into your own data structure.

      Example:

       
      List<Asset> listAssetsResults = new ArrayList<>();
      client.assets()
              .list(Request.create()
                             .withFilterParameter("source", "source"),
                                  "1/8","2/8","3/8","4/8","5/8","6/8","7/8","8/8")
              .forEachRemaining(listAssetsResults::addAll);
      API Reference - Filter assets
      Parameters:
      requestParameters - the filters to use for retrieving the assets.
      partitions - the partitions to include.
      Returns:
      an Iterator to page through the results set.
      Throws:
      Exception
      See Also:

    • stream

      public Publisher<Asset> stream()
      Returns a Publisher that can stream Asset from Cognite Data Fusion. When an Asset is created or updated, it will be captured by the publisher and emitted to the registered consumer.

      Example:

       
      List<Asset> eventList = new CopyOnWriteArrayList<>();
      Publisher<Asset> publisher = client.assets().stream()
                     .withRequest(Request.create()
                             .withFilterMetadataParameter("source", "source"))
                     .withStartTime(Instant.now())
                     .withEndTime(Instant.now().plusSeconds(25))
                     .withPollingInterval(Duration.ofSeconds(2))
                     .withPollingOffset(Duration.ofSeconds(15L))
                     .withConsumer(batch -> {
                         eventList.addAll(batch);
                     });
      Future<Boolean> streamer = publisher.start();
      Boolean result = streamer.get();
      Returns:
      The publisher producing the stream of assets. Call start() to start the stream.
      See Also:

    • retrieve

      public List<Asset> retrieve(String... externalId) throws Exception
      Retrieve assets by externalId.

      Example:

       
      List<Asset> retrievedAssets = client.assets().retrieve("1","2");
      API Reference - Retrieve assets
      Parameters:
      externalId - The externalIds to retrieve
      Returns:
      The retrieved assets.
      Throws:
      Exception
      See Also:

    • retrieve

      public List<Asset> retrieve(long... id) throws Exception
      Retrieve assets by internal id.

      Example:

       
      List<Asset> retrievedAssets = client.assets().retrieve(1,2);
      API Reference - Retrieve assets
      Parameters:
      id - The ids to retrieve
      Returns:
      The retrieved assets.
      Throws:
      Exception
      See Also:

    • retrieve

      public List<Asset> retrieve(List<Item> items) throws Exception
      Retrieve assets by externalId / id.

      Example:

       
      List<Item> assetItems = List.of(Item.newBuilder().setExternalId("1").build());
      List<Asset> retrievedAssets = client.assets().retrieve(assetItems);
      API Reference - Retrieve assets
      Parameters:
      items - The item(s) externalId / id to retrieve.
      Returns:
      The retrieved assets.
      Throws:
      Exception
      See Also:

    • aggregate

      public Aggregate aggregate(Request requestParameters) throws Exception
      Performs an item aggregation request to Cognite Data Fusion. The default aggregation is a total item count based on the (optional) filters in the request. Multiple aggregation types are supported. Please refer to the Cognite API specification for more information on the possible settings.

      Example:

       
      Aggregate aggregateResult = client.assets()
                  .aggregate(Request.create()
                  .withFilterParameter("source", "source"));
      API Reference - Aggregate assets
      Parameters:
      requestParameters - The filtering and aggregates specification
      Returns:
      The aggregation results.
      Throws:
      Exception
      See Also:

    • synchronizeMultipleHierarchies

      public List<Asset> synchronizeMultipleHierarchies(Collection<Asset> assetHierarchies) throws Exception
      Synchronizes the input collection of Asset (representing multiple, complete asset hierarchies) with existing asset hierarchies in CDF. This method will inspect the input collection of Asset and identify the various asset hierarchies. Each hierarchy is then processed by synchronizeHierarchy(Collection).

      Example:

       
      List<Asset> originalAssetList = // List of Asset;
      originalAssetList.addAll(// List of Asset);
      List<Asset> upsertedAssets = client.assets().synchronizeMultipleHierarchies(originalAssetList);
      Parameters:
      assetHierarchies - The input asset hierarchies--this represents the target state of the synchronization.
      Returns:
      the synchronized assets.
      Throws:
      Exception
      See Also:

    • synchronizeHierarchy

      public List<Asset> synchronizeHierarchy(Collection<Asset> assetHierarchy) throws Exception
      Synchronizes the input collection of Asset (representing a single, complete asset hierarchy) with an existing asset hierarchy in CDF. The input asset collection represents the target state. New asset nodes will be added, changed asset nodes will be updated and deleted asset nodes will be removed (from CDF). Algorithm: - Verify that the input collection satisfies the hierarchy constraints: - All assets must specify an externalId. - No duplicates (based on externalId). - The collection must contain one and only one asset object with no parent reference (representing the root node) - All other assets must contain a valid parentExternalId reference (no self-references). - No circular references. - Read the CDF asset hierarchy based on the identified root external id. - Compare the input collection with the existing CDF hierarchy. Identify creates, updates and deletes. - Write creates and updates in topological order. - Write deletes in reverse topological order.

      Example:

       
      List<Asset> originalAssetList = // List of Asset;
      List<Asset> upsertedAssets = client.assets().synchronizeHierarchy(originalAssetList);
      Parameters:
      assetHierarchy - The input asset hierarchy--this represents the target state of the synchronization.
      Returns:
      the synchronized assets.
      Throws:
      Exception
      See Also:

    • upsert

      public List<Asset> upsert(Collection<Asset> assets) throws Exception
      Creates or updates a set of Asset objects. If it is a new Asset object (based on id / externalId, then it will be created. If an Asset object already exists in Cognite Data Fusion, it will be updated. The update behavior is specified via the update mode in the ClientConfig settings. The assets will be checked for integrity and topologically sorted before an ordered upsert operation is started. The following constraints will be evaluated: - All assets must specify an externalId. - No duplicates (based on externalId. - No self-reference. - No circular references.

      Example:

       
      List<Asset> upsertAssetsList = // List of Asset;
      client.assets().upsert(upsertAssetsList);
      API Reference - Create assets
      API Reference - Update assets
      Parameters:
      assets - The assets to upsert.
      Returns:
      The upserted assets.
      Throws:
      Exception
      See Also:

    • verifyAssetHierarchyIntegrity

      public boolean verifyAssetHierarchyIntegrity(Collection<Asset> assets)
      Checks a collection of assets for integrity. The assets must represent a single, complete hierarchy. This verifies if the collection satisfies the constraints of the Cognite Data Fusion data model if you were to write them using the upsert method. The following constraints will be evaluated: - All assets must specify an externalId. - No duplicates (based on externalId). - The collection must contain one and only one asset object with no parent reference (representing the root node) - All other assets must contain a valid parentExternalId reference (no self-references). - No circular references.
      Parameters:
      assets - A collection of Asset representing a single, complete asset hierarchy.
      Returns:

    • delete

      public List<Item> delete(List<Item> items) throws Exception
      Deletes a set of assets. The assets to delete are identified via their externalId / id by submitting a list of Item. This method will not delete assets recursively. Please use delete(List<Item> items, boolean recursive) for recursive deletes.

      Example:

       
     List<Item> deleteItemsInput = List.of(Item.newBuilder().setExternalId("1").build());
     List<Item> deleteItemsResults = client.assets().delete(deleteItemsInput);
      API Reference - Delete assets
      Parameters:
      items - a list of Item representing the assets (externalId / id) to be deleted
      Returns:
      The deleted events via Item
      Throws:
      Exception
      See Also:

    • delete

      public List<Item> delete(List<Item> items, boolean recursive) throws Exception
      Deletes a set of assets. The assets to delete are identified via their externalId / id by submitting a list of Item.

      Example:

       
     List<Item> deleteItemsInput = List.of(Item.newBuilder().setExternalId("1").build());
     List<Item> deleteItemsResults = client.assets().delete(deleteItemsInput, true);
      API Reference - Delete assets
      Parameters:
      items - a list of Item representing the assets (externalId / id) to be deleted
      recursive - Set to true to recursively delete all subtrees under the specified items.
      Returns:
      The deleted events via Item
      Throws:
      Exception
      See Also:

    • getClient

      public abstract CogniteClient getClient()

    • buildPartitionsList

      protected List<String> buildPartitionsList(int noPartitions)
      Builds an array of partition specifications for parallel retrieval from the Cognite api. This specification is used as a parameter together with the filter / list endpoints. The number of partitions indicate the number of parallel read streams. Employ one partition specification per read stream.

      Example:

       
      List<String> partitions = buildPartitionsList(getClient().getClientConfig().getNoListPartitions());
      Parameters:
      noPartitions - The total number of partitions
      Returns:
      a List of partition specifications

    • listJson

      protected Iterator<List<String>> listJson(ResourceType resourceType, Request requestParameters, String... partitions) throws Exception
      Will return the results from a list / filter api endpoint. For example, the filter assets endpoint. The results are paged through / iterated over via an Iterator--the entire results set is not buffered in memory, but streamed in "pages" from the Cognite api. If you need to buffer the entire results set, then you have to stream these results into your own data structure. This method support parallel retrieval via a set of partition specifications. The specified partitions will be collected and merged together before being returned via the Iterator.

      Example:

       
      Iterator<List<String>> result = listJson(resourceType, requestParameters, partitions);
      Parameters:
      resourceType - The resource type to query / filter / list. Ex. event, asset, time series.
      requestParameters - The query / filter specification. Follows the Cognite api request parameters.
      partitions - An optional set of partitions to read via.
      Returns:
      an Iterator over the results set.
      Throws:
      Exception
      See Also:

    • listJson

      protected Iterator<List<String>> listJson(ResourceType resourceType, Request requestParameters, String partitionKey, String... partitions) throws Exception
      Will return the results from a list / filter api endpoint. For example, the filter assets endpoint. The results are paged through / iterated over via an Iterator--the entire results set is not buffered in memory, but streamed in "pages" from the Cognite api. If you need to buffer the entire results set, then you have to stream these results into your own data structure. This method support parallel retrieval via a set of partition specifications. The specified partitions will be collected and merged together before being returned via the Iterator.

      Example:

       
      Iterator<List<String>> result = listJson(resourceType, requestParameters, partitionKey, partitions);
      Parameters:
      resourceType - The resource type to query / filter / list. Ex. event, asset, time series.
      requestParameters - The query / filter specification. Follows the Cognite api request parameters.
      partitionKey - The key to use for the partitions in the read request. For example partition or cursor.
      partitions - An optional set of partitions to read via.
      Returns:
      an Iterator over the results set.
      Throws:
      Exception

    • retrieveJson

      protected List<String> retrieveJson(ResourceType resourceType, Collection<Item> items) throws Exception
      Retrieve items by id. Will ignore unknown ids by default.

      Example:

       
      Collection<Item> items = //Collection of items with ids;
      List<String> result = retrieveJson(resourceType, items);
      Parameters:
      resourceType - The item resource type (Event, Asset, etc.) to retrieve.
      items - The item(s) externalId / id to retrieve.
      Returns:
      The items in Json representation.
      Throws:
      Exception
      See Also:

    • retrieveJson

      protected List<String> retrieveJson(ResourceType resourceType, Collection<Item> items, Map<String,Object> parameters) throws Exception
      Retrieve items by id. This version allows you to explicitly set additional parameters for the retrieve request. For example: <"ignoreUnknownIds", true> and <"fetchResources", true>.

      Example:

       
      Collection<Item> items = //Collection of items with ids;
      Map<String, Object> parameters = //Parameters;
      List<String> result = retrieveJson(resourceType, items, parameters);
      Parameters:
      resourceType - The item resource type (Event, Asset, etc.) to retrieve.
      items - The item(s) externalId / id to retrieve.
      parameters - Additional parameters for the request. For example <"ignoreUnknownIds", true>
      Returns:
      The items in Json representation.
      Throws:
      Exception

    • aggregate

      protected Aggregate aggregate(ResourceType resourceType, Request requestParameters) throws Exception
      Performs an item aggregation request to Cognite Data Fusion. The default aggregation is a total item count based on the (optional) filters in the request. Some resource types, for example Event, supports multiple types of aggregation.

      Example:

       
      Aggregate aggregateResult = aggregate(resourceType,requestParameters);
      Parameters:
      resourceType - The resource type to perform aggregation of.
      requestParameters - The request containing filters.
      Returns:
      The aggregation result.
      Throws:
      Exception
      See Also:

    • addAuthInfo

      protected Request addAuthInfo(Request request) throws Exception
      Adds the required authentication information into the request object. If the request object already have complete auth info nothing will be added. The following authentication schemes are supported: 1) API key. When using an api key, this service will look up the corresponding project/tenant to issue requests to.

      Example:

       
      Request requestParams = addAuthInfo(request);
      Parameters:
      request - The request to enrich with auth information.
      Returns:
      The request parameters with auth info added to it.
      Throws:
      Exception

    • getListResponseIterator

      protected Iterator<CompletableFuture<ResponseItems<String>>> getListResponseIterator(ResourceType resourceType, Request requestParameters) throws Exception
      Throws:
      Exception

    • parseItems

      protected List<Item> parseItems(List<String> input) throws Exception
      Parses a list of item object in json representation to typed objects.

      Example:

       
      List<String> input = //List of json;
      List<Item> resultList = parseItems(input);
      Parameters:
      input - the item list in Json string representation
      Returns:
      the parsed item objects
      Throws:
      Exception

    • toRequestItems

      protected List<Map<String,Object>> toRequestItems(Collection<Item> itemList)
      Converts a list of Item to a request object structure (that can later be parsed to Json).

      Example:

       
      Collection<Item> itemList = //Collection of items;
      List<Map<String, Object>> result = toRequestItems(itemList);
      Parameters:
      itemList - The items to parse.
      Returns:
      The items in request item object form.

    • deDuplicate

      protected List<Item> deDuplicate(Collection<Item> itemList)
      De-duplicates a collection of Item.

      Example:

       
      Collection<Item> itemList = //Collection of items;
      List<Item> result = deDuplicate(itemList);
      Parameters:
      itemList -
      Returns:

    • itemsHaveId

      protected boolean itemsHaveId(Collection<Item> items)
      Returns true if all items contain either an externalId or id.

      Example:

       
      Collection<Item> items = //Collection of items;
      boolean result = itemsHaveId(items);
      Parameters:
      items -
      Returns:

    • mapItemToId

      protected Map<String,Item> mapItemToId(Collection<Item> items)
      Maps all items to their externalId (primary) or id (secondary). If the id function does not return any identity, the item will be mapped to the empty string. Via the identity mapping, this function will also perform deduplication of the input items.

      Example:

       
      Collection<Item> items = //Collection of items;
      Map<String, Item> result = mapItemToId(items);
      Parameters:
      items - the items to map to externalId / id.
      Returns:
      the Map with all items mapped to externalId / id.

    • parseString

      protected String parseString(String itemJson, String fieldName)
      Try parsing the specified Json path as a String.

      Example:

       
      String json = //String of json object
      String result = parseString(json, "name");
      Parameters:
      itemJson - The Json string
      fieldName - The Json path to parse
      Returns:
      The Json path as a String.

    • parseName

      protected String parseName(String json)
      Returns the name attribute value from a json input.

      Example:

       
      String json = //String of json object
      String result = parseName(json);
      Parameters:
      json - the json to parse
      Returns:
      The name value