Files

`AsyncCogniteClient.files.aggregate_count`([...])	Aggregate files.
`AsyncCogniteClient.files.create`(file_metadata)	Create file without uploading content.
`AsyncCogniteClient.files.delete`([id, ...])	Delete files.
`AsyncCogniteClient.files.download`(directory)	Download files by id or external id.
`AsyncCogniteClient.files.download_bytes`([...])	Download a file as bytes.
`AsyncCogniteClient.files.download_to_path`(path)	Download a file to a specific target.
`AsyncCogniteClient.files.list`([name, ...])	List files.
`AsyncCogniteClient.files.multipart_upload_content_session`(parts)	Begin uploading a file in multiple parts whose metadata is already created in CDF.
`AsyncCogniteClient.files.multipart_upload_session`(...)	Begin uploading a file in multiple parts.
`AsyncCogniteClient.files.retrieve`([id, ...])	Retrieve a single file metadata by id.
`AsyncCogniteClient.files.retrieve_download_urls`([...])	Get download links by id or external id.
`AsyncCogniteClient.files.retrieve_multiple`([...])	Retrieve multiple file metadatas by id.
`AsyncCogniteClient.files.search`([name, ...])	Search for files.
`AsyncCogniteClient.files.update`(item[, mode])	Update files.
`AsyncCogniteClient.files.upload`(path[, ...])	Upload a file.
`AsyncCogniteClient.files.upload_bytes`(...[, ...])	Upload bytes or string.
`AsyncCogniteClient.files.upload_content`(path)	Upload a file content.
`AsyncCogniteClient.files.upload_content_bytes`(content)	Upload bytes or string (UTF-8 assumed).

Files Data classes

class cognite.client.data_classes.files.FileMetadata( id: int, uploaded: bool, created_time: int, last_updated_time: int, name: str, uploaded_time: int | None = None, external_id: str | None = None, instance_id: NodeId | None = None, source: str | None = None, mime_type: str | None = None, metadata: dict[str, str] | None = None, directory: str | None = None, asset_ids: Sequence[int] | None = None, data_set_id: int | None = None, labels: Sequence[Label] | None = None, geo_location: GeoLocation | None = None, source_created_time: int | None = None, source_modified_time: int | None = None, security_categories: Sequence[int] | None = None, )

Bases: FileMetadataCore

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

Parameters:

id (int) – A server-generated ID for the object.
uploaded (bool) – Whether the actual file is uploaded. This field is returned only by the API, it has no effect in a post body.
created_time (int) – The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.
last_updated_time (int) – The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.
name (str) – Name of the file.
uploaded_time (int | None) – The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.
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

Convert the file to a writeable version.

Returns:: A writeable version of this file.
Return type:: FileMetadataWrite
Raises:: ValueError – If the file has an instance_id as these must be created via the Data Modeling API.

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]

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.
name (str) – 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]

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: Sequence[T_CogniteResource], )

Bases: WriteableCogniteResourceList[FileMetadataWrite, FileMetadata], IdTransformerMixin

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

class cognite.client.data_classes.files.FileMetadataUpdate( id: int | None = None, external_id: str | None = None, instance_id: NodeId | None = 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]

Bases: FileMetadataCore

This represents the metadata for a file. It does not contain the actual file itself. This is the write 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.
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.

class cognite.client.data_classes.files.FileMetadataWriteList( resources: Sequence[T_CogniteResource], ): Bases: CogniteResourceList[FileMetadataWrite], ExternalIDTransformerMixin

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

Bases: AbstractContextManager[FileMultipartUploadSession], AbstractAsyncContextManager[FileMultipartUploadSession]

Result of a call to multipart_upload_session. Use upload_part_async or upload_part to upload parts, then upon exiting the context manager, the upload will be marked as completed.

Note

Can be used both as a regular and async context manager. Use

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 (AsyncCogniteClient) – Cognite client to use for completing the upload.

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

Upload part of a file.

Note

If content does not somehow expose its length, this method may not work on Azure or AWS.

Parameters:

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

async upload_part_async( part_no: int, content: str | bytes | BinaryIO, ) → None

Upload part of a file.

Note

If content does not somehow expose its length, this method may not work on Azure or AWS.

Parameters:

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