Files in data modeling

Cognite's core data model uses CogniteFile to represent files. The actual file content is handled by the File service. This article describes how to use files with the core data model.

alpha

The examples below include Cognite Python SDK functionality that's in alpha release state. The functionality is in an early testing phase and can be changed or removed without prior notice. Refer to the changelog for details.

CogniteFile in the core data model

CogniteFile uses the assets property to associate a file with one or more CogniteAssets, and other properties to hold metadata of the file.

The access control for CogniteFile is handled by the datamodelinstances access-control list (ACL). This is the only ACL required to access files in the core data model.

Create, retrieve and delete files

To create a file, use the Cognite Python SDK CogniteFileApply data class:

    from pathlib import Path
    
    from cognite.client.data_classes.data_modeling import NodeId
    from cognite.client.data_classes.data_modeling.cdm.v1 import CogniteFileApply, CogniteFile
    
    # Create a file node in the specified space:
    client.data_modeling.instances.apply(
        CogniteFileApply(name="FileName", space="Space", external_id="File001")
    )

    # Retrieve the created file node:
    file_info_retrieved = client.data_modeling.instances.retrieve_nodes(
        nodes=NodeId("Space", "File001"), node_cls=CogniteFile
    )
    print(file_info_retrieved)

    # When you have created the file node, to upload the content:
    client.files.upload_content("file.txt", instance_id=NodeId("Space", "File001"))

    # To download the content:
    client.files.download_to_path("downloaded_file.txt", instance_id=NodeId("Space", "File001"))

    # To delete a file, delete the node:
    client.data_modeling.instances.delete(nodes=NodeId("Space", "File001"))

Associate files to CogniteAsset

To associate files to CogniteAsset, provide the instance identifiers of the asset nodes:

    from cognite.client.data_classes.data_modeling import DirectRelationReference, NodeId
    from cognite.client.data_classes.data_modeling.cdm.v1 import CogniteFileApply, CogniteFile

    # Create or modify a file node with the asset references:
    client.data_modeling.instances.apply(
        CogniteFileApply(
            space="Space",
            name = "FileName",
            external_id="File001",
            assets=[
                DirectRelationReference("Space", "Asset001"),
                DirectRelationReference("Space", "Asset002"),
            ],
        )
    )

    # Retrieve the file node to see the asset references:
    file_info_retrieved = client.data_modeling.instances.retrieve_nodes(
        nodes=NodeId("Space", "File001"), node_cls=CogniteFile
    )
    print(file_info_retrieved)