Upload a file or directory

async AsyncCogniteClient.files.upload(
path: Path | str,
external_id: str | None = None,
name: 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,
source_created_time: int | None = None,
source_modified_time: int | None = None,
data_set_id: int | None = None,
labels: Sequence[Label] | None = None,
geo_location: GeoLocation | None = None,
security_categories: Sequence[int] | None = None,
recursive: bool = False,
overwrite: bool = False,
) → FileMetadata | FileMetadataList

Upload a file.

Parameters:

  • path (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, AsyncCogniteClient
>>> from pathlib import Path
>>> client = CogniteClient()
>>> # async_client = AsyncCogniteClient()  # another option
>>> my_file = Path("/path/to/file.txt")
>>> res = client.files.upload(my_file, name="my_file")

If name is omitted, this method will use the name of the file (file.txt in the example above):

>>> res = client.files.upload(my_file)

You can also upload all files in a directory by setting path to the path of a directory (filenames will be automatically used for name):

>>> upload_dir = Path("/path/to/my/directory")
>>> res = client.files.upload(upload_dir)

You can also upload all files in a directory recursively by passing recursive=True:

>>> res = client.files.upload(upload_dir, recursive=True)

Upload a file with a label:

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

Upload a file with a geo_location:

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