Skip to main content
Collections are saved groups of data units or labels that let you curate subsets of your data and perform bulk actions on them, such as sending items to annotation, running bulk classifications, or exporting a curated Dataset.

​
Filter Presets

Filter presets are saved groups of filter criteria that you can reuse across Data Curation.

​
Create Filter Preset

Create a Filter Preset based on raw JSON. 

# Import dependencies
from encord import EncordUserClient

SSH_PATH = "file-path-to-ssh-private-key"


user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Create a preset

preset = user_client.create_preset(
    name="name-of-my-preset",
    description="A useful and meaningful description for the preset.",
    filter_preset_json={
        "global_filters": {
            "filters": [
                {
                    ... define your filter here ...
                }
            ]
        }
    },
)

print(preset)


# Import dependencies
from encord import EncordUserClient

SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"


user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Create a preset

preset = user_client.create_preset(
    name="Vehicle Speed",
    description="Specifies the speed of cars, trucks, and motorcycles.",
    filter_preset_json={
        "global_filters": {
            "filters": [
                {
                    "key": "speed",
                    "type": "client_meta_number",
                    "values": [50, 100],
                    "include": True,
                }
            ]
        }
    },
)

print(preset)

​
Update Filter Presets

All arguments are optional when updating a filter preset.

# Import dependencies
from encord import EncordUserClient

SSH_PATH = "file-path-to-ssh-private-key"

# Preset ID to update
PRESET_ID = "unique-preset-filter-id" 


user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Update a preset

preset = user_client.get_filter_preset(preset_uuid=PRESET_ID)
preset.update_preset(
    name="updated-name-of-my-preset",
    description="Updated useful and meaningful description for the preset.",
    filter_preset_json={ ... }
)

print(preset)


# Import dependencies
from encord import EncordUserClient

SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"

# Preset ID to add to the collection
PRESET_ID = "unique-preset-filter-id" 

user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Update a preset

preset = user_client.get_filter_preset(preset_uuid=PRESET_ID)
preset.update_preset(
    filter_preset_json={
        "global_filters": {
            "filters": [
                {
                    "key": "speed (kph)",
                    "type": "client_meta_number",
                    "values": [70, 120],
                    "include": True,
                }
            ]
        }
    },
)

print(preset)

​
Delete Filter Presets

Delete Preset template

# Import dependencies
from encord import EncordUserClient

# Define constants
SSH_PATH = "file-path-to-ssh-private-key"

# Preset ID to add to the collection
PRESET_ID = "unique-preset-filter-id"  

# Initialize the user client using the SSH private key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Delete the preset by ID
user_client.delete_preset(PRESET_ID)

​
List Filter Presets

List all Filter Presets in Index by name with their unique identifier. 

# Import dependencies
from encord import EncordUserClient

SSH_PATH = "file-path-to-ssh-private-key"


user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Get Preset Filters
presets = user_client.list_presets()

# List Preset Filters by name and UUID
for preset in presets:
    print(preset.name, preset.uuid)


# Import dependencies
from encord import EncordUserClient

SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"


user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Get Preset Filters
presets = user_client.list_presets()

# List Preset Filters by name and UUID
for preset in presets:
    print(preset.name, preset.uuid)

​
List Filters in Filter Preset

This code lists the filters that make up the filter preset into a JSON file format. Filters are of the following types:
  • Global filters: Global filters can apply to the data in any top-level Folder. Examples: Data type, Storage Location, Quality Metrics.
  • Local filters: Local filters can apply ONLY to specific top-level Folders. Examples: Data title, File ID, Collection.
Returned results are a combination of Global and Local filters. While Global filters provide information about filter, Local filters provide a raw filter ID. 

# Import dependencies
from encord import EncordUserClient

from pprint import pprint

from encord.orm.filter_preset import FilterPreset as OrmFilterPreset

SSH_PATH = "/file/path/to/your/ssh-private-key.txt"
PRESET_ID = "00000000-0000-0000-0000-000000000000"

user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

filters = user_client.get_filter_preset(preset_uuid=PRESET_ID).get_filter_preset_json()

filters_dict = filters.to_dict() 

print("\nFormatted Output:\n")
pprint(filters_dict)



# Import dependencies
from encord import EncordUserClient

from pprint import pprint

from encord.orm.filter_preset import FilterPreset as OrmFilterPreset

SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"
PRESET_ID = "00000000-0000-0000-0000-000000000000"

user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

filters = user_client.get_filter_preset(preset_uuid=PRESET_ID).get_filter_preset_json()

filters_dict = filters.to_dict() 

print("\nFormatted Output:\n")
pprint(filters_dict)



Formatted Output:

{'globalFilters': {'filters': [{'domain': 'item',
                                'enum': 'data_type',
                                'include': True,
                                'type': 'enum',
                                'values': ['IMAGE']}]},
 'localFilters': {'raw-filter-id': {'filters': []}}}

​
Add Filter Preset Contents to Collection

Adds all storage items that match the criteria specified by a filter preset to a Collection. 
# Import dependencies
from encord import EncordUserClient
from encord.orm.collection import Collection
from encord.orm.filter_preset import FilterPreset

# Define constants
SSH_PATH = "file-path-to-ssh-private-key"
COLLECTION_HASH = "unique-collection-id"

# Preset ID to add to the collection
PRESET_ID = "unique-preset-filter-id"  

# Initialize the user client using the SSH private key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Fetch the specific collection by hash
collection: Collection = user_client.get_collection(COLLECTION_HASH)

# Add preset storage items to the collection by preset ID
collection.add_preset_items(PRESET_ID)

print(f"Added preset {PRESET_ID} to collection {COLLECTION_HASH}.")



# Import dependencies
from encord import EncordUserClient
from encord.orm.collection import Collection
from encord.orm.filter_preset import FilterPreset

# Define constants
SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
COLLECTION_HASH = "9a423f8f-0d3d-48ee-9fd6-0b2b80d229e7"

# Preset Filter ID to add to the collection
PRESET_ID = "2eb7c0e2-bc4f-4583-991c-2acb7dec4a72"  

# Initialize the user client using the SSH private key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Fetch the specific collection by hash
collection: Collection = user_client.get_collection(COLLECTION_HASH)

# Add preset storage items to the collection by preset ID
collection.add_preset_items(PRESET_ID)

print(f"Added preset {PRESET_ID} to collection {COLLECTION_HASH}.")

​
Remove Filter Preset Contents from Collection

Removes all storage items that match the criteria specified by a filter preset from a Collection. 

# Import dependencies
from encord import EncordUserClient
from encord.orm.collection import Collection
from encord.orm.filter_preset import FilterPreset

# Define constants
SSH_PATH = "file-path-to-key-private-key"
COLLECTION_HASH = "collection-unique-id"

# Preset ID to remove contents from the collection
PRESET_ID = "preset-filter-unique-id"  

# Initialize the user client using the SSH private key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Fetch the specific collection by hash
collection: Collection = user_client.get_collection(COLLECTION_HASH)

# Remove preset storage items from the collection by preset ID
collection.remove_preset_items(PRESET_ID)

print(f"Removed preset {PRESET_ID} from collection {COLLECTION_HASH}.")


# Import dependencies
from encord import EncordUserClient
from encord.orm.collection import Collection
from encord.orm.filter_preset import FilterPreset

# Define constants
SSH_PATH = "/Users/chirs-encord/sdk-ssh-private-key.txt"
COLLECTION_HASH = "078c1568-d46b-4f64-adf5-e16e8473f25d"

# Preset ID to remove contents from the collection
PRESET_ID = "e57cbab1-3be4-4485-bdfe-5747796b7800"  

# Initialize the user client using the SSH private key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Fetch the specific collection by hash
collection: Collection = user_client.get_collection(COLLECTION_HASH)

# Remove preset storage items from the collection by preset ID
collection.remove_preset_items(PRESET_ID)

print(f"Removed preset {PRESET_ID} from collection {COLLECTION_HASH}.")

​
Collections

Collections are groups of data units you selected by filtering, sorting, inspecting, and analyzing the data units in Index.

​
List Collections

List all Collections in Index by name with their unique identifier. 
# Import dependencies
from encord import EncordUserClient

SSH_PATH = "file-path-to-your-ssh-private-key"


user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Get Collection

collections = user_client.list_collections()

# Print out the names of the Collections
for collection in collections:
    print(collection.name, collection.uuid)


# Import dependencies
from encord import EncordUserClient

SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"


user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Get Collection

collections = user_client.list_collections()

# Print out the names of the Collections
for collection in collections:
    print(collection.name, collection.uuid)

​
Create Collection

Create a Collection with a meaningful name and description in a Folder. 
# Import dependencies
from encord import EncordUserClient

SSH_PATH = "file-path-to-ssh-private-key"


user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Create a Collection

collection = user_client.create_collection(top_level_folder_uuid="root-folder-uuid", name="name-of-my-collection", description="A useful and meaningful description for the Collection.")

print(collection)

# Import dependencies
from encord import EncordUserClient

SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"


user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Create a Collection

collection = user_client.create_collection(top_level_folder_uuid="cdb9eacd-46a6-4982-8d0e-4cafbf248a38", name="SDK-Collection-01", description="A Collection created using the SDK.")

print(collection)

​
Add Storage Items to a Collection using UUIDs

Add storage items to a Collection using the UUID of the storage items. 
# Import dependencies
from encord import EncordUserClient
from encord.orm.collection import Collection
from encord.orm.filter_preset import FilterPreset

# Define constants
SSH_PATH = "file-path-to-ssh-private-key"
COLLECTION_HASH = "collection-unique-id"

# Initialize the user client using the SSH private key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Fetch the specific collection by hash
collection: Collection = user_client.get_collection(COLLECTION_HASH)

updates = [
    "<storage-item-id-01>",
    "<storage-item-id-02>",
    "<storage-item-id-03>"
]


collection.add_items(updates)

print(f"Added storage items {updates} to collection {COLLECTION_HASH}.")



# Import dependencies
from encord import EncordUserClient
from encord.orm.collection import Collection
from encord.orm.filter_preset import FilterPreset

# Define constants
SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
COLLECTION_HASH = "9a423f8f-0d3d-48ee-9fd6-0b2b80d229e7"

# Initialize the user client using the SSH private key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Fetch the specific collection by hash
collection: Collection = user_client.get_collection(COLLECTION_HASH)

updates = [
    "fd332087-3691-48b9-bb46-19c4cdcd6099",
    "62daaa33-195e-4faf-be5b-8335a239beb6",
    "c1dac9ff-cd92-4029-b178-e093f8a803af"
]


collection.add_items(updates)

print(f"Added storage items {updates} to collection {COLLECTION_HASH}.")

​
Remove Storage Items from a Collection using UUIDs

Remove storage items from a Collection using UUIDs. 
# Import dependencies
from encord import EncordUserClient
from encord.orm.collection import Collection
from encord.orm.filter_preset import FilterPreset

# Define constants
SSH_PATH = "file-path-to-ssh-private-key"
COLLECTION_HASH = "collection-unique-id"

# Initialize the user client using the SSH private key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Fetch the specific collection by hash
collection: Collection = user_client.get_collection(COLLECTION_HASH)

updates = [
    "<storage-item-id-01>",
    "<storage-item-id-02>",
    "<storage-item-id-03>"
]


collection.remove_items(updates)

print(f"Removed storage items {updates} from collection {COLLECTION_HASH}.")



# Import dependencies
from encord import EncordUserClient
from encord.orm.collection import Collection
from encord.orm.filter_preset import FilterPreset

# Define constants
SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
COLLECTION_HASH = "9a423f8f-0d3d-48ee-9fd6-0b2b80d229e7"

# Initialize the user client using the SSH private key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Fetch the specific collection by hash
collection: Collection = user_client.get_collection(COLLECTION_HASH)

updates = [
    "fd332087-3691-48b9-bb46-19c4cdcd6099",
    "62daaa33-195e-4faf-be5b-8335a239beb6",
    "c1dac9ff-cd92-4029-b178-e093f8a803af"
]


collection.remove_items(updates)

print(f"Removed storage items {updates} from collection {COLLECTION_HASH}.")

​
List all Storage Items in a Collection

Lists all storage items in a Collection 

# Import dependencies
from encord import EncordUserClient
from encord.orm.storage import StorageItemType
from encord.orm.collection import Collection
from encord.orm.filter_preset import FilterPreset

# Define constants
SSH_PATH = "file-path-to-ssh-private-key"
COLLECTION_HASH = "collection-unique-id"

# Initialize the user client using the SSH private key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Fetch the specific collection by hash
collection: Collection = user_client.get_collection(COLLECTION_HASH)

# Initialize an empty list to store items
items = []

# Iterate over storage items and append them to the list
for item in collection.list_items():
    items.append(item)
    print(f"UUID: {item.uuid}, Name: {item.name}, Type: {item.item_type}")



# Import dependencies
from encord import EncordUserClient
from encord.orm.storage import StorageItemType
from encord.orm.collection import Collection
from encord.orm.filter_preset import FilterPreset

# Define constants
SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
COLLECTION_HASH = "078c1568-d46b-4f64-adf5-e16e8473f25d"

# Initialize the user client using the SSH private key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
)

# Fetch the specific collection by hash
collection: Collection = user_client.get_collection(COLLECTION_HASH)

# Initialize an empty list to store items
items = []

# Iterate over storage items and append them to the list
for item in collection.list_items():
    items.append(item)
    print(f"UUID: {item.uuid}, Name: {item.name}, Type: {item.item_type}")