---
sidebar:
  hidden: true
title: roboto.domain.collections.collection
---
## Module Contents

### Collection

```python
class roboto.domain.collections.collection.Collection(
    record: roboto.domain.collections.record.CollectionRecord,
    roboto_client: Optional[roboto.http.RobotoClient] = None,
)
```

`from roboto import Collection`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/collections/collection.py#L41-L427)

A higher-level container for grouping datasets together. Collections can also be used to group files from several distinct datasets together.

**Parameters**

- **record** (`roboto.domain.collections.record.CollectionRecord`)
- **roboto_client** (`Optional[roboto.http.RobotoClient]`)

**Properties**

- **Collection.collection_id** (`str`)

- **Collection.created** (`datetime.datetime`)

- **Collection.created_by** (`str`)

- **Collection.custom_fields** (`dict[str, Any]`): Custom-field values defined on Collections in this org.

  Every `Ready` [`CustomField`](/reference/python-sdk/roboto/domain/custom_fields/custom_field#roboto.domain.custom_fields.custom_field.CustomField) defined for `(org_id, Collection)` appears as a key. Values that have not been set on this collection surface as `None` rather than being absent. Empty when no custom fields are defined for the org.

  A [`Timestamp`](/reference/python-sdk/roboto/domain/custom_fields/record#roboto.domain.custom_fields.record.CustomFieldType.Timestamp) value is returned as an ISO 8601 string.

- **Collection.datasets** (`list[str]`)

- **Collection.description** (`str | None`): Return type: `Optional[str]`

- **Collection.events** (`list[str]`)

- **Collection.files** (`list[str]`)

- **Collection.name** (`str | None`): Return type: `Optional[str]`

- **Collection.record** (`roboto.domain.collections.record.CollectionRecord`)

- **Collection.resource_count** (`int`): Number of resources this collection holds.

  Read from the collection record rather than from `resources`, so it is available in every content mode, including summary-only loads where the member list is empty. Counts every membership reference, including references to resources that have since been deleted.

- **Collection.sessions** (`list[str]`)

- **Collection.updated** (`datetime.datetime`)

- **Collection.updated_by** (`str`)

#### Collection.add_dataset()

```python
def add_dataset(dataset_id: str) -> Collection
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/collections/collection.py#L289-L292)

**Parameters**

- **dataset_id** (`str`)

**Returns**

- `Collection`

#### Collection.add_event()

```python
def add_event(event_id: str) -> Collection
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/collections/collection.py#L294-L297)

**Parameters**

- **event_id** (`str`)

**Returns**

- `Collection`

#### Collection.add_file()

```python
def add_file(file_id: str) -> Collection
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/collections/collection.py#L299-L302)

**Parameters**

- **file_id** (`str`)

**Returns**

- `Collection`

#### Collection.add_session()

```python
def add_session(session_id: str) -> Collection
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/collections/collection.py#L304-L307)

**Parameters**

- **session_id** (`str`)

**Returns**

- `Collection`

#### Collection.changes()

```python
def changes(
    from_version: Optional[int] = None,
    to_version: Optional[int] = None,
) -> collections.abc.Generator[roboto.domain.collections.record.CollectionChangeRecord, None, None]
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/collections/collection.py#L309-L332)

Yield this collection's revision history, oldest change first.

Version 0 is a real collection version, so `0` is a bound like any other: `from_version=0` starts at the beginning, and `to_version=0` selects the empty range. Omit a bound to leave that end open.

**Parameters**

- **from_version** (`Optional[int]`)
- **to_version** (`Optional[int]`)

**Returns**

- `collections.abc.Generator[roboto.domain.collections.record.CollectionChangeRecord, None, None]`

#### Collection.clear_custom_field()

```python
def clear_custom_field(name: str) -> Collection
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/collections/collection.py#L410-L412)

Clear a single custom-field value on this collection to `None`.

**Parameters**

- **name** (`str`)

**Returns**

- `Collection`

#### Collection.clear_custom_fields()

```python
def clear_custom_fields(names: collections.abc.Sequence[str]) -> Collection
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/collections/collection.py#L425-L427)

Clear multiple custom-field values on this collection to `None`.

**Parameters**

- **names** (`collections.abc.Sequence[str]`)

**Returns**

- `Collection`

#### Collection.create()

```python
@classmethod
def create(
    description: Optional[str] = None,
    name: Optional[str] = None,
    resource_type: roboto.domain.collections.record.CollectionResourceType = CollectionResourceType.File,
    resources: Optional[list[roboto.domain.collections.record.CollectionResourceRef]] = None,
    dataset_ids: Optional[collections.abc.Collection[str]] = None,
    event_ids: Optional[collections.abc.Collection[str]] = None,
    file_ids: Optional[collections.abc.Collection[str]] = None,
    session_ids: Optional[collections.abc.Collection[str]] = None,
    tags: Optional[list[str]] = None,
    custom_fields: Optional[dict[str, Any]] = None,
    roboto_client: Optional[roboto.http.RobotoClient] = None,
    caller_org_id: Optional[str] = None,
) -> Collection
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/collections/collection.py#L70-L136)

**Parameters**

- **description** (`Optional[str]`)
- **name** (`Optional[str]`)
- **resource_type** (`roboto.domain.collections.record.CollectionResourceType`)
- **resources** (`Optional[list[roboto.domain.collections.record.CollectionResourceRef]]`)
- **dataset_ids** (`Optional[collections.abc.Collection[str]]`)
- **event_ids** (`Optional[collections.abc.Collection[str]]`)
- **file_ids** (`Optional[collections.abc.Collection[str]]`)
- **session_ids** (`Optional[collections.abc.Collection[str]]`)
- **tags** (`Optional[list[str]]`)
- **custom_fields** (`Optional[dict[str, Any]]`)
- **roboto_client** (`Optional[roboto.http.RobotoClient]`)
- **caller_org_id** (`Optional[str]`)

**Returns**

- `Collection`

#### Collection.delete()

```python
def delete()
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/collections/collection.py#L334-L335)

#### Collection.edit_access()

```python
def edit_access(edit: roboto.auth.EditAccessRequest) -> roboto.auth.GetAccessResponse
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/collections/collection.py#L340-L343)

**Parameters**

- **edit** (`roboto.auth.EditAccessRequest`)

**Returns**

- `roboto.auth.GetAccessResponse`

#### Collection.from_id()

```python
@classmethod
def from_id(
    collection_id: str,
    version: Optional[int] = None,
    content_mode: roboto.domain.collections.record.CollectionContentMode = CollectionContentMode.Full,
    roboto_client: Optional[roboto.http.RobotoClient] = None,
) -> Collection
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/collections/collection.py#L51-L67)

**Parameters**

- **collection_id** (`str`)
- **version** (`Optional[int]`)
- **content_mode** (`roboto.domain.collections.record.CollectionContentMode`)
- **roboto_client** (`Optional[roboto.http.RobotoClient]`)

**Returns**

- `Collection`

#### Collection.get_access()

```python
def get_access() -> roboto.auth.GetAccessResponse
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/collections/collection.py#L337-L338)

**Returns**

- `roboto.auth.GetAccessResponse`

#### Collection.list_all()

```python
@classmethod
def list_all(
    roboto_client: Optional[roboto.http.RobotoClient] = None,
    owner_org_id: Optional[str] = None,
    content_mode: roboto.domain.collections.record.CollectionContentMode = CollectionContentMode.SummaryOnly,
    sort_by: Optional[str] = None,
    sort_direction: Optional[roboto.query.SortDirection] = None,
) -> collections.abc.Generator[Collection, None, None]
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/collections/collection.py#L139-L171)

**Parameters**

- **roboto_client** (`Optional[roboto.http.RobotoClient]`)
- **owner_org_id** (`Optional[str]`)
- **content_mode** (`roboto.domain.collections.record.CollectionContentMode`)
- **sort_by** (`Optional[str]`)
- **sort_direction** (`Optional[roboto.query.SortDirection]`)

**Returns**

- `collections.abc.Generator[Collection, None, None]`

#### Collection.remove_dataset()

```python
def remove_dataset(dataset_id: str) -> Collection
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/collections/collection.py#L345-L350)

**Parameters**

- **dataset_id** (`str`)

**Returns**

- `Collection`

#### Collection.remove_event()

```python
def remove_event(event_id: str) -> Collection
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/collections/collection.py#L357-L360)

**Parameters**

- **event_id** (`str`)

**Returns**

- `Collection`

#### Collection.remove_file()

```python
def remove_file(file_id: str) -> Collection
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/collections/collection.py#L352-L355)

**Parameters**

- **file_id** (`str`)

**Returns**

- `Collection`

#### Collection.remove_session()

```python
def remove_session(session_id: str) -> Collection
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/collections/collection.py#L362-L367)

**Parameters**

- **session_id** (`str`)

**Returns**

- `Collection`

#### Collection.set_custom_field()

```python
def set_custom_field(name: str, value: Any) -> Collection
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/collections/collection.py#L398-L407)

Set a single custom-field value on this collection.

`name` must be the name of a [`Ready`](/reference/python-sdk/roboto/domain/custom_fields/record#roboto.domain.custom_fields.record.CustomFieldStatus.Ready) custom field for this collection's org and the [`Collection`](/reference/python-sdk/roboto/domain/custom_fields/record#roboto.domain.custom_fields.record.TargetEntityType.Collection) entity type; `value` must satisfy the field's declared type.

**Parameters**

- **name** (`str`)
- **value** (`Any`)

**Returns**

- `Collection`

#### Collection.set_custom_fields()

```python
def set_custom_fields(fields: dict[str, Any]) -> Collection
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/collections/collection.py#L415-L422)

Set or overwrite multiple custom-field values on this collection.

Each key must name a Ready custom field for this collection's org and the [`Collection`](/reference/python-sdk/roboto/domain/custom_fields/record#roboto.domain.custom_fields.record.TargetEntityType.Collection) entity type; each value must satisfy the field's declared type.

**Parameters**

- **fields** (`dict[str, Any]`)

**Returns**

- `Collection`

#### Collection.update()

```python
def update(
    add_resources: Union[list[roboto.domain.collections.record.CollectionResourceRef], roboto.sentinels.NotSetType] = NotSet,
    add_tags: Union[list[str], roboto.sentinels.NotSetType] = NotSet,
    description: Optional[Union[roboto.sentinels.NotSetType, str]] = NotSet,
    name: Optional[Union[roboto.sentinels.NotSetType, str]] = NotSet,
    remove_resources: Union[list[roboto.domain.collections.record.CollectionResourceRef], roboto.sentinels.NotSetType] = NotSet,
    remove_tags: Union[list[str], roboto.sentinels.NotSetType] = NotSet,
    custom_fields_changeset: Optional[roboto.updates.CustomFieldChangeset] = None,
) -> Collection
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/collections/collection.py#L369-L395)

**Parameters**

- **add_resources** (`Union[list[roboto.domain.collections.record.CollectionResourceRef], roboto.sentinels.NotSetType]`)
- **add_tags** (`Union[list[str], roboto.sentinels.NotSetType]`)
- **description** (`Optional[Union[roboto.sentinels.NotSetType, str]]`)
- **name** (`Optional[Union[roboto.sentinels.NotSetType, str]]`)
- **remove_resources** (`Union[list[roboto.domain.collections.record.CollectionResourceRef], roboto.sentinels.NotSetType]`)
- **remove_tags** (`Union[list[str], roboto.sentinels.NotSetType]`)
- **custom_fields_changeset** (`Optional[roboto.updates.CustomFieldChangeset]`)

**Returns**

- `Collection`