Files

Retrieve file metadata by id

FilesAPI.retrieve(id: Optional[int] = None, external_id: Optional[str] = None, instance_id: Optional[NodeId] = None) → cognite.client.data_classes.files.FileMetadata | None

Retrieve a single file metadata by id.

Parameters

id (int | None) – ID
external_id (str | None) – External ID
instance_id (NodeId | None) – Instance ID

Returns

Requested file metadata or None if it does not exist.

Return type

FileMetadata | None

Examples

Get file metadata by id:

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

Get file metadata by external id:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.files.retrieve(external_id="1")

Retrieve multiple files’ metadata by id

FilesAPI.retrieve_multiple(ids: Optional[Sequence[int]] = None, external_ids: Optional[SequenceNotStr[str]] = None, instance_ids: Optional[Sequence[NodeId]] = None, ignore_unknown_ids: bool = False) → FileMetadataList

Retrieve multiple file metadatas by id.

Parameters

ids (Sequence[int] | None) – IDs
external_ids (SequenceNotStr[str] | None) – External IDs
instance_ids (Sequence[NodeId] | None) – Instance IDs
ignore_unknown_ids (bool) – Ignore IDs and external IDs that are not found rather than throw an exception.

Returns

The requested file metadatas.

Return type

FileMetadataList

Examples

Get file metadatas by id:

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

Get file_metadatas by external id:

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

List files metadata

FilesAPI.list(name: Optional[str] = None, mime_type: Optional[str] = None, metadata: Optional[dict[str, str]] = None, asset_ids: Optional[Sequence[int]] = None, asset_external_ids: Optional[SequenceNotStr[str]] = None, asset_subtree_ids: Optional[Union[int, Sequence[int]]] = None, asset_subtree_external_ids: Optional[Union[str, SequenceNotStr[str]]] = None, data_set_ids: Optional[Union[int, Sequence[int]]] = None, data_set_external_ids: Optional[Union[str, SequenceNotStr[str]]] = None, labels: Optional[LabelFilter] = None, geo_location: Optional[GeoLocationFilter] = None, source: Optional[str] = None, created_time: Optional[Union[dict[str, Any], TimestampRange]] = None, last_updated_time: Optional[Union[dict[str, Any], TimestampRange]] = None, source_created_time: Optional[Union[dict[str, Any], TimestampRange]] = None, source_modified_time: Optional[Union[dict[str, Any], TimestampRange]] = None, uploaded_time: Optional[Union[dict[str, Any], TimestampRange]] = None, external_id_prefix: Optional[str] = None, directory_prefix: Optional[str] = None, uploaded: Optional[bool] = None, limit: int | None = 25, partitions: Optional[int] = None) → FileMetadataList

List files

Parameters

name (str | None) – Name of the file.
mime_type (str | None) – File type. E.g. text/plain, application/pdf, ..
metadata (dict[str, str] | None) – Custom, application specific metadata. String key -> String value
asset_ids (Sequence[int] | None) – Only include files that reference these specific asset IDs.
asset_external_ids (SequenceNotStr[str] | None) – No description.
asset_subtree_ids (int | Sequence[int] | None) – Only include files that have a related asset in a subtree rooted at any of these assetIds. If the total size of the given subtrees exceeds 100,000 assets, an error will be returned.
asset_subtree_external_ids (str | SequenceNotStr[str] | None) – Only include files that have a related asset in a subtree rooted at any of these assetExternalIds. If the total size of the given subtrees exceeds 100,000 assets, an error will be returned.
data_set_ids (int | Sequence[int] | None) – Return only files in the specified data set(s) with this id / these ids.
data_set_external_ids (str | SequenceNotStr[str] | None) – Return only files in the specified data set(s) with this external id / these external ids.
labels (LabelFilter | None) – Return only the files matching the specified label filter(s).
geo_location (GeoLocationFilter | None) – Only include files matching the specified geographic relation.
source (str | None) – The source of this event.
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.
source_created_time (dict[str, Any] | TimestampRange | None) – Filter for files where the sourceCreatedTime field has been set and is within the specified range.
source_modified_time (dict[str, Any] | TimestampRange | None) – Filter for files where the sourceModifiedTime field has been set and is within the specified range.
uploaded_time (dict[str, Any] | TimestampRange | None) – Range between two timestamps
external_id_prefix (str | None) – External Id provided by client. Should be unique within the project.
directory_prefix (str | None) – Filter by this (case-sensitive) prefix for the directory provided by the client.
uploaded (bool | None) – Whether or not the actual file is uploaded. This field is returned only by the API, it has no effect in a post body.
limit (int | None) – Max number of files to return. Defaults to 25. Set to -1, float(“inf”) or None to return all items.
partitions (int | None) – Retrieve resources in parallel using this number of workers (values up to 10 allowed), limit must be set to None (or -1).

Returns

The requested files.

Return type

FileMetadataList

Examples

List files metadata and filter on external id prefix:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> file_list = client.files.list(limit=5, external_id_prefix="prefix")

Iterate over files metadata:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> for file_metadata in client.files:
...     file_metadata # do something with the file metadata

Iterate over chunks of files metadata to reduce memory load:

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

Filter files based on labels:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import LabelFilter
>>> client = CogniteClient()
>>> my_label_filter = LabelFilter(contains_all=["WELL LOG", "VERIFIED"])
>>> file_list = client.files.list(labels=my_label_filter)

Filter files based on geoLocation:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import GeoLocationFilter, GeometryFilter
>>> client = CogniteClient()
>>> my_geo_location_filter = GeoLocationFilter(relation="intersects", shape=GeometryFilter(type="Point", coordinates=[35,10]))
>>> file_list = client.files.list(geo_location=my_geo_location_filter)

Aggregate files metadata

FilesAPI.aggregate(filter: Optional[Union[FileMetadataFilter, dict[str, Any]]] = None) → list[cognite.client.data_classes.aggregations.CountAggregate]

Aggregate files

Parameters: filter (FileMetadataFilter | dict[str, Any] | None) – Filter on file metadata filter with exact match
Returns: List of count aggregates
Return type: list[CountAggregate]

Examples

List files metadata and filter on external id prefix:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> aggregate_uploaded = client.files.aggregate(filter={"uploaded": True})

Search for files

FilesAPI.search(name: Optional[str] = None, filter: Optional[Union[FileMetadataFilter, dict[str, Any]]] = None, limit: int = 25) → FileMetadataList

Search for files. 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.
filter (FileMetadataFilter | dict[str, Any] | None) – Filter to apply. Performs exact match on these fields.
limit (int) – Max number of results to return.

Returns

List of requested files metadata.

Return type

FileMetadataList

Examples

Search for a file:

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

Search for an asset with an attached label:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> my_label_filter = LabelFilter(contains_all=["WELL LOG"])
>>> res = client.assets.search(name="xyz",filter=FileMetadataFilter(labels=my_label_filter))

Create file metadata

FilesAPI.create(file_metadata: cognite.client.data_classes.files.FileMetadata | cognite.client.data_classes.files.FileMetadataWrite, overwrite: bool = False) → tuple[cognite.client.data_classes.files.FileMetadata, str]

Create file without uploading content.

Parameters

file_metadata (FileMetadata | FileMetadataWrite) – File metadata for the file to create.
overwrite (bool) – If ‘overwrite’ is set to true, and the POST body content specifies a ‘externalId’ field, fields for the file found for externalId can be overwritten. The default setting is false. If metadata is included in the request body, all of the original metadata will be overwritten. File-Asset mappings only change if explicitly stated in the assetIds field of the POST json body. Do not set assetIds in request body if you want to keep the current file-asset mappings.

Returns

Tuple containing the file metadata and upload url of the created file.

Return type

tuple[FileMetadata, str]

Examples

Create a file:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import FileMetadataWrite
>>> client = CogniteClient()
>>> file_metadata = FileMetadataWrite(name="MyFile")
>>> res = client.files.create(file_metadata)

Upload a file or directory

FilesAPI.upload(path: str, external_id: Optional[str] = None, name: Optional[str] = None, source: Optional[str] = None, mime_type: Optional[str] = None, metadata: Optional[dict[str, str]] = None, directory: Optional[str] = None, asset_ids: Optional[Sequence[int]] = None, source_created_time: Optional[int] = None, source_modified_time: Optional[int] = None, data_set_id: Optional[int] = None, labels: Optional[Sequence[Label]] = None, geo_location: Optional[GeoLocation] = None, security_categories: Optional[Sequence[int]] = None, recursive: bool = False, overwrite: bool = False) → cognite.client.data_classes.files.FileMetadata | cognite.client.data_classes.files.FileMetadataList

Upload a file

Parameters

path (str) – Path to the file you wish to upload. If path is a directory, this method will upload all files in that directory.
external_id (str | None) – The external ID provided by the client. Must be unique within the project.
name (str | None) – Name of the file.
source (str | None) – The source of the file.
mime_type (str | None) – File type. E.g. text/plain, application/pdf, …
metadata (dict[str, str] | None) – Customizable extra data about the file. String key -> String value.
directory (str | None) – The directory to be associated with this file. Must be an absolute, unix-style path.
asset_ids (Sequence[int] | None) – No description.
source_created_time (int | None) – The timestamp for when the file was originally created in the source system.
source_modified_time (int | None) – The timestamp for when the file was last modified in the source system.
data_set_id (int | None) – ID of the data set.
labels (Sequence[Label] | None) – A list of the labels associated with this resource item.
geo_location (GeoLocation | None) – The geographic metadata of the file.
security_categories (Sequence[int] | None) – Security categories to attach to this file.
recursive (bool) – If path is a directory, upload all contained files recursively.
overwrite (bool) – If ‘overwrite’ is set to true, and the POST body content specifies a ‘externalId’ field, fields for the file found for externalId can be overwritten. The default setting is false. If metadata is included in the request body, all of the original metadata will be overwritten. The actual file will be overwritten after successful upload. If there is no successful upload, the current file contents will be kept. File-Asset mappings only change if explicitly stated in the assetIds field of the POST json body. Do not set assetIds in request body if you want to keep the current file-asset mappings.

Returns

The file metadata of the uploaded file(s).

Return type

FileMetadata | FileMetadataList

Examples

Upload a file in a given path:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.files.upload("/path/to/file", name="my_file")

If name is omitted, this method will use the name of the file

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.files.upload("/path/to/file")

You can also upload all files in a directory by setting path to the path of a directory:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.files.upload("/path/to/my/directory")

Upload a file with a label:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import Label
>>> client = CogniteClient()
>>> res = client.files.upload("/path/to/file", name="my_file", labels=[Label(external_id="WELL LOG")])

Upload a file with a geo_location:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import GeoLocation, Geometry
>>> client = CogniteClient()
>>> geometry = Geometry(type="LineString", coordinates=[[30, 10], [10, 30], [40, 40]])
>>> res = client.files.upload("/path/to/file", geo_location=GeoLocation(type="Feature", geometry=geometry))

Upload a string or bytes

FilesAPI.upload_bytes(content: str | bytes | TextIO | BinaryIO, name: str, external_id: Optional[str] = None, source: Optional[str] = None, mime_type: Optional[str] = None, metadata: Optional[dict[str, str]] = None, directory: Optional[str] = None, asset_ids: Optional[Sequence[int]] = None, data_set_id: Optional[int] = None, labels: Optional[Sequence[Label]] = None, geo_location: Optional[GeoLocation] = None, source_created_time: Optional[int] = None, source_modified_time: Optional[int] = None, security_categories: Optional[Sequence[int]] = None, overwrite: bool = False) → FileMetadata

Upload bytes or string.

You can also pass a file handle to content.

Note that the maximum file size is 5GiB. In order to upload larger files use multipart_upload_session.

Parameters

content (str | bytes | TextIO | BinaryIO) – The content to upload.
name (str) – Name of the file.
external_id (str | None) – The external ID provided by the client. Must be unique within the project.
source (str | None) – The source of the file.
mime_type (str | None) – File type. E.g. text/plain, application/pdf,…
metadata (dict[str, str] | None) – Customizable extra data about the file. String key -> String value.
directory (str | None) – The directory to be associated with this file. Must be an absolute, unix-style path.
asset_ids (Sequence[int] | None) – No description.
data_set_id (int | None) – Id of the data set.
labels (Sequence[Label] | None) – A list of the labels associated with this resource item.
geo_location (GeoLocation | None) – The geographic metadata of the file.
source_created_time (int | None) – The timestamp for when the file was originally created in the source system.
source_modified_time (int | None) – The timestamp for when the file was last modified in the source system.
security_categories (Sequence[int] | None) – Security categories to attach to this file.
overwrite (bool) – If ‘overwrite’ is set to true, and the POST body content specifies a ‘externalId’ field, fields for the file found for externalId can be overwritten. The default setting is false. If metadata is included in the request body, all of the original metadata will be overwritten. The actual file will be overwritten after successful upload. If there is no successful upload, the current file contents will be kept. File-Asset mappings only change if explicitly stated in the assetIds field of the POST json body. Do not set assetIds in request body if you want to keep the current file-asset mappings.

Returns

No description.

Return type

FileMetadata

Examples

Upload a file from memory:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.files.upload_bytes(b"some content", name="my_file", asset_ids=[1,2,3])

Upload a file content

FilesAPI.upload_content(path: str, external_id: Optional[str] = None, instance_id: Optional[NodeId] = None) → FileMetadata

Upload a file content

Parameters

path (str) – Path to the file you wish to upload. If path is a directory, this method will upload all files in that directory.
external_id (str | None) – The external ID provided by the client. Must be unique within the project.
instance_id (NodeId | None) – Instance ID of the file.

Returns

No description.

Return type

FileMetadata

Upload a file content in string or bytes

FilesAPI.upload_content_bytes(content: str | bytes | TextIO | BinaryIO, external_id: Optional[str] = None, instance_id: Optional[NodeId] = None) → FileMetadata

Upload bytes or string.

Note that the maximum file size is 5GiB. In order to upload larger files use multipart_upload_content_session.

Parameters

content (str | bytes | TextIO | BinaryIO) – The content to upload.
external_id (str | None) – The external ID provided by the client. Must be unique within the project.
instance_id (NodeId | None) – Instance ID of the file.

Returns

No description.

Return type

FileMetadata

Examples

Upload a file from memory:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.files.upload_bytes(b"some content", name="my_file", asset_ids=[1,2,3])

Upload a file in multiple parts

FilesAPI.multipart_upload_session(name: str, parts: int, external_id: Optional[str] = None, source: Optional[str] = None, mime_type: Optional[str] = None, metadata: Optional[dict[str, str]] = None, directory: Optional[str] = None, asset_ids: Optional[Sequence[int]] = None, data_set_id: Optional[int] = None, labels: Optional[Sequence[Label]] = None, geo_location: Optional[GeoLocation] = None, source_created_time: Optional[int] = None, source_modified_time: Optional[int] = None, security_categories: Optional[Sequence[int]] = None, overwrite: bool = False) → FileMultipartUploadSession

Begin uploading a file in multiple parts. This allows uploading files larger than 5GiB. Note that the size of each part may not exceed 4000MiB, and the size of each part except the last must be greater than 5MiB.

The file chunks may be uploaded in any order, and in parallel, but the client must ensure that the parts are stored in the correct order by uploading each chunk to the correct upload URL.

This returns a context object you must enter (using the with keyword), then call upload_part on for each part before exiting.

Parameters

name (str) – Name of the file.
parts (int) – The number of parts to upload, must be between 1 and 250.
external_id (str | None) – The external ID provided by the client. Must be unique within the project.
source (str | None) – The source of the file.
mime_type (str | None) – File type. E.g. text/plain, application/pdf,…
metadata (dict[str, str] | None) – Customizable extra data about the file. String key -> String value.
directory (str | None) – The directory to be associated with this file. Must be an absolute, unix-style path.
asset_ids (Sequence[int] | None) – No description.
data_set_id (int | None) – Id of the data set.
labels (Sequence[Label] | None) – A list of the labels associated with this resource item.
geo_location (GeoLocation | None) – The geographic metadata of the file.
source_created_time (int | None) – The timestamp for when the file was originally created in the source system.
source_modified_time (int | None) – The timestamp for when the file was last modified in the source system.
security_categories (Sequence[int] | None) – Security categories to attach to this file.
overwrite (bool) – If ‘overwrite’ is set to true, and the POST body content specifies a ‘externalId’ field, fields for the file found for externalId can be overwritten. The default setting is false. If metadata is included in the request body, all of the original metadata will be overwritten. The actual file will be overwritten after successful upload. If there is no successful upload, the current file contents will be kept. File-Asset mappings only change if explicitly stated in the assetIds field of the POST json body. Do not set assetIds in request body if you want to keep the current file-asset mappings.

Returns

Object containing metadata about the created file, and information needed to upload the file content. Use this object to manage the file upload, and exit it once all parts are uploaded.

Return type

FileMultipartUploadSession

Examples

Upload binary data in two chunks

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> with client.files.multipart_upload_session("my_file.txt", parts=2) as session:
...     # Note that the minimum chunk size is 5 MiB.
...     session.upload_part(0, "hello" * 1_200_000)
...     session.upload_part(1, " world")

Upload a file content in multiple parts

FilesAPI.multipart_upload_content_session(parts: int, external_id: Optional[str] = None, instance_id: Optional[NodeId] = None) → FileMultipartUploadSession

Begin uploading a file in multiple parts. This allows uploading files larger than 5GiB. Note that the size of each part may not exceed 4000MiB, and the size of each part except the last must be greater than 5MiB.

The file chunks may be uploaded in any order, and in parallel, but the client must ensure that the parts are stored in the correct order by uploading each chunk to the correct upload URL.

This returns a context object you must enter (using the with keyword), then call upload_part on for each part before exiting.

Parameters

parts (int) – The number of parts to upload, must be between 1 and 250.
external_id (str | None) – The external ID provided by the client. Must be unique within the project.
instance_id (NodeId | None) – Instance ID of the file.

Returns

Object containing metadata about the created file, and information needed to upload the file content. Use this object to manage the file upload, and exit it once all parts are uploaded.

Return type

FileMultipartUploadSession

Examples

Upload binary data in two chunks

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> with client.files.multipart_upload_content_session(external_id="external-id", parts=2) as session:
...     # Note that the minimum chunk size is 5 MiB.
...     session.upload_part(0, "hello" * 1_200_000)
...     session.upload_part(1, " world")

Retrieve download urls

FilesAPI.retrieve_download_urls(id: Optional[Union[int, Sequence[int]]] = None, external_id: Optional[Union[str, SequenceNotStr[str]]] = None, instance_id: Optional[Union[NodeId, Sequence[NodeId]]] = None, extended_expiration: bool = False) → dict[int | str | cognite.client.data_classes.data_modeling.ids.NodeId, str]

Get download links by id or external id

Parameters

id (int | Sequence[int] | None) – Id or list of ids.
external_id (str | SequenceNotStr[str] | None) – External id or list of external ids.
instance_id (NodeId | Sequence[NodeId] | None) – Instance id or list of instance ids.
extended_expiration (bool) – Extend expiration time of download url to 1 hour. Defaults to false.

Returns

Dictionary containing download urls.

Return type

dict[int | str | NodeId, str]

Download files to disk

FilesAPI.download(directory: str | pathlib.Path, id: Optional[Union[int, Sequence[int]]] = None, external_id: Optional[Union[str, SequenceNotStr[str]]] = None, instance_id: Optional[Union[NodeId, Sequence[NodeId]]] = None, keep_directory_structure: bool = False, resolve_duplicate_file_names: bool = False) → None

Download files by id or external id.

This method will stream all files to disk, never keeping more than 2MB in memory per worker. The files will be stored in the provided directory using the file name retrieved from the file metadata in CDF. You can also choose to keep the directory structure from CDF so that the files will be stored in subdirectories matching the directory attribute on the files. When missing, the (root) directory is used. By default, duplicate file names to the same local folder will be resolved by only keeping one of the files. You can choose to resolve this by appending a number to the file name using the resolve_duplicate_file_names argument.

Warning

If you are downloading several files at once, be aware that file name collisions lead to all-but-one of the files missing. A warning is issued when this happens, listing the affected files.

Parameters

directory (str | Path) – Directory to download the file(s) to.
id (int | Sequence[int] | None) – Id or list of ids
external_id (str | SequenceNotStr[str] | None) – External ID or list of external ids.
instance_id (NodeId | Sequence[NodeId] | None) – Instance ID or list of instance ids.
keep_directory_structure (bool) – Whether or not to keep the directory hierarchy in CDF, creating subdirectories as needed below the given directory.
resolve_duplicate_file_names (bool) – Whether or not to resolve duplicate file names by appending a number on duplicate file names

Examples

Download files by id and external id into directory ‘my_directory’:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> client.files.download(directory="my_directory", id=[1,2,3], external_id=["abc", "def"])

Download files by id to the current directory:

>>> client.files.download(directory=".", id=[1,2,3])

Download a single file to a specific path

FilesAPI.download_to_path(path: pathlib.Path | str, id: Optional[int] = None, external_id: Optional[str] = None, instance_id: Optional[NodeId] = None) → None

Download a file to a specific target.

Parameters

path (Path | str) – The path in which to place the file.
id (int | None) – Id of of the file to download.
external_id (str | None) – External id of the file to download.
instance_id (NodeId | None) – Instance id of the file to download.

Examples

Download a file by id:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> client.files.download_to_path("~/mydir/my_downloaded_file.txt", id=123)

Download a file as bytes

FilesAPI.download_bytes(id: Optional[int] = None, external_id: Optional[str] = None, instance_id: Optional[NodeId] = None) → bytes

Download a file as bytes.

Parameters

id (int | None) – Id of the file
external_id (str | None) – External id of the file
instance_id (NodeId | None) – Instance id of the file

Examples

Download a file’s content into memory:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> file_content = client.files.download_bytes(id=1)

Returns: The file in binary format
Return type: bytes

Delete files

FilesAPI.delete(id: Optional[Union[int, Sequence[int]]] = None, external_id: Optional[Union[str, SequenceNotStr[str]]] = None, ignore_unknown_ids: bool = False) → None

Delete files

Parameters

id (int | Sequence[int] | None) – Id or list of ids
external_id (str | SequenceNotStr[str] | None) – str or list of str
ignore_unknown_ids (bool) – Ignore IDs and external IDs that are not found rather than throw an exception.

Examples

Delete files by id or external id:

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

Update files metadata

FilesAPI.update(item: cognite.client.data_classes.files.FileMetadata | cognite.client.data_classes.files.FileMetadataWrite | cognite.client.data_classes.files.FileMetadataUpdate, mode: Literal['replace_ignore_null', 'patch', 'replace'] = 'replace_ignore_null') → FileMetadata

FilesAPI.update(item: Sequence[cognite.client.data_classes.files.FileMetadata | cognite.client.data_classes.files.FileMetadataWrite | cognite.client.data_classes.files.FileMetadataUpdate], mode: Literal['replace_ignore_null', 'patch', 'replace'] = 'replace_ignore_null') → FileMetadataList

Update files Currently, a full replacement of labels on a file is not supported (only partial add/remove updates). See the example below on how to perform partial labels update.

Parameters

item (FileMetadata | FileMetadataWrite | FileMetadataUpdate | Sequence[FileMetadata | FileMetadataWrite | FileMetadataUpdate]) – file(s) to update.
mode (Literal['replace_ignore_null', 'patch', 'replace']) – How to update data when a non-update object is given (FilesMetadata or -Write). If you use ‘replace_ignore_null’, only the fields you have set will be used to replace existing (default). Using ‘replace’ will additionally clear all the fields that are not specified by you. Last option, ‘patch’, will update only the fields you have set and for container-like fields such as metadata or labels, add the values to the existing. For more details, see Update and Upsert Mode Parameter.

Returns

The updated files.

Return type

FileMetadata | FileMetadataList

Examples

Update file metadata that you have fetched. This will perform a full update of the file metadata:

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

Perform a partial update on file metadata, updating the source and adding a new field to metadata:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import FileMetadataUpdate
>>> client = CogniteClient()
>>> my_update = FileMetadataUpdate(id=1).source.set("new source").metadata.add({"key": "value"})
>>> res = client.files.update(my_update)

Attach labels to a files:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import FileMetadataUpdate
>>> client = CogniteClient()
>>> my_update = FileMetadataUpdate(id=1).labels.add(["PUMP", "VERIFIED"])
>>> res = client.files.update(my_update)

Detach a single label from a file:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import FileMetadataUpdate
>>> client = CogniteClient()
>>> my_update = FileMetadataUpdate(id=1).labels.remove("PUMP")
>>> res = client.files.update(my_update)

Files Data classes

Bases: FileMetadataCore

This represents the metadata for a file. It does not contain the actual file itself. This is the reading version of FileMetadata, and it is used when retrieving from CDF.

Parameters

external_id (str | None) – The external ID provided by the client. Must be unique for the resource type.
instance_id (NodeId | None) – The Instance ID for the file. (Only applicable for files created in DMS)
name (str | None) – Name of the file.
source (str | None) – The source of the file.
mime_type (str | None) – File type. E.g., text/plain, application/pdf, …
metadata (dict[str, str] | None) – Custom, application-specific metadata. String key -> String value. Limits: Maximum length of key is 32 bytes, value 512 bytes, up to 16 key-value pairs.
directory (str | None) – Directory associated with the file. It must be an absolute, unix-style path.
asset_ids (Sequence[int] | None) – No description.
data_set_id (int | None) – The dataSet ID for the item.
labels (Sequence[Label] | None) – A list of the labels associated with this resource item.
geo_location (GeoLocation | None) – The geographic metadata of the file.
source_created_time (int | None) – The timestamp for when the file was originally created in the source system.
source_modified_time (int | None) – The timestamp for when the file was last modified in the source system.
security_categories (Sequence[int] | None) – The security category IDs required to access this file.
id (int | None) – A server-generated ID for the object.
uploaded (bool | None) – Whether the actual file is uploaded. This field is returned only by the API, it has no effect in a post body.
uploaded_time (int | None) – The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.
created_time (int | None) – The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.
last_updated_time (int | None) – The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.
cognite_client (CogniteClient | None) – The client to associate with this object.

as_write() → FileMetadataWrite: Returns this FileMetadata in its writing format.

class cognite.client.data_classes.files.FileMetadataCore(external_id: Optional[str] = None, instance_id: Optional[NodeId] = None, name: Optional[str] = None, source: Optional[str] = None, mime_type: Optional[str] = None, metadata: Optional[dict[str, str]] = None, directory: Optional[str] = None, asset_ids: Optional[Sequence[int]] = None, data_set_id: Optional[int] = None, labels: Optional[Sequence[Label]] = None, geo_location: Optional[GeoLocation] = None, source_created_time: Optional[int] = None, source_modified_time: Optional[int] = None, security_categories: Optional[Sequence[int]] = None)

Bases: WriteableCogniteResource[FileMetadataWrite], ABC

No description.

Parameters

external_id (str | None) – The external ID provided by the client. Must be unique for the resource type.
instance_id (NodeId | None) – The instance ID for the file. (Only applicable for files created in DMS)
name (str | None) – Name of the file.
source (str | None) – The source of the file.
mime_type (str | None) – File type. E.g., text/plain, application/pdf, …
metadata (dict[str, str] | None) – Custom, application-specific metadata. String key -> String value. Limits: Maximum length of key is 32 bytes, value 512 bytes, up to 16 key-value pairs.
directory (str | None) – Directory associated with the file. It must be an absolute, unix-style path.
asset_ids (Sequence[int] | None) – No description.
data_set_id (int | None) – The dataSet ID for the item.
labels (Sequence[Label] | None) – A list of the labels associated with this resource item.
geo_location (GeoLocation | None) – The geographic metadata of the file.
source_created_time (int | None) – The timestamp for when the file was originally created in the source system.
source_modified_time (int | None) – The timestamp for when the file was last modified in the source system.
security_categories (Sequence[int] | None) – The security category IDs required to access this file.

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.files.FileMetadataFilter(name: Optional[str] = None, mime_type: Optional[str] = None, metadata: Optional[dict[str, str]] = None, asset_ids: Optional[Sequence[int]] = None, asset_external_ids: Optional[SequenceNotStr[str]] = None, data_set_ids: Optional[Sequence[dict[str, Any]]] = None, labels: Optional[LabelFilter] = None, geo_location: Optional[GeoLocationFilter] = None, asset_subtree_ids: Optional[Sequence[dict[str, Any]]] = None, source: Optional[str] = None, created_time: Optional[Union[dict[str, Any], TimestampRange]] = None, last_updated_time: Optional[Union[dict[str, Any], TimestampRange]] = None, uploaded_time: Optional[Union[dict[str, Any], TimestampRange]] = None, source_created_time: Optional[Union[dict[str, Any], TimestampRange]] = None, source_modified_time: Optional[Union[dict[str, Any], TimestampRange]] = None, external_id_prefix: Optional[str] = None, directory_prefix: Optional[str] = None, uploaded: Optional[bool] = None)

Bases: CogniteFilter

No description.

Parameters

name (str | None) – Name of the file.
mime_type (str | None) – File type. E.g. text/plain, application/pdf, ..
metadata (dict[str, str] | None) – Custom, application specific metadata. String key -> String value. Limits: Maximum length of key is 32 bytes, value 512 bytes, up to 16 key-value pairs.
asset_ids (Sequence[int] | None) – Only include files that reference these specific asset IDs.
asset_external_ids (SequenceNotStr[str] | None) – Only include files that reference these specific asset external IDs.
data_set_ids (Sequence[dict[str, Any]] | None) – Only include files that belong to these datasets.
labels (LabelFilter | None) – Return only the files matching the specified label(s).
geo_location (GeoLocationFilter | None) – Only include files matching the specified geographic relation.
asset_subtree_ids (Sequence[dict[str, Any]] | None) – Only include files that have a related asset in a subtree rooted at any of these asset IDs or external IDs. If the total size of the given subtrees exceeds 100,000 assets, an error will be returned.
source (str | None) – The source of this event.
created_time (dict[str, Any] | TimestampRange | None) – Range between two timestamps.
last_updated_time (dict[str, Any] | TimestampRange | None) – Range between two timestamps.
uploaded_time (dict[str, Any] | TimestampRange | None) – Range between two timestamps.
source_created_time (dict[str, Any] | TimestampRange | None) – Filter for files where the sourceCreatedTime field has been set and is within the specified range.
source_modified_time (dict[str, Any] | TimestampRange | None) – Filter for files where the sourceModifiedTime field has been set and is within the specified range.
external_id_prefix (str | None) – Filter by this (case-sensitive) prefix for the external ID.
directory_prefix (str | None) – Filter by this (case-sensitive) prefix for the directory provided by the client.
uploaded (bool | None) – Whether or not the actual file is uploaded. This field is returned only by the API, it has no effect in a post body.

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.files.FileMetadataList(resources: Iterable[Any], cognite_client: CogniteClient | None = None)

Bases: WriteableCogniteResourceList[FileMetadataWrite, FileMetadata], IdTransformerMixin

as_write() → FileMetadataWriteList: Returns this FileMetadataList in its writing format.

class cognite.client.data_classes.files.FileMetadataUpdate(id: Optional[int] = None, external_id: Optional[str] = None, instance_id: Optional[NodeId] = None)

Bases: CogniteUpdate

Changes will be applied to file.

Parameters

id (int | None) – A server-generated ID for the object.
external_id (str | None) – The external ID provided by the client. Must be unique for the resource type.
instance_id (NodeId | None) – The ID of the file.

dump(camel_case: Literal[True] = True) → dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters: camel_case (Literal[True]) – No description.
Returns: A dictionary representation of the instance.
Return type: dict[str, Any]

class cognite.client.data_classes.files.FileMetadataWrite(name: str, external_id: Optional[str] = None, instance_id: Optional[NodeId] = None, source: Optional[str] = None, mime_type: Optional[str] = None, metadata: Optional[dict[str, str]] = None, directory: Optional[str] = None, asset_ids: Optional[Sequence[int]] = None, data_set_id: Optional[int] = None, labels: Optional[Sequence[Label]] = None, geo_location: Optional[GeoLocation] = None, source_created_time: Optional[int] = None, source_modified_time: Optional[int] = None, security_categories: Optional[Sequence[int]] = None)

Bases: FileMetadataCore

This represents the metadata for a file. It does not contain the actual file itself. This is the writing version of FileMetadata, and it is used when inserting or updating files.

Parameters

name (str) – Name of the file.
external_id (str | None) – The external ID provided by the client. Must be unique for the resource type.
instance_id (NodeId | None) – The Instance ID for the file. (Only applicable for files created in DMS)
source (str | None) – The source of the file.
mime_type (str | None) – File type. E.g., text/plain, application/pdf, …
metadata (dict[str, str] | None) – Custom, application-specific metadata. String key -> String value. Limits: Maximum length of key is 32 bytes, value 512 bytes, up to 16 key-value pairs.
directory (str | None) – Directory associated with the file. It must be an absolute, unix-style path.
asset_ids (Sequence[int] | None) – No description.
data_set_id (int | None) – The dataSet ID for the item.
labels (Sequence[Label] | None) – A list of the labels associated with this resource item.
geo_location (GeoLocation | None) – The geographic metadata of the file.
source_created_time (int | None) – The timestamp for when the file was originally created in the source system.
source_modified_time (int | None) – The timestamp for when the file was last modified in the source system.
security_categories (Sequence[int] | None) – The security category IDs required to access this file.

as_write() → FileMetadataWrite: Returns self.

class cognite.client.data_classes.files.FileMetadataWriteList(resources: Iterable[Any], cognite_client: CogniteClient | None = None): Bases: CogniteResourceList[FileMetadataWrite], ExternalIDTransformerMixin

class cognite.client.data_classes.files.FileMultipartUploadSession(file_metadata: FileMetadata, upload_urls: list[str], upload_id: str, cognite_client: CogniteClient)

Bases: object

Result of a call to multipart_upload_session

Parameters

file_metadata (FileMetadata) – The created file in CDF.
upload_urls (list[str]) – List of upload URLs for the file upload.
upload_id (str) – ID of the multipart upload, needed to complete the upload.
cognite_client (CogniteClient) – Cognite client to use for completing the upload.

upload_part(part_no: int, content: str | bytes | TextIO | BinaryIO) → None

Upload part of a file. Note that if content does not somehow expose its length, this method may not work on Azure. See requests.utils.super_len.

Parameters

part_no (int) – Which part number this is, must be between 0 and parts given to multipart_upload_session
content (str | bytes | TextIO | BinaryIO) – The content to upload.