EntitiesCollectionApi¶

class EntitiesCollectionApi(api)[source]¶

Bases: UpdateableModule, RemoveableModuleApi

API for working with entities collections.

Parameters:

api¶: Api object to use for API connection.

Methods

`add_items`	Add items to Entities Collection.
`convert_info_to_json`	Convert information about an entity to a dictionary.
`create`	Creates Entities Collections.
`exists`	Checks if an entity with the given parent_id and name exists
`get_free_name`	Generates a free name for an entity with the given parent_id and name.
`get_info_by_ai_search_key`	Get information about Entities Collection of type `AI_SEARCH` with given AI search key.
`get_info_by_id`	Get information about Entities Collection with given ID.
`get_info_by_name`	Get information about an entity by its name from the Supervisely server.
`get_items`	Get items from Entities Collection.
`get_list`	Get list of information about Entities Collection for the given project.
`get_list_all_pages`	Get list of all or limited quantity entities from the Supervisely server.
`get_list_all_pages_generator`	This generator function retrieves a list of all or a limited quantity of entities from the Supervisely server, yielding batches of entities as they are retrieved
`get_list_idx_page_async`	Get the list of items for a given page number.
`get_list_page_generator_async`	Yields list of images in dataset asynchronously page by page.
`info_sequence`	Sequence of fields that are returned by the API to represent EntitiesCollectionInfo.
`info_tuple_name`	Name of the tuple that represents EntitiesCollectionInfo.
`remove`	Remove Entites Collection with the specified ID from the Supervisely server.
`remove_batch`	Remove entities with given IDs from the Supervisely server.
`remove_items`	Remove items from Entities Collection.
`update`	Update an entity with the specified ID.

Attributes

`MAX_WAIT_ATTEMPTS`	Maximum number of attempts that will be made to wait for a certain condition to be met.
`WAIT_ATTEMPT_TIMEOUT_SEC`	Number of seconds for intervals between attempts.

InfoType¶: alias of EntitiesCollectionInfo

classmethod convert_info_to_json(info)¶

Convert information about an entity to a dictionary.

Parameters:

info : NamedTuple¶: Information about the entity.

Returns:

Dictionary with information about the entity.

Return type:

dict

static info_sequence()[source]¶

Sequence of fields that are returned by the API to represent EntitiesCollectionInfo.

Usage Example:

EntitiesCollectionInfo(
    id=2,
    name='Enitites Collections #1',
    team_id=4,
    project_id=58,
    description='',
    created_at='2020-04-08T15:10:12.618Z',
    updated_at='2020-04-08T15:10:19.833Z',
)

static info_tuple_name()[source]¶

Name of the tuple that represents EntitiesCollectionInfo.

Returns:: NamedTuple name.
Return type:: str

add_items(id, items)[source]¶

Add items to Entities Collection.

Parameters:

id : int¶: Entities Collection ID in Supervisely.
items¶: List of items to add to the collection. Could be a list of entity IDs (int) or CollectionItem objects.

Returns:

List of added items with their IDs and creation timestamps.

Return type:

List[Dict[str, int]]

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly
from supervisely.api.entities_collection_api import CollectionItem

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

collection_id = 2
item_ids = [525, 526]
items = [CollectionItem(entity_id=item_id) for item_id in item_ids]
new_items = api.entities_collection.add_items(collection_id, items)
print(new_items)
# Output: [
#   {"id": 1, "entityId": 525, 'createdAt': '2025-04-10T08:49:41.852Z'},
#   {"id": 2, "entityId": 526, 'createdAt': '2025-04-10T08:49:41.852Z'}
]

create(project_id, name, description=None, type='default', ai_search_key=None, change_name_if_conflict=False)[source]¶

Creates Entities Collections.

Parameters:

project_id : int¶: Project ID in Supervisely.
name : str¶: Entities Collection name in Supervisely.
description : str¶: Entities Collection description.
type : str¶: Type of the collection. Defaults to “default”.
ai_search_key : Optional[str]¶: AI search key for the collection. Defaults to None.
change_name_if_conflict : bool¶: Checks if given name already exists and adds suffix to the end of the name. Defaults to False.

Returns:

Information about new Entities Collection

Return type:

EntitiesCollectionInfo

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

project_id = 123
name = "Chihuahuas"
description = "Collection of Chihuahuas"
type = CollectionType.AI_SEARCH
ai_search_key = "0ed6a5256433bbe32822949d563d476a"

new_collection = api.entities_collection.create(project_id, name, description, type, ai_search_key)
print(new_collection)

exists(parent_id, name)¶

Checks if an entity with the given parent_id and name exists

Parameters:

parent_id : int¶: ID of the parent entity.
name : str¶: Name of the entity.

Returns:

Returns True if entity exists, and False if not

Return type:

bool

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

name = "IMG_0315.jpeg"
dataset_id = 55832
exists = api.image.exists(dataset_id, name)
print(exists) # True

get_free_name(parent_id, name)¶

Generates a free name for an entity with the given parent_id and name. Adds an increasing suffix to original name until a unique name is found.

Parameters:

parent_id : int¶: ID of the parent entity.
name : str¶: Name of the entity.

Returns:

Returns free name.

Return type:

str

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

name = "IMG_0315.jpeg"
dataset_id = 55832
free_name = api.image.get_free_name(dataset_id, name)
print(free_name) # IMG_0315_001.jpeg

get_info_by_ai_search_key(project_id, ai_search_key)[source]¶

Get information about Entities Collection of type AI_SEARCH with given AI search key.

Parameters:

project_id : int¶: Project ID in Supervisely.
ai_search_key : str¶: AI search key for the collection.

Returns:

Information about Entities Collection.

Return type:

EntitiesCollectionInfo

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

project_id = 123
ai_search_key = "0ed6a5256433bbe32822949d563d476a"

# Get collection by AI search key
collection = api.entities_collection.get_info_by_ai_search_key(project_id, ai_search_key)

get_info_by_id(id, with_meta=False)[source]¶

Get information about Entities Collection with given ID.

Parameters:

id : int¶: Entities Collection ID in Supervisely.
with_meta : bool, optional¶: If True, includes meta information in the response. Defaults to False.

Returns:

Information about Entities Collection.

Return type:

EntitiesCollectionInfo

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

collection = api.entities_collection.get_info_by_id(2)
print(collection)
# Output:
# {
#     "id": 1,
#     "teamId": 1,
#     "projectId": 1,
#     "name": "ds",
#     "description": "",
#     "createdAt": "2018-08-21T14:25:56.140Z",
#     "updatedAt": "2018-08-21T14:25:56.140Z"
# }

get_info_by_name(parent_id, name, fields=[])¶

Get information about an entity by its name from the Supervisely server.

Parameters:

parent_id : int¶: ID of the parent entity.
name : str¶: Name of the entity for which the information is being retrieved.
fields : List[str]¶: The list of api fields which will be returned with the response.

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

dataset_id = 55832
name = "IMG_0315.jpeg"
info = api.image.get_info_by_name(dataset_id, name)
print(info)
# Output: ImageInfo(id=19369643, name='IMG_0315.jpeg', ...)

get_items(collection_id, collection_type, project_id=None, ai_search_threshold=None, ai_search_threshold_direction='above')[source]¶

Get items from Entities Collection.

Parameters:

collection_id : int¶: Entities Collection ID in Supervisely.
collection_type¶: Type of the collection. Can be AI_SEARCH or DEFAULT.
project_id : int, optional¶: Project ID in Supervisely.
ai_search_threshold : float, optional¶: AI search threshold for filtering items. Optional, defaults to None.
ai_search_threshold_direction : str¶: Direction for the AI search threshold. Optional, defaults to ‘above’.

Returns:

List of ImageInfo objects.

Return type:

List[ImageInfo]

Raises:

RuntimeError – If Entities Collection with given ID not found.

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

collection_id = 2
project_id = 4
item_ids = api.entities_collection.get_items(collection_id, project_id)
print(item_ids)

get_list(project_id, filters=None, with_meta=False, collection_type='default')[source]¶

Get list of information about Entities Collection for the given project.

Parameters:

project_id : int, optional¶

Project ID in Supervisely.

filters : List[Dict[str, str]], optional¶

List of filters to apply to the request. Optional, defaults to None.

with_meta : bool, optional¶

If True, includes meta information in the response. Defaults to False.

collection_type='default'¶

Type of the collection. Defaults to DEFAULT.

Available types are:

DEFAULT
AI_SEARCH
ALL

Returns:

List of information about Entities Collections.

Return type:

List[EntitiesCollectionInfo]

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

collections = api.entities_collection.get_list(4)

get_list_all_pages(method, data, progress_cb=None, convert_json_info_cb=None, limit=None, return_first_response=False)¶

Get list of all or limited quantity entities from the Supervisely server.

Parameters:

method : str¶: Request method name
data : dict¶: Dictionary with request body info
progress_cb : Progress, optional¶: Function for tracking download progress.
convert_json_info_cb : Callable, optional¶: Function for convert json info
limit : int, optional¶: Number of entity to retrieve
return_first_response : bool, optional¶: Specify if return first response

Returns:

List of entities.

Return type:

List[dict]

get_list_all_pages_generator(method, data, progress_cb=None, convert_json_info_cb=None, limit=None, return_first_response=False)¶

This generator function retrieves a list of all or a limited quantity of entities from the Supervisely server, yielding batches of entities as they are retrieved

Parameters:

method : str¶: Request method name
data : dict¶: Dictionary with request body info
progress_cb : Progress, optional¶: Function for tracking download progress.
convert_json_info_cb : Callable, optional¶: Function for convert json info
limit : int, optional¶: Number of entity to retrieve
return_first_response : bool, optional¶: Specify if return first response

async get_list_idx_page_async(method, data)¶

Get the list of items for a given page number. Page number is specified in the data dictionary.

Parameters:

method : str¶: Method to call for listing items.
data : dict¶: Data to pass to the API method.

Returns:

List of items.

Return type:

Tuple[int, List[NamedTuple]]

async get_list_page_generator_async(method, data, pages_count=None, semaphore=None)¶

Yields list of images in dataset asynchronously page by page.

Parameters:

method : str¶: Method to call for listing items.
data : dict¶: Data to pass to the API method.
pages_count : int, optional¶: Preferred number of pages to retrieve if used with a per_page limit. Will be automatically adjusted if the pagesCount differs from the requested number.
semaphore=None¶: Semaphore for limiting the number of simultaneous requests.

Returns:

List of images in dataset.

Return type:

AsyncGenerator[List[ImageInfo]]

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

method = 'images.list'
data = {'datasetId': 123456}

loop = sly.utils.get_or_create_event_loop()
images = loop.run_until_complete(api.image.get_list_generator_async(method, data))

remove(id, force=False)[source]¶

Remove Entites Collection with the specified ID from the Supervisely server.

If force is set to True, the collection will be removed permanently. If force is set to False, the collection will be disabled instead of removed.

Parameters:

id : int¶: Entites Collection ID in Supervisely
force : bool¶: If True, the collection will be removed permanently. Defaults to False.

Returns:

None

remove_batch(ids, progress_cb=None)¶

Remove entities with given IDs from the Supervisely server.

Parameters:

ids : List[int]¶: IDs of entities in Supervisely.
progress_cb : Callable¶: Function for control remove progress.

Returns:

None

Return type:

None

remove_items(id, items)[source]¶

Remove items from Entities Collection.

Parameters:

id : int¶: Entities Collection ID in Supervisely.
items : List[int]¶: List of entity IDs in Supervisely, e.g. image IDs etc.

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

collection_id = 2
item_ids = [525, 526, 527]
removed_items = api.entities_collection.remove_items(collection_id, item_ids)
# print(removed_items)
# Output: [{"id": 1, "entityId": 525}, {"id": 2, "entityId": 526}]

update(id, name=None, description=None)¶

Update an entity with the specified ID.

Parameters:

id : int¶: ID of the entity to update.
name : str, optional¶: New name of the entity.
description : str, optional¶: New description of the entity.

Returns:

Entity with updated information.

Return type:

dict