Upload a file in multiple parts

async AsyncCogniteClient.files.multipart_upload_session(
name: str,
parts: int,
external_id: str | 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,
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 manager you must enter (using the with keyword), then call upload_part for each part before exiting. It also supports async usage with async with, then calling await upload_part_async.

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, AsyncCogniteClient
>>> client = CogniteClient()
>>> # async_client = AsyncCogniteClient()  # another option
>>> 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")