Adding and reading client metadata

ℹ️

Note

This tutorial applies to clientMetadata, which is the metadata associated with individual data units. This is distinct from videoMetadata that is used to specify video parameters when using Strict client-only access. It is also distinct from patient metadata in DICOM files.

Client metadata is accessed by specifying the dataset using the <dataset_hash>. All projects that have the specified dataset attached will contain client metadata.

Reading metadata

The following code reads the client metadata of all data units in the specified dataset. The code prints the metadata along with the data unit's index within the dataset. 


# Import dependencies
from encord import EncordUserClient
from encord.client import DatasetAccessSettings

# Authenticate with Encord using the path to your private key
client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>"
)

# Specify a dataset to read or write metadata to
dataset = client.get_dataset("<dataset_hash>")

# Fetch the dataset's metadata
dataset.set_access_settings(DatasetAccessSettings(fetch_client_metadata=True))

# Read the metadata of all data units in the dataset.
for data_unit, data_row in enumerate(dataset.data_rows):
    print(f"{data_row.client_metadata} - Data Unit: {data_unit}")

Adding metadata

Adding metadata to a specific data unit

You can add client metadata to specific data units in the dataset.

👍

Tip

You can find the <data unit number> by reading all metadata in the dataset. The sample code provided prints all <data unit number>s.


# Import dependencies
from encord import EncordUserClient
from encord.client import DatasetAccessSettings

# Authenticate with Encord using the path to your private key
client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>"
)

# Specify a dataset to read or write metadata to
dataset = client.get_dataset("<dataset_hash>")

# Fetch the dataset's metadata
dataset.set_access_settings(DatasetAccessSettings(fetch_client_metadata=True))

# Add metadata to a specific data unit by replacing <data unit number> with the number of the data unit
data_row = dataset.data_rows[<data unit number>]

# Replace {"my": "metadata"} with the metadata you want to add
data_row.client_metadata= {"my": "metadata"}
data_row.save()
print(data_row.client_metadata)

Adding metadata to all data units in a dataset

The following code adds the same client metadata to each data unit in the specified dataset. The code prints the metadata along with the data units index within the dataset, so that you can verify the metadata has been set correctly. 


# Import dependencies
from encord import EncordUserClient
from encord.client import DatasetAccessSettings

# Authenticate with Encord using the path to your private key
client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>"
)

# Specify a dataset to read or write metadata to
dataset = client.get_dataset("<dataset_hash>")

# Fetch the dataset's metadata
dataset.set_access_settings(DatasetAccessSettings(fetch_client_metadata=True))

# Add metadata to all data units in the dataset.
# Replace {"my": "metadata"} with the metadata you want to add
for data_unit, data_row in enumerate(dataset.data_rows):
    data_row.client_metadata = {"my": "metadata"}
    data_row.save()
    print(f"{data_row.client_metadata} - Data Unit: {data_unit}")