13. Working with Metadata

import dtlpy as dl
project_name = 'project_name'
dataset_name = 'dataset_name'
# Get project and dataset
project = dl.projects.get(project_name=project_name)
dataset = project.datasets.get(dataset_name=dataset_name)

13.1. User Metadata

As a powerful tool to manage data based on your categories and information, you can add any keys and values to both the item’s and annotations’ user-metadata sections using the Dataloop SDK. Then, you can use your user-metadata for data filtering, sorting, etc.

NoteWhen adding metadata to the same item, the new metadata might overwrite existing metadata. To avoid overwriting a field or the entire metadata, use the list data type.

13.1.1. Metadata Data Types

Metadata is a dictionary attribute used with items, annotations, and other entities of the Dataloop system (task, recipe, and more). As such, it can be used with string, number, boolean, list or null types.

13.1.2. String

item.metadata['user'] = dict()
item.metadata['user']['MyKey'] = 'MyValue'
annotation.metadata['user']['MyKey'] = 'MyValue'

13.1.3. Number

item.metadata['user']['MyKey'] = 3
annotation.metadata['user']['MyKey'] = 3

13.1.4. Boolean

item.metadata['user']['MyKey'] = True
annotation.metadata['user']['MyKey'] = True

13.1.5. Null – add metadata with no information

item.metadata['user']['MyKey'] = None
annotation.metadata['user']['MyKey'] = None

13.1.6. List

# add metadata of a list (can contain elements of different types).
item.metadata['user']['MyKey'] = ["A", 2, False]
annotation.metadata['user']['MyKey'] = ["A", 2, False]

13.1.7. Add new metadata to a list without losing existing data

item.metadata['user']['MyKey'].append(3)
item = item.update()
annotation.metadata['user']['MyKey'].append(3)
annotation = annotation.update()

13.1.8. Add metadata to an item’s user metadata

local_path = r'C:/home/project/images/item.mimetype'
item_id = 'write-your-id-number'
# upload and claim item
item = dataset.items.upload(local_path=local_path)
# or get item
item = dataset.items.get(item_id=item_id)
# modify metadata
item.metadata['user'] = dict()
item.metadata['user']['MyKey'] = 'MyValue'
# update and reclaim item
item = item.update()

13.1.9. Modify an existing user metadata field

local_path = r'C:/home/project/images/item.mimetype'
item_id = 'write-your-id-number'
# upload and claim item
item = dataset.items.upload(local_path=local_path)
# or get item
item = dataset.items.get(item_id=item_id)
# modify metadata
if 'user' not in item.metadata:
    item.metadata['user'] = dict()
item.metadata['user']['MyKey'] = 'MyValue'
# update and reclaim item
item = item.update()

Item in platform should have section ‘user’ in metadata with field ‘MyKey’ and value ‘MyValue’.

13.1.10. Add metadata to annotations’ user metadata

annotation_id = 'my-annotation-id'
# Get annotation
annotation = dl.annotations.get(annotation_id=annotation_id)
# modify metadata
annotation.metadata['user'] = dict()
annotation.metadata['user']['red'] = True
# update and reclaim annotation
annotation = annotation.update()

annotation in platform should have section ‘user’ in metadata with field ‘red’ and value True

13.1.11. Filter items by user metadata

13.1.11.1. 1. Get your dataset

project_name = 'project_name'
dataset_name = 'dataset_name'
project = dl.projects.get(project_name=project_name)
dataset = project.datasets.get(dataset_name=dataset_name)

13.1.11.2. 2. Add metadata to an item

You can also add metadata to filtered items

local_path = r'C:/home/project/images/item.mimetype'
item_id = 'write-your-id-number'
# upload and claim item
item = dataset.items.upload(local_path=local_path)
# or get item
item = dataset.items.get(item_id=item_id)
# modify metadata
item.metadata['user'] = dict()
item.metadata['user']['MyKey'] = 'MyValue'
# update and reclaim item
item = item.update()

13.1.11.3. 3. Create a filter

filters = dl.Filters()
# set resource - optional - default is item
filters.resource = dl.FiltersResource.ITEM

13.1.11.4. 4. Filter by your written key

filters.add(field='metadata.user.Key', values='Value')

13.1.11.5. 5. Get filtered items

pages = dataset.items.list(filters=filters)
# Go over all item and print the properties
for page in pages:
    for item in page:
        item.print()