Dataset Collection¶

Contained within this file are experimental interfaces for working with the Synapse Python Client. Unless otherwise noted these interfaces are subject to change at any time. Use at your own risk.

API reference¶

synapseclient.models.DatasetCollection `dataclass` ¶

Bases: DatasetCollectionSynchronousProtocol, AccessControllable, ViewBase, ViewStoreMixin, DeleteMixin, ColumnMixin, GetMixin, QueryMixin, ViewUpdateMixin, ViewSnapshotMixin

A DatasetCollection object represents the metadata of a Synapse Dataset Collection. https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/table/DatasetCollection.html

A Dataset Collection is a type of view defined by a flat list of Datasets.

ATTRIBUTE	DESCRIPTION
`id`	The unique immutable ID for this dataset collection. A new ID will be generated for new DatasetCollections. Once issued, this ID is guaranteed to never change or be re-issued TYPE: `Optional[str]`
`name`	The name of this dataset collection. Must be 256 characters or less. Names may only contain: letters, numbers, spaces, underscores, hyphens, periods, plus signs, apostrophes, and parentheses TYPE: `Optional[str]`
`description`	The description of the dataset collection. Must be 1000 characters or less. TYPE: `Optional[str]`
`etag`	Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle concurrent updates. Since the E-Tag changes every time an entity is updated it is used to detect when a client's current representation of an entity is out-of-date. TYPE: `Optional[str]`
`created_on`	The date this dataset collection was created. TYPE: `Optional[str]`
`modified_on`	The date this dataset collection was last modified. In YYYY-MM-DD-Thh:mm:ss.sssZ format TYPE: `Optional[str]`
`created_by`	The ID of the user that created this dataset collection. TYPE: `Optional[str]`
`modified_by`	The ID of the user that last modified this dataset collection. TYPE: `Optional[str]`
`parent_id`	The ID of the Entity that is the parent of this dataset collection. TYPE: `Optional[str]`
`columns`	The columns of this dataset collection. This is an ordered dictionary where the key is the name of the column and the value is the Column object. When creating a new instance of a DatasetCollection object you may pass any of the following types as the `columns` argument: A list of Column objects A dictionary where the key is the name of the column and the value is the Column object An OrderedDict where the key is the name of the column and the value is the Column object The order of the columns will be the order they are stored in Synapse. If you need to reorder the columns the recommended approach is to use the `.reorder_column()` method. Additionally, you may add, and delete columns using the `.add_column()`, and `.delete_column()` methods on your dataset collection class instance. You may modify the attributes of the Column object to change the column type, name, or other attributes. For example, suppose you'd like to change a column from a INTEGER to a DOUBLE. You can do so by changing the column type attribute of the Column object. The next time you store the dataset collection the column will be updated in Synapse with the new type. `from synapseclient import Synapse from synapseclient.models import DatasetCollection, Column, ColumnType syn = Synapse() syn.login() collection = DatasetCollection(id="syn1234").get() collection.columns["my_column"].column_type = ColumnType.DOUBLE collection.store()` Note that the keys in this dictionary should match the column names as they are in Synapse. However, know that the name attribute of the Column object is used for all interactions with the Synapse API. The OrderedDict key is purely for the usage of this interface. For example, if you wish to rename a column you may do so by changing the name attribute of the Column object. The key in the OrderedDict does not need to be changed. The next time you store the dataset collection the column will be updated in Synapse with the new name and the key in the OrderedDict will be updated. TYPE: `Optional[Union[List[Column], OrderedDict[str, Column], Dict[str, Column]]]`
`version_number`	The version number issued to this version on the object. TYPE: `Optional[int]`
`version_label`	The version label for this dataset collection. TYPE: `Optional[str]`
`version_comment`	The version comment for this dataset collection. TYPE: `Optional[str]`
`is_latest_version`	If this is the latest version of the object. TYPE: `Optional[bool]`
`is_search_enabled`	When creating or updating a dataset collection or view specifies if full text search should be enabled. Note that enabling full text search might slow down the indexing of the dataset collection or view. TYPE: `Optional[bool]`
`items`	The flat list of datasets that define this collection. This is effectively a list of the rows that are in/will be in the collection after it is stored. The only way to add or remove rows is to add or remove items from this list. TYPE: `Optional[List[EntityRef]]`
`activity`	The Activity model represents the main record of Provenance in Synapse. It is analogous to the Activity defined in the W3C Specification on Provenance. TYPE: `Optional[Activity]`
`annotations`	Additional metadata associated with the dataset collection. The key is the name of your desired annotations. The value is an object containing a list of values (use empty list to represent no values for key) and the value type associated with all values in the list. TYPE: `Optional[Dict[str, Union[List[str], List[bool], List[float], List[int], List[date], List[datetime]]]]`
`include_default_columns`	When creating a dataset collection or view, specifies if default columns should be included. Default columns are columns that are automatically added to the dataset collection or view. These columns are managed by Synapse and cannot be modified. If you attempt to create a column with the same name as a default column, you will receive a warning when you store the dataset collection. `include_default_columns` is only used if this is the first time that the view is being stored. If you are updating an existing view this attribute will be ignored. If you want to add all default columns back to your view then you may use this code snippet to accomplish this: `import asyncio from synapseclient import Synapse from synapseclient.models import DatasetCollection syn = Synapse() syn.login() async def main(): view = await DatasetCollection(id="syn1234").get_async() await view._append_default_columns() await view.store_async() asyncio.run(main())` The column you are overriding will not behave the same as a default column. For example, suppose you create a column called `id` on a DatasetCollection. When using a default column, the `id` stores the Synapse ID of each of the entities included in the scope of the view. If you override the `id` column with a new column, the `id` column will no longer store the Synapse ID of the entities in the view. Instead, it will store the values you provide when you store the dataset collection. It will be stored as an annotation on the entity for the row you are modifying. TYPE: `Optional[bool]`

Create a new Dataset Collection from a list of Datasets.

from synapseclient import Synapse
from synapseclient.models import DatasetCollection, Dataset

syn = Synapse()
syn.login()

my_datasets = [Dataset(id="syn1234"), Dataset(id="syn1235"), Dataset(id="syn1236")]
my_collection = DatasetCollection(parent_id="syn987", name="my-new-collection", items=my_datasets)
my_collection.store()

Add Datasets to an existing Dataset Collection.

from synapseclient import Synapse
from synapseclient.models import DatasetCollection, Dataset

syn = Synapse()
syn.login()

my_collection = DatasetCollection(id="syn1234").get()

# Add a dataset to the collection
my_collection.add_item(Dataset(id="syn1235"))
my_collection.store()

Remove Datasets from a Dataset Collection.

from synapseclient import Synapse
from synapseclient.models import DatasetCollection, Dataset

syn = Synapse()
syn.login()

my_collection = DatasetCollection(id="syn1234").get()

# Remove a dataset from the collection
my_collection.remove_item(Dataset(id="syn1235"))
my_collection.store()

Query data from a Dataset Collection.

from synapseclient import Synapse
from synapseclient.models import DatasetCollection

syn = Synapse()
syn.login()

my_collection = DatasetCollection(id="syn1234").get()
row = my_collection.query(query="SELECT * FROM syn1234 WHERE id = 'syn1235'")
print(row)

Add a custom column to a Dataset Collection.

from synapseclient import Synapse
from synapseclient.models import DatasetCollection, Column, ColumnType

syn = Synapse()
syn.login()

my_collection = DatasetCollection(id="syn1234").get()
my_collection.add_column(Column(name="my_annotation", column_type=ColumnType.STRING))
my_collection.store()

Update custom column values in a Dataset Collection.

from synapseclient import Synapse
from synapseclient.models import DatasetCollection

syn = Synapse()
syn.login()

my_collection = DatasetCollection(id="syn1234").get()
# my_annotation must already exist in the dataset collection as a custom column
modified_data = pd.DataFrame(
    {"id": ["syn1234"], "my_annotation": ["good data"]}
)
my_collection.update_rows(values=modified_data, primary_keys=["id"], dry_run=False)

Save a snapshot of a Dataset Collection.

from synapseclient import Synapse
from synapseclient.models import DatasetCollection

syn = Synapse()
syn.login()

my_collection = DatasetCollection(id="syn1234").get()
my_collection.snapshot(comment="My first snapshot", label="My first snapshot")

Deleting a Dataset Collection.

from synapseclient import Synapse
from synapseclient.models import DatasetCollection

syn = Synapse()
syn.login()

DatasetCollection(id="syn4567").delete()

Source code in synapseclient/models/dataset.py

@dataclass
@async_to_sync
class DatasetCollection(
    DatasetCollectionSynchronousProtocol,
    AccessControllable,
    ViewBase,
    ViewStoreMixin,
    DeleteMixin,
    ColumnMixin,
    GetMixin,
    QueryMixin,
    ViewUpdateMixin,
    ViewSnapshotMixin,
):
    """A `DatasetCollection` object represents the metadata of a Synapse Dataset Collection.
    <https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/table/DatasetCollection.html>

    A Dataset Collection is a type of view defined by a flat list of Datasets.

    Attributes:
        id: The unique immutable ID for this dataset collection. A new ID will be generated for new
            DatasetCollections. Once issued, this ID is guaranteed to never change or be re-issued
        name: The name of this dataset collection. Must be 256 characters or less. Names may only
            contain: letters, numbers, spaces, underscores, hyphens, periods, plus
            signs, apostrophes, and parentheses
        description: The description of the dataset collection. Must be 1000 characters or less.
        etag: Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle
            concurrent updates. Since the E-Tag changes every time an entity is updated
            it is used to detect when a client's current representation of an entity is
            out-of-date.
        created_on: The date this dataset collection was created.
        modified_on: The date this dataset collection was last modified.
            In YYYY-MM-DD-Thh:mm:ss.sssZ format
        created_by: The ID of the user that created this dataset collection.
        modified_by: The ID of the user that last modified this dataset collection.
        parent_id: The ID of the Entity that is the parent of this dataset collection.
        columns: The columns of this dataset collection. This is an ordered dictionary where the key is the
            name of the column and the value is the Column object. When creating a new instance
            of a DatasetCollection object you may pass any of the following types as the `columns` argument:

            - A list of Column objects
            - A dictionary where the key is the name of the column and the value is the Column object
            - An OrderedDict where the key is the name of the column and the value is the Column object

            The order of the columns will be the order they are stored in Synapse. If you need
            to reorder the columns the recommended approach is to use the `.reorder_column()`
            method. Additionally, you may add, and delete columns using the `.add_column()`,
            and `.delete_column()` methods on your dataset collection class instance.

            You may modify the attributes of the Column object to change the column
            type, name, or other attributes. For example, suppose you'd like to change a
            column from a INTEGER to a DOUBLE. You can do so by changing the column type
            attribute of the Column object. The next time you store the dataset collection the column
            will be updated in Synapse with the new type.

            ```python
            from synapseclient import Synapse
            from synapseclient.models import DatasetCollection, Column, ColumnType

            syn = Synapse()
            syn.login()

            collection = DatasetCollection(id="syn1234").get()
            collection.columns["my_column"].column_type = ColumnType.DOUBLE
            collection.store()
            ```

            Note that the keys in this dictionary should match the column names as they are in
            Synapse. However, know that the name attribute of the Column object is used for
            all interactions with the Synapse API. The OrderedDict key is purely for the usage
            of this interface. For example, if you wish to rename a column you may do so by
            changing the name attribute of the Column object. The key in the OrderedDict does
            not need to be changed. The next time you store the dataset collection the column will be updated
            in Synapse with the new name and the key in the OrderedDict will be updated.
        version_number: The version number issued to this version on the object.
        version_label: The version label for this dataset collection.
        version_comment: The version comment for this dataset collection.
        is_latest_version: If this is the latest version of the object.
        is_search_enabled: When creating or updating a dataset collection or view specifies if full
            text search should be enabled. Note that enabling full text search might
            slow down the indexing of the dataset collection or view.
        items: The flat list of datasets that define this collection. This is effectively
            a list of the rows that are in/will be in the collection after it is stored. The only way to add
            or remove rows is to add or remove items from this list.
        activity: The Activity model represents the main record of Provenance in
            Synapse. It is analogous to the Activity defined in the
            [W3C Specification](https://www.w3.org/TR/prov-n/) on Provenance.
        annotations: Additional metadata associated with the dataset collection. The key is the name
            of your desired annotations. The value is an object containing a list of
            values (use empty list to represent no values for key) and the value type
            associated with all values in the list.
        include_default_columns: When creating a dataset collection or view, specifies if default
            columns should be included. Default columns are columns that are
            automatically added to the dataset collection or view. These columns are managed by
            Synapse and cannot be modified. If you attempt to create a column with the
            same name as a default column, you will receive a warning when you store the
            dataset collection.

            **`include_default_columns` is only used if this is the first time that the
            view is being stored.** If you are updating an existing view this attribute
            will be ignored. If you want to add all default columns back to your view
            then you may use this code snippet to accomplish this:

            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import DatasetCollection

            syn = Synapse()
            syn.login()

            async def main():
                view = await DatasetCollection(id="syn1234").get_async()
                await view._append_default_columns()
                await view.store_async()

            asyncio.run(main())
            ```

            The column you are overriding will not behave the same as a default column.
            For example, suppose you create a column called `id` on a DatasetCollection. When
            using a default column, the `id` stores the Synapse ID of each of the
            entities included in the scope of the view. If you override the `id` column
            with a new column, the `id` column will no longer store the Synapse ID of
            the entities in the view. Instead, it will store the values you provide when
            you store the dataset collection. It will be stored as an annotation on the entity for
            the row you are modifying.

    Example: Create a new Dataset Collection from a list of Datasets.
        &nbsp;

        ```python
        from synapseclient import Synapse
        from synapseclient.models import DatasetCollection, Dataset

        syn = Synapse()
        syn.login()

        my_datasets = [Dataset(id="syn1234"), Dataset(id="syn1235"), Dataset(id="syn1236")]
        my_collection = DatasetCollection(parent_id="syn987", name="my-new-collection", items=my_datasets)
        my_collection.store()
        ```

    Example: Add Datasets to an existing Dataset Collection.
        &nbsp;

        ```python
        from synapseclient import Synapse
        from synapseclient.models import DatasetCollection, Dataset

        syn = Synapse()
        syn.login()

        my_collection = DatasetCollection(id="syn1234").get()

        # Add a dataset to the collection
        my_collection.add_item(Dataset(id="syn1235"))
        my_collection.store()
        ```

    Example: Remove Datasets from a Dataset Collection.
        &nbsp;

        ```python
        from synapseclient import Synapse
        from synapseclient.models import DatasetCollection, Dataset

        syn = Synapse()
        syn.login()

        my_collection = DatasetCollection(id="syn1234").get()

        # Remove a dataset from the collection
        my_collection.remove_item(Dataset(id="syn1235"))
        my_collection.store()
        ```

    Example: Query data from a Dataset Collection.
        &nbsp;

        ```python
        from synapseclient import Synapse
        from synapseclient.models import DatasetCollection

        syn = Synapse()
        syn.login()

        my_collection = DatasetCollection(id="syn1234").get()
        row = my_collection.query(query="SELECT * FROM syn1234 WHERE id = 'syn1235'")
        print(row)
        ```

    Example: Add a custom column to a Dataset Collection.
        &nbsp;

        ```python
        from synapseclient import Synapse
        from synapseclient.models import DatasetCollection, Column, ColumnType

        syn = Synapse()
        syn.login()

        my_collection = DatasetCollection(id="syn1234").get()
        my_collection.add_column(Column(name="my_annotation", column_type=ColumnType.STRING))
        my_collection.store()
        ```

    Example: Update custom column values in a Dataset Collection.
        &nbsp;

        ```python
        from synapseclient import Synapse
        from synapseclient.models import DatasetCollection

        syn = Synapse()
        syn.login()

        my_collection = DatasetCollection(id="syn1234").get()
        # my_annotation must already exist in the dataset collection as a custom column
        modified_data = pd.DataFrame(
            {"id": ["syn1234"], "my_annotation": ["good data"]}
        )
        my_collection.update_rows(values=modified_data, primary_keys=["id"], dry_run=False)
        ```

    Example: Save a snapshot of a Dataset Collection.
        &nbsp;

        ```python
        from synapseclient import Synapse
        from synapseclient.models import DatasetCollection

        syn = Synapse()
        syn.login()

        my_collection = DatasetCollection(id="syn1234").get()
        my_collection.snapshot(comment="My first snapshot", label="My first snapshot")
        ```

    Example: Deleting a Dataset Collection.
        &nbsp;

        ```python
        from synapseclient import Synapse
        from synapseclient.models import DatasetCollection

        syn = Synapse()
        syn.login()

        DatasetCollection(id="syn4567").delete()
        ```
    """

    id: Optional[str] = None
    """The unique immutable ID for this dataset collection. A new ID will be generated for new
    dataset collections. Once issued, this ID is guaranteed to never change or be re-issued"""

    name: Optional[str] = None
    """The name of this dataset collection. Must be 256 characters or less. Names may only
    contain: letters, numbers, spaces, underscores, hyphens, periods, plus signs,
    apostrophes, and parentheses"""

    description: Optional[str] = None
    """The description of this entity. Must be 1000 characters or less."""

    etag: Optional[str] = field(default=None, compare=False)
    """
    Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle
    concurrent updates. Since the E-Tag changes every time an entity is updated it is
    used to detect when a client's current representation of an entity is out-of-date.
    """

    created_on: Optional[str] = field(default=None, compare=False)
    """The date this dataset collection was created."""

    modified_on: Optional[str] = field(default=None, compare=False)
    """The date this dataset collection was last modified. In YYYY-MM-DD-Thh:mm:ss.sssZ format"""

    created_by: Optional[str] = field(default=None, compare=False)
    """The ID of the user that created this dataset collection."""

    modified_by: Optional[str] = field(default=None, compare=False)
    """The ID of the user that last modified this dataset collection."""

    parent_id: Optional[str] = None
    """The ID of the Entity that is the parent of this dataset collection."""

    version_number: Optional[int] = field(default=None, compare=False)
    """The version number issued to this version on the object."""

    version_label: Optional[str] = None
    """The version label for this dataset collection."""

    version_comment: Optional[str] = None
    """The version comment for this dataset collection."""

    is_latest_version: Optional[bool] = field(default=None, compare=False)
    """If this is the latest version of the object."""

    is_search_enabled: Optional[bool] = None
    """When creating or updating a dataset collection or view specifies if full text search
    should be enabled. Note that enabling full text search might slow down the
    indexing of the dataset collection or view."""

    items: Optional[List["EntityRef"]] = field(default_factory=list, compare=False)
    """The flat list of EntityRefs referring to the datasets that define this collection."""

    columns: Optional[
        Union[List[Column], OrderedDict[str, Column], Dict[str, Column]]
    ] = field(default_factory=OrderedDict, compare=False)
    """
    The columns of this dataset collection. This is an ordered dictionary where the key is the
    name of the column and the value is the Column object. When creating a new instance
    of a DatasetCollection object you may pass any of the following types as the `columns` argument:

    - A list of Column objects
    - A dictionary where the key is the name of the column and the value is the Column object
    - An OrderedDict where the key is the name of the column and the value is the Column object

    The order of the columns will be the order they are stored in Synapse. If you need
    to reorder the columns the recommended approach is to use the `.reorder_column()`
    method. Additionally, you may add, and delete columns using the `.add_column()`,
    and `.delete_column()` methods on your dataset collection class instance.

    You may modify the attributes of the Column object to change the column
    type, name, or other attributes. For example, suppose you'd like to change a
    column from a INTEGER to a DOUBLE. You can do so by changing the column type
    attribute of the Column object. The next time you store the dataset collection the column
    will be updated in Synapse with the new type.

    ```python
    from synapseclient import Synapse
    from synapseclient.models import DatasetCollection, Column, ColumnType

    syn = Synapse()
    syn.login()

    collection = DatasetCollection(id="syn1234").get()
    collection.columns["my_column"].column_type = ColumnType.DOUBLE
    collection.store()
    ```

    Note that the keys in this dictionary should match the column names as they are in
    Synapse. However, know that the name attribute of the Column object is used for
    all interactions with the Synapse API. The OrderedDict key is purely for the usage
    of this interface. For example, if you wish to rename a column you may do so by
    changing the name attribute of the Column object. The key in the OrderedDict does
    not need to be changed. The next time you store the dataset collection the column will be updated
    in Synapse with the new name and the key in the OrderedDict will be updated.
    """

    _columns_to_delete: Optional[Dict[str, Column]] = field(default_factory=dict)
    """
    Columns to delete when the dataset collection is stored. The key in this dict is the ID of the
    column to delete. The value is the Column object that represents the column to
    delete.
    """

    activity: Optional[Activity] = field(default=None, compare=False)
    """The Activity model represents the main record of Provenance in Synapse.  It is
    analogous to the Activity defined in the
    [W3C Specification](https://www.w3.org/TR/prov-n/) on Provenance."""

    annotations: Optional[
        Dict[
            str,
            Union[
                List[str],
                List[bool],
                List[float],
                List[int],
                List[date],
                List[datetime],
            ],
        ]
    ] = field(default_factory=dict, compare=False)
    """Additional metadata associated with the dataset collection. The key is the name of your
    desired annotations. The value is an object containing"""

    _last_persistent_instance: Optional["DatasetCollection"] = field(
        default=None, repr=False, compare=False
    )
    """The last persistent instance of this object. This is used to determine if the
    object has been changed and needs to be updated in Synapse."""

    view_entity_type: ViewEntityType = ViewEntityType.DATASET_COLLECTION
    """The API model string for the type of view. This is used to determine the default columns that are
    added to the table. Must be defined as a `ViewEntityType` enum.
    """

    view_type_mask: ViewTypeMask = ViewTypeMask.DATASET_COLLECTION
    """The Bit Mask representing DatasetCollection type.
    As defined in the Synapse REST API:
    <https://rest-docs.synapse.org/rest/GET/column/tableview/defaults.html>"""

    def __post_init__(self):
        self.columns = self._convert_columns_to_ordered_dict(columns=self.columns)

    @property
    def has_changed(self) -> bool:
        """Determines if the object has been changed and needs to be updated in Synapse."""
        return (
            not self._last_persistent_instance
            or self._last_persistent_instance != self
            or (not self._last_persistent_instance.items and self.items)
            or self._last_persistent_instance.items != self.items
        )

    def _set_last_persistent_instance(self) -> None:
        """Stash the last time this object interacted with Synapse. This is used to
        determine if the object has been changed and needs to be updated in Synapse."""
        del self._last_persistent_instance
        self._last_persistent_instance = dataclasses.replace(self)
        self._last_persistent_instance.activity = (
            dataclasses.replace(self.activity) if self.activity else None
        )
        self._last_persistent_instance.columns = (
            OrderedDict(
                (key, dataclasses.replace(column))
                for key, column in self.columns.items()
            )
            if self.columns
            else OrderedDict()
        )
        self._last_persistent_instance.annotations = (
            deepcopy(self.annotations) if self.annotations else {}
        )
        self._last_persistent_instance.items = (
            [dataclasses.replace(item) for item in self.items] if self.items else []
        )

    def fill_from_dict(self, entity, set_annotations: bool = True) -> "Self":
        """
        Converts the data coming from the Synapse API into this datamodel.

        Arguments:
            synapse_table: The data coming from the Synapse API

        Returns:
            The DatasetCollection object instance.
        """
        self.id = entity.get("id", None)
        self.name = entity.get("name", None)
        self.description = entity.get("description", None)
        self.parent_id = entity.get("parentId", None)
        self.etag = entity.get("etag", None)
        self.created_on = entity.get("createdOn", None)
        self.created_by = entity.get("createdBy", None)
        self.modified_on = entity.get("modifiedOn", None)
        self.modified_by = entity.get("modifiedBy", None)
        self.version_number = entity.get("versionNumber", None)
        self.version_label = entity.get("versionLabel", None)
        self.version_comment = entity.get("versionComment", None)
        self.is_latest_version = entity.get("isLatestVersion", None)
        self.is_search_enabled = entity.get("isSearchEnabled", False)
        self.items = [
            EntityRef(id=item["entityId"], version=item["versionNumber"])
            for item in entity.get("items", [])
        ]
        if set_annotations:
            self.annotations = Annotations.from_dict(entity.get("annotations", {}))
        return self

    def to_synapse_request(self):
        """Converts the request to a request expected of the Synapse REST API."""

        entity = {
            "name": self.name,
            "description": self.description,
            "id": self.id,
            "etag": self.etag,
            "createdOn": self.created_on,
            "modifiedOn": self.modified_on,
            "createdBy": self.created_by,
            "modifiedBy": self.modified_by,
            "parentId": self.parent_id,
            "concreteType": concrete_types.DATASET_COLLECTION_ENTITY,
            "versionNumber": self.version_number,
            "versionLabel": self.version_label,
            "versionComment": self.version_comment,
            "isLatestVersion": self.is_latest_version,
            "columnIds": (
                [
                    column.id
                    for column in self._last_persistent_instance.columns.values()
                ]
                if self._last_persistent_instance
                and self._last_persistent_instance.columns
                else []
            ),
            "isSearchEnabled": self.is_search_enabled,
            "items": (
                [item.to_synapse_request() for item in self.items] if self.items else []
            ),
        }
        delete_none_keys(entity)
        result = {
            "entity": entity,
        }
        delete_none_keys(result)
        return result

    def add_item(
        self,
        item: Union["Dataset", "EntityRef"],
    ) -> None:
        """Adds a dataset to the dataset collection.
        Effect is not seen until the dataset collection is stored.

        Arguments:
            item: Dataset to add to the collection. Must be a Dataset.

        Raises:
            ValueError: If the item is not a Dataset

        Example: Add a Dataset to a Dataset Collection.
            &nbsp;

            ```python
            from synapseclient import Synapse
            from synapseclient.models import DatasetCollection, Dataset

            syn = Synapse()
            syn.login()

            my_collection = DatasetCollection(id="syn1234").get()
            my_collection.add_item(Dataset(id="syn1235"))
            my_collection.store()
            ```
        """
        if not isinstance(item, (Dataset, EntityRef)):
            raise ValueError(
                f"item must be a Dataset or EntityRef. {item} is a {type(item)}"
            )

        # EntityRef uses `version`, Dataset uses `version_number`
        version = item.version if isinstance(item, EntityRef) else item.version_number

        if not any(
            current_item.id == item.id and current_item.version == version
            for current_item in self.items
        ):
            self.items.append(EntityRef(id=item.id, version=version))

    def remove_item(
        self,
        item: Union["Dataset", "EntityRef"],
    ) -> None:
        """
        Removes an entity from the dataset collection. Must be a Dataset or EntityRef.
        Effect is not seen until the dataset collection is stored.
        Unless the version is specified, all entities with the same ID will be removed.

        Arguments:
            item: The Dataset to remove from the collection

        Returns:
            None

        Raises:
            ValueError: If the item is not a Dataset

        Example: Remove a Dataset from a Dataset Collection.
            &nbsp;

            ```python
            from synapseclient import Synapse
            from synapseclient.models import DatasetCollection, Dataset

            syn = Synapse()
            syn.login()

            my_collection = DatasetCollection(id="syn1234").get()
            my_collection.remove_item(Dataset(id="syn1235", version_number=1))
            my_collection.store()
            ```

        Example: Remove all versions of a Dataset from a Dataset Collection.
            &nbsp;

            ```python
            from synapseclient import Synapse
            from synapseclient.models import DatasetCollection, Dataset

            syn = Synapse()
            syn.login()

            my_collection = DatasetCollection(id="syn1234").get()
            my_collection.remove_item(Dataset(id="syn1235"))
            my_collection.store()
            ```
        """
        if not isinstance(item, (Dataset, EntityRef)):
            raise ValueError(
                f"item must be a Dataset or EntityRef. {item} is a {type(item)}"
            )

        version = item.version if isinstance(item, EntityRef) else item.version_number

        if version:
            self.items = [
                current_item
                for current_item in self.items
                if current_item != EntityRef(id=item.id, version=version)
            ]
        else:
            self.items = [
                current_item
                for current_item in self.items
                if current_item.id != item.id
            ]

    async def store_async(
        self,
        dry_run: bool = False,
        *,
        job_timeout: int = 600,
        synapse_client: Optional[Synapse] = None,
    ) -> "Self":
        """Store information about a DatasetCollection including the columns and annotations. This includes updating
        the `item`s of the DatasetCollection which will update the rows of the visualization in Synapse.

        DatasetCollections have default columns that are managed by Synapse. The default behavior of
        this function is to include these default columns in the dataset collection when it is stored.
        This means that with the default behavior, any columns that you have added to your
        DatasetCollection will be overwritten by the default columns if they have the same name. To
        avoid this behavior, set the `include_default_columns` attribute to `False`.

        Note the following behavior for the order of columns:

        - If a column is added via the `add_column` method it will be added at the
            index you specify, or at the end of the columns list.
        - If column(s) are added during the construction of your DatasetCollection instance, ie.
            `DatasetCollection(columns=[Column(name="foo")])`, they will be added at the beginning
            of the columns list.
        - If you use the `store_rows` method and the `schema_storage_strategy` is set to
            `INFER_FROM_DATA` the columns will be added at the end of the columns list.

        Arguments:
            dry_run: If True, will not actually store the table but will log to
                the console what would have been stored.
            job_timeout: The maximum amount of time to wait for a job to complete.
                This is used when updating the table schema. If the timeout
                is reached a `SynapseTimeoutError` will be raised.
                The default is 600 seconds
            synapse_client: If not passed in and caching was not disabled by
                `Synapse.allow_client_caching(False)` this will use the last created
                instance from the Synapse class constructor.

        Returns:
            The DatasetCollection instance stored in synapse.

        Example: Create a new Dataset Collection from a list of Datasets by storing it.
            &nbsp;

            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import DatasetCollection, Dataset

            syn = Synapse()
            syn.login()

            async def main():
                my_datasets = [Dataset(id="syn1234"), Dataset(id="syn1235"), Dataset(id="syn1236")]
                my_collection = DatasetCollection(parent_id="syn987", name="my-new-collection", items=my_datasets)
                await my_collection.store_async()

            asyncio.run(main())
            ```
        """
        return await super().store_async(
            dry_run=dry_run,
            job_timeout=job_timeout,
            synapse_client=synapse_client,
        )

    async def get_async(
        self,
        include_columns: bool = True,
        include_activity: bool = False,
        *,
        synapse_client: Optional[Synapse] = None,
    ) -> "Self":
        """Get the metadata about the DatasetCollection from synapse.

        Arguments:
            include_columns: If True, will include fully filled column objects in the
                `.columns` attribute. Defaults to True.
            include_activity: If True the activity will be included in the DatasetCollection
                if it exists. Defaults to False.

            synapse_client: If not passed in and caching was not disabled by
                `Synapse.allow_client_caching(False)` this will use the last created
                instance from the Synapse class constructor.

        Returns:
            The DatasetCollection instance stored in synapse.

        Example: Getting metadata about a Dataset Collection using id
            Get a DatasetCollection by ID and print out the columns and activity. `include_columns`
            defaults to True and `include_activity` defaults to False. When you need to
            update existing columns or activity these need to be set to True during the
            `get_async` call, then you'll make the changes, and finally call the
            `.store_async()` method.

            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import DatasetCollection

            syn = Synapse()
            syn.login()

            async def main():
                collection = await DatasetCollection(id="syn4567").get_async(include_activity=True)
                print(collection)

                # Columns are retrieved by default
                print(collection.columns)
                print(collection.activity)

            asyncio.run(main())
            ```

        Example: Getting metadata about a Dataset Collection using name and parent_id
            Get a Dataset Collection by name/parent_id and print out the columns and activity.
            `include_columns` defaults to True and `include_activity` defaults to
            False. When you need to update existing columns or activity these need to
            be set to True during the `get_async` call, then you'll make the changes,
            and finally call the `.store_async()` method.

            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import DatasetCollection

            syn = Synapse()
            syn.login()

            async def main():
                collection = await DatasetCollection(
                    name="my_collection",
                    parent_id="syn1234"
                ).get_async(
                    include_columns=True,
                    include_activity=True
                )
                print(collection)
                print(collection.columns)
                print(collection.activity)

            asyncio.run(main())
            ```
        """
        return await super().get_async(
            include_columns=include_columns,
            include_activity=include_activity,
            synapse_client=synapse_client,
        )

    async def delete_async(self, *, synapse_client: Optional[Synapse] = None) -> None:
        """Delete the dataset collection from synapse. This is not version specific. If you'd like
        to delete a specific version of the dataset collection you must use the
        [synapseclient.api.delete_entity][] function directly.

        Arguments:
            synapse_client: If not passed in and caching was not disabled by
                `Synapse.allow_client_caching(False)` this will use the last created
                instance from the Synapse class constructor.

        Returns:
            None

        Example: Deleting a Dataset Collection
            Deleting a Dataset Collection is only supported by the ID of the Dataset Collection.

            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import DatasetCollection

            syn = Synapse()
            syn.login()

            async def main():
                await DatasetCollection(id="syn4567").delete_async()

            asyncio.run(main())
            ```
        """
        await super().delete_async(synapse_client=synapse_client)

    async def update_rows_async(
        self,
        values: DATA_FRAME_TYPE,
        primary_keys: List[str],
        dry_run: bool = False,
        *,
        rows_per_query: int = 50000,
        update_size_bytes: int = 1.9 * MB,
        insert_size_bytes: int = 900 * MB,
        job_timeout: int = 600,
        wait_for_eventually_consistent_view: bool = False,
        wait_for_eventually_consistent_view_timeout: int = 600,
        synapse_client: Optional[Synapse] = None,
        **kwargs,
    ) -> None:
        """Update the values of rows in the dataset collection. This method can only
        be used to update values in custom columns. Default columns cannot be updated, but
        may be used as primary keys.

        Limitations:

        - When updating many rows the requests to Synapse will be chunked into smaller
            requests. The limit is 2MB per request. This chunking will happen
            automatically and should not be a concern for most users. If you are
            having issues with the request being too large you may lower the
            number of rows you are trying to update.
        - The `primary_keys` argument must contain at least one column.
        - The `primary_keys` argument cannot contain columns that are a LIST type.
        - The `primary_keys` argument cannot contain columns that are a JSON type.
        - The values used as the `primary_keys` must be unique in the table. If there
            are multiple rows with the same values in the `primary_keys` the behavior
            is that an exception will be raised.
        - The columns used in `primary_keys` cannot contain updated values. Since
            the values in these columns are used to determine if a row exists, they
            cannot be updated in the same transaction.

        Arguments:
            values: Supports storing data from the following sources:

                - A string holding the path to a CSV file. The data will be read into a
                    [Pandas DataFrame](http://pandas.pydata.org/pandas-docs/stable/api.html#dataframe).
                    The code makes assumptions about the format of the columns in the
                    CSV as detailed in the [csv_to_pandas_df][synapseclient.models.mixins.table_components.csv_to_pandas_df]
                    function. You may pass in additional arguments to the `csv_to_pandas_df`
                    function by passing them in as keyword arguments to this function.
                - A dictionary where the key is the column name and the value is one or
                    more values. The values will be wrapped into a [Pandas DataFrame](http://pandas.pydata.org/pandas-docs/stable/api.html#dataframe). You may pass in additional arguments to the `pd.DataFrame` function by passing them in as keyword arguments to this function. Read about the available arguments in the [Pandas DataFrame](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html) documentation.
                - A [Pandas DataFrame](http://pandas.pydata.org/pandas-docs/stable/api.html#dataframe)

            primary_keys: The columns to use to determine if a row already exists. If
                a row exists with the same values in the columns specified in this list
                the row will be updated. If a row does not exist nothing will be done.

            dry_run: If set to True the data will not be updated in Synapse. A message
                will be printed to the console with the number of rows that would have
                been updated and inserted. If you would like to see the data that would
                be updated and inserted you may set the `dry_run` argument to True and
                set the log level to DEBUG by setting the debug flag when creating
                your Synapse class instance like: `syn = Synapse(debug=True)`.

            rows_per_query: The number of rows that will be queried from Synapse per
                request. Since we need to query for the data that is being updated
                this will determine the number of rows that are queried at a time.
                The default is 50,000 rows.

            update_size_bytes: The maximum size of the request that will be sent to Synapse
                when updating rows of data. The default is 1.9MB.

            insert_size_bytes: The maximum size of the request that will be sent to Synapse
                when inserting rows of data. The default is 900MB.

            job_timeout: The maximum amount of time to wait for a job to complete.
                This is used when inserting, and updating rows of data. Each individual
                request to Synapse will be sent as an independent job. If the timeout
                is reached a `SynapseTimeoutError` will be raised.
                The default is 600 seconds

            wait_for_eventually_consistent_view: Only used if the table is a view. If
                set to True this will wait for the view to reflect any changes that
                you've made to the view. This is useful if you need to query the view
                after making changes to the data.

            wait_for_eventually_consistent_view_timeout: The maximum amount of time to
                wait for a view to be eventually consistent. The default is 600 seconds.

            synapse_client: If not passed in and caching was not disabled by
                `Synapse.allow_client_caching(False)` this will use the last created
                instance from the Synapse class constructor

            **kwargs: Additional arguments that are passed to the `pd.DataFrame`
                function when the `values` argument is a path to a csv file.


        Example: Update custom column values in a Dataset Collection.
            &nbsp;

            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import DatasetCollection

            syn = Synapse()
            syn.login()

            async def main():
                my_collection = await DatasetCollection(id="syn1234").get_async()
                # my_annotation must already exist in the dataset collection as a custom column
                modified_data = pd.DataFrame(
                    {"id": ["syn1234"], "my_annotation": ["good data"]}
                )
                await my_collection.update_rows_async(values=modified_data, primary_keys=["id"], dry_run=False)

            asyncio.run(main())
            ```
        """
        await super().update_rows_async(
            values=values,
            primary_keys=primary_keys,
            dry_run=dry_run,
            rows_per_query=rows_per_query,
            update_size_bytes=update_size_bytes,
            insert_size_bytes=insert_size_bytes,
            job_timeout=job_timeout,
            wait_for_eventually_consistent_view=wait_for_eventually_consistent_view,
            wait_for_eventually_consistent_view_timeout=wait_for_eventually_consistent_view_timeout,
            synapse_client=synapse_client,
            **kwargs,
        )

    async def snapshot_async(
        self,
        *,
        comment: Optional[str] = None,
        label: Optional[str] = None,
        include_activity: bool = True,
        associate_activity_to_new_version: bool = True,
        synapse_client: Optional[Synapse] = None,
    ) -> "TableUpdateTransaction":
        """Creates a snapshot of the dataset collection. A snapshot is a saved, read-only version of the dataset collection
        at the time it was created. Dataset collection snapshots are created using the asyncronous job API.

        Arguments:
            comment: A unique comment to associate with the snapshot.
            label: A unique label to associate with the snapshot.
            include_activity: If True the activity will be included in snapshot if it
                exists. In order to include the activity, the activity must have already
                been stored in Synapse by using the `activity` attribute on the Dataset
                Collection and calling the `store()` method on the Dataset Collection
                instance. Adding an activity to a snapshot of a dataset collection is
                meant to capture the provenance of the data at the time of the snapshot.
                Defaults to True.
            associate_activity_to_new_version: If True the activity will be associated
                with the new version of the dataset collection. If False the activity will
                not be associated with the new version of the dataset collection. Defaults
                to True.
            synapse_client: If not passed in and caching was not disabled by
                `Synapse.allow_client_caching(False)` this will use the last created
                instance from the Synapse class constructor.

        Returns:
            A `TableUpdateTransaction` object which includes the version number of the snapshot.

        Example: Save a snapshot of a Dataset Collection.
            &nbsp;

            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import DatasetCollection

            syn = Synapse()
            syn.login()

            async def main():
                my_collection = await DatasetCollection(id="syn1234").get_async()
                await my_collection.snapshot_async(comment="My first snapshot", label="My first snapshot")

            asyncio.run(main())
            ```
        """
        return await super().snapshot_async(
            comment=comment,
            label=label,
            include_activity=include_activity,
            associate_activity_to_new_version=associate_activity_to_new_version,
            synapse_client=synapse_client,
        )

Functions¶

add_item ¶

add_item(item: Union[Dataset, EntityRef]) -> None

Adds a dataset to the dataset collection. Effect is not seen until the dataset collection is stored.

PARAMETER	DESCRIPTION
`item`	Dataset to add to the collection. Must be a Dataset. TYPE: `Union[Dataset, EntityRef]`

RAISES	DESCRIPTION
`ValueError`	If the item is not a Dataset

Add a Dataset to a Dataset Collection.

from synapseclient import Synapse
from synapseclient.models import DatasetCollection, Dataset

syn = Synapse()
syn.login()

my_collection = DatasetCollection(id="syn1234").get()
my_collection.add_item(Dataset(id="syn1235"))
my_collection.store()

Source code in synapseclient/models/dataset.py

def add_item(
    self,
    item: Union["Dataset", "EntityRef"],
) -> None:
    """Adds a dataset to the dataset collection.
    Effect is not seen until the dataset collection is stored.

    Arguments:
        item: Dataset to add to the collection. Must be a Dataset.

    Raises:
        ValueError: If the item is not a Dataset

    Example: Add a Dataset to a Dataset Collection.
        &nbsp;

        ```python
        from synapseclient import Synapse
        from synapseclient.models import DatasetCollection, Dataset

        syn = Synapse()
        syn.login()

        my_collection = DatasetCollection(id="syn1234").get()
        my_collection.add_item(Dataset(id="syn1235"))
        my_collection.store()
        ```
    """
    if not isinstance(item, (Dataset, EntityRef)):
        raise ValueError(
            f"item must be a Dataset or EntityRef. {item} is a {type(item)}"
        )

    # EntityRef uses `version`, Dataset uses `version_number`
    version = item.version if isinstance(item, EntityRef) else item.version_number

    if not any(
        current_item.id == item.id and current_item.version == version
        for current_item in self.items
    ):
        self.items.append(EntityRef(id=item.id, version=version))

remove_item ¶

remove_item(item: Union[Dataset, EntityRef]) -> None

Removes an entity from the dataset collection. Must be a Dataset or EntityRef. Effect is not seen until the dataset collection is stored. Unless the version is specified, all entities with the same ID will be removed.

PARAMETER	DESCRIPTION
`item`	The Dataset to remove from the collection TYPE: `Union[Dataset, EntityRef]`

RETURNS	DESCRIPTION
`None`	None

RAISES	DESCRIPTION
`ValueError`	If the item is not a Dataset

Remove a Dataset from a Dataset Collection.

from synapseclient import Synapse
from synapseclient.models import DatasetCollection, Dataset

syn = Synapse()
syn.login()

my_collection = DatasetCollection(id="syn1234").get()
my_collection.remove_item(Dataset(id="syn1235", version_number=1))
my_collection.store()

Remove all versions of a Dataset from a Dataset Collection.

from synapseclient import Synapse
from synapseclient.models import DatasetCollection, Dataset

syn = Synapse()
syn.login()

my_collection = DatasetCollection(id="syn1234").get()
my_collection.remove_item(Dataset(id="syn1235"))
my_collection.store()

Source code in synapseclient/models/dataset.py

def remove_item(
    self,
    item: Union["Dataset", "EntityRef"],
) -> None:
    """
    Removes an entity from the dataset collection. Must be a Dataset or EntityRef.
    Effect is not seen until the dataset collection is stored.
    Unless the version is specified, all entities with the same ID will be removed.

    Arguments:
        item: The Dataset to remove from the collection

    Returns:
        None

    Raises:
        ValueError: If the item is not a Dataset

    Example: Remove a Dataset from a Dataset Collection.
        &nbsp;

        ```python
        from synapseclient import Synapse
        from synapseclient.models import DatasetCollection, Dataset

        syn = Synapse()
        syn.login()

        my_collection = DatasetCollection(id="syn1234").get()
        my_collection.remove_item(Dataset(id="syn1235", version_number=1))
        my_collection.store()
        ```

    Example: Remove all versions of a Dataset from a Dataset Collection.
        &nbsp;

        ```python
        from synapseclient import Synapse
        from synapseclient.models import DatasetCollection, Dataset

        syn = Synapse()
        syn.login()

        my_collection = DatasetCollection(id="syn1234").get()
        my_collection.remove_item(Dataset(id="syn1235"))
        my_collection.store()
        ```
    """
    if not isinstance(item, (Dataset, EntityRef)):
        raise ValueError(
            f"item must be a Dataset or EntityRef. {item} is a {type(item)}"
        )

    version = item.version if isinstance(item, EntityRef) else item.version_number

    if version:
        self.items = [
            current_item
            for current_item in self.items
            if current_item != EntityRef(id=item.id, version=version)
        ]
    else:
        self.items = [
            current_item
            for current_item in self.items
            if current_item.id != item.id
        ]

store ¶

store(dry_run: bool = False, *, job_timeout: int = 600, synapse_client: Optional[Synapse] = None) -> Self

Store non-row information about a DatasetCollection including the columns and annotations.

DatasetCollections have default columns that are managed by Synapse. The default behavior of this function is to include these default columns in the dataset collection when it is stored. This means that with the default behavior, any columns that you have added to your DatasetCollection will be overwritten by the default columns if they have the same name. To avoid this behavior, set the include_default_columns attribute to False.

Note the following behavior for the order of columns:

If a column is added via the add_column method it will be added at the index you specify, or at the end of the columns list.
If column(s) are added during the construction of your DatasetCollection instance, ie. DatasetCollection(columns=[Column(name="foo")]), they will be added at the beginning of the columns list.
If you use the store_rows method and the schema_storage_strategy is set to INFER_FROM_DATA the columns will be added at the end of the columns list.

PARAMETER	DESCRIPTION
`dry_run`	If True, will not actually store the table but will log to the console what would have been stored. TYPE: `bool` DEFAULT: `False`
`job_timeout`	The maximum amount of time to wait for a job to complete. This is used when updating the table schema. If the timeout is reached a `SynapseTimeoutError` will be raised. The default is 600 seconds TYPE: `int` DEFAULT: `600`
`synapse_client`	If not passed in and caching was not disabled by `Synapse.allow_client_caching(False)` this will use the last created instance from the Synapse class constructor. TYPE: `Optional[Synapse]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Self`	The DatasetCollection instance stored in synapse.

Create a new Dataset Collection from a list of Datasets by storing it.

from synapseclient import Synapse
from synapseclient.models import DatasetCollection, Dataset

syn = Synapse()
syn.login()

my_datasets = [Dataset(id="syn1234"), Dataset(id="syn1235"), Dataset(id="syn1236")]
my_collection = DatasetCollection(parent_id="syn987", name="my-new-collection", items=my_datasets)
my_collection.store()

Source code in synapseclient/models/dataset.py

def store(
    self,
    dry_run: bool = False,
    *,
    job_timeout: int = 600,
    synapse_client: Optional[Synapse] = None,
) -> "Self":
    """Store non-row information about a DatasetCollection including the columns and annotations.

    DatasetCollections have default columns that are managed by Synapse. The default behavior of
    this function is to include these default columns in the dataset collection when it is stored.
    This means that with the default behavior, any columns that you have added to your
    DatasetCollection will be overwritten by the default columns if they have the same name. To
    avoid this behavior, set the `include_default_columns` attribute to `False`.

    Note the following behavior for the order of columns:

    - If a column is added via the `add_column` method it will be added at the
        index you specify, or at the end of the columns list.
    - If column(s) are added during the construction of your DatasetCollection instance, ie.
        `DatasetCollection(columns=[Column(name="foo")])`, they will be added at the beginning
        of the columns list.
    - If you use the `store_rows` method and the `schema_storage_strategy` is set to
        `INFER_FROM_DATA` the columns will be added at the end of the columns list.

    Arguments:
        dry_run: If True, will not actually store the table but will log to
            the console what would have been stored.
        job_timeout: The maximum amount of time to wait for a job to complete.
            This is used when updating the table schema. If the timeout
            is reached a `SynapseTimeoutError` will be raised.
            The default is 600 seconds
        synapse_client: If not passed in and caching was not disabled by
            `Synapse.allow_client_caching(False)` this will use the last created
            instance from the Synapse class constructor.

    Returns:
        The DatasetCollection instance stored in synapse.

    Example: Create a new Dataset Collection from a list of Datasets by storing it.
        &nbsp;

        ```python
        from synapseclient import Synapse
        from synapseclient.models import DatasetCollection, Dataset

        syn = Synapse()
        syn.login()

        my_datasets = [Dataset(id="syn1234"), Dataset(id="syn1235"), Dataset(id="syn1236")]
        my_collection = DatasetCollection(parent_id="syn987", name="my-new-collection", items=my_datasets)
        my_collection.store()
        ```
    """
    return self

get ¶

get(include_columns: bool = True, include_activity: bool = False, *, synapse_client: Optional[Synapse] = None) -> Self

Get the metadata about the DatasetCollection from synapse.

PARAMETER	DESCRIPTION
`include_columns`	If True, will include fully filled column objects in the `.columns` attribute. Defaults to True. TYPE: `bool` DEFAULT: `True`
`include_activity`	If True the activity will be included in the DatasetCollection if it exists. Defaults to False. TYPE: `bool` DEFAULT: `False`
`synapse_client`	If not passed in and caching was not disabled by `Synapse.allow_client_caching(False)` this will use the last created instance from the Synapse class constructor. TYPE: `Optional[Synapse]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Self`	The DatasetCollection instance stored in synapse.

Getting metadata about a Dataset Collection using id

Get a Dataset Collection by ID and print out the columns and activity. include_columns defaults to True and include_activity defaults to False. When you need to update existing columns or activity these need to be set to True during the get call, then you'll make the changes, and finally call the .store() method.

from synapseclient import Synapse
from synapseclient.models import DatasetCollection

syn = Synapse()
syn.login()

collection = DatasetCollection(id="syn4567").get(include_activity=True)
print(collection)

# Columns are retrieved by default
print(collection.columns)
print(collection.activity)

Getting metadata about a Dataset Collection using name and parent_id

Get a Dataset Collection by name/parent_id and print out the columns and activity. include_columns defaults to True and include_activity defaults to False. When you need to update existing columns or activity these need to be set to True during the get call, then you'll make the changes, and finally call the .store() method.

from synapseclient import Synapse
from synapseclient.models import DatasetCollection

syn = Synapse()
syn.login()

collection = DatasetCollection(name="my_collection", parent_id="syn1234").get(include_columns=True, include_activity=True)
print(collection)
print(collection.columns)
print(collection.activity)

Source code in synapseclient/models/dataset.py

def get(
    self,
    include_columns: bool = True,
    include_activity: bool = False,
    *,
    synapse_client: Optional[Synapse] = None,
) -> "Self":
    """Get the metadata about the DatasetCollection from synapse.

    Arguments:
        include_columns: If True, will include fully filled column objects in the
            `.columns` attribute. Defaults to True.
        include_activity: If True the activity will be included in the DatasetCollection
            if it exists. Defaults to False.

        synapse_client: If not passed in and caching was not disabled by
            `Synapse.allow_client_caching(False)` this will use the last created
            instance from the Synapse class constructor.

    Returns:
        The DatasetCollection instance stored in synapse.

    Example: Getting metadata about a Dataset Collection using id
        Get a Dataset Collection by ID and print out the columns and activity. `include_columns`
        defaults to True and `include_activity` defaults to False. When you need to
        update existing columns or activity these need to be set to True during the
        `get` call, then you'll make the changes, and finally call the
        `.store()` method.

        ```python
        from synapseclient import Synapse
        from synapseclient.models import DatasetCollection

        syn = Synapse()
        syn.login()

        collection = DatasetCollection(id="syn4567").get(include_activity=True)
        print(collection)

        # Columns are retrieved by default
        print(collection.columns)
        print(collection.activity)
        ```

    Example: Getting metadata about a Dataset Collection using name and parent_id
        Get a Dataset Collection by name/parent_id and print out the columns and activity.
        `include_columns` defaults to True and `include_activity` defaults to
        False. When you need to update existing columns or activity these need to
        be set to True during the `get` call, then you'll make the changes,
        and finally call the `.store()` method.

        ```python
        from synapseclient import Synapse
        from synapseclient.models import DatasetCollection

        syn = Synapse()
        syn.login()

        collection = DatasetCollection(name="my_collection", parent_id="syn1234").get(include_columns=True, include_activity=True)
        print(collection)
        print(collection.columns)
        print(collection.activity)
        ```
    """
    return self

delete ¶

delete(*, synapse_client: Optional[Synapse] = None) -> None

Delete the dataset collection from synapse. This is not version specific. If you'd like to delete a specific version of the dataset collection you must use the synapseclient.api.delete_entity function directly.

PARAMETER	DESCRIPTION
`synapse_client`	If not passed in and caching was not disabled by `Synapse.allow_client_caching(False)` this will use the last created instance from the Synapse class constructor. TYPE: `Optional[Synapse]` DEFAULT: `None`

RETURNS	DESCRIPTION
`None`	None

Deleting a Dataset Collection

Deleting a Dataset Collection is only supported by the ID of the Dataset Collection.

from synapseclient import Synapse
from synapseclient.models import DatasetCollection

syn = Synapse()
syn.login()

DatasetCollection(id="syn4567").delete()

Source code in synapseclient/models/dataset.py

def delete(self, *, synapse_client: Optional[Synapse] = None) -> None:
    """Delete the dataset collection from synapse. This is not version specific. If you'd like
    to delete a specific version of the dataset collection you must use the
    [synapseclient.api.delete_entity][] function directly.

    Arguments:
        synapse_client: If not passed in and caching was not disabled by
            `Synapse.allow_client_caching(False)` this will use the last created
            instance from the Synapse class constructor.

    Returns:
        None

    Example: Deleting a Dataset Collection
        Deleting a Dataset Collection is only supported by the ID of the Dataset Collection.

        ```python
        from synapseclient import Synapse
        from synapseclient.models import DatasetCollection

        syn = Synapse()
        syn.login()

        DatasetCollection(id="syn4567").delete()
        ```
    """
    return None

update_rows ¶

update_rows(values: DATA_FRAME_TYPE, primary_keys: List[str], dry_run: bool = False, *, rows_per_query: int = 50000, update_size_bytes: int = 1.9 * MB, insert_size_bytes: int = 900 * MB, job_timeout: int = 600, wait_for_eventually_consistent_view: bool = False, wait_for_eventually_consistent_view_timeout: int = 600, synapse_client: Optional[Synapse] = None, **kwargs) -> None

Update the values of rows in the dataset collection. This method can only be used to update values in custom columns. Default columns cannot be updated, but may be used as primary keys.

Limitations:

When updating many rows the requests to Synapse will be chunked into smaller requests. The limit is 2MB per request. This chunking will happen automatically and should not be a concern for most users. If you are having issues with the request being too large you may lower the number of rows you are trying to update.
The primary_keys argument must contain at least one column.
The primary_keys argument cannot contain columns that are a LIST type.
The primary_keys argument cannot contain columns that are a JSON type.
The values used as the primary_keys must be unique in the table. If there are multiple rows with the same values in the primary_keys the behavior is that an exception will be raised.
The columns used in primary_keys cannot contain updated values. Since the values in these columns are used to determine if a row exists, they cannot be updated in the same transaction.

PARAMETER	DESCRIPTION
`values`	Supports storing data from the following sources: A string holding the path to a CSV file. The data will be read into a Pandas DataFrame. The code makes assumptions about the format of the columns in the CSV as detailed in the csv_to_pandas_df function. You may pass in additional arguments to the `csv_to_pandas_df` function by passing them in as keyword arguments to this function. A dictionary where the key is the column name and the value is one or more values. The values will be wrapped into a Pandas DataFrame. You may pass in additional arguments to the `pd.DataFrame` function by passing them in as keyword arguments to this function. Read about the available arguments in the Pandas DataFrame documentation. A Pandas DataFrame TYPE: `DATA_FRAME_TYPE`
`primary_keys`	The columns to use to determine if a row already exists. If a row exists with the same values in the columns specified in this list the row will be updated. If a row does not exist nothing will be done. TYPE: `List[str]`
`dry_run`	If set to True the data will not be updated in Synapse. A message will be printed to the console with the number of rows that would have been updated and inserted. If you would like to see the data that would be updated and inserted you may set the `dry_run` argument to True and set the log level to DEBUG by setting the debug flag when creating your Synapse class instance like: `syn = Synapse(debug=True)`. TYPE: `bool` DEFAULT: `False`
`rows_per_query`	The number of rows that will be queried from Synapse per request. Since we need to query for the data that is being updated this will determine the number of rows that are queried at a time. The default is 50,000 rows. TYPE: `int` DEFAULT: `50000`
`update_size_bytes`	The maximum size of the request that will be sent to Synapse when updating rows of data. The default is 1.9MB. TYPE: `int` DEFAULT: `1.9 * MB`
`insert_size_bytes`	The maximum size of the request that will be sent to Synapse when inserting rows of data. The default is 900MB. TYPE: `int` DEFAULT: `900 * MB`
`job_timeout`	The maximum amount of time to wait for a job to complete. This is used when inserting, and updating rows of data. Each individual request to Synapse will be sent as an independent job. If the timeout is reached a `SynapseTimeoutError` will be raised. The default is 600 seconds TYPE: `int` DEFAULT: `600`
`wait_for_eventually_consistent_view`	Only used if the table is a view. If set to True this will wait for the view to reflect any changes that you've made to the view. This is useful if you need to query the view after making changes to the data. TYPE: `bool` DEFAULT: `False`
`wait_for_eventually_consistent_view_timeout`	The maximum amount of time to wait for a view to be eventually consistent. The default is 600 seconds. TYPE: `int` DEFAULT: `600`
`synapse_client`	If not passed in and caching was not disabled by `Synapse.allow_client_caching(False)` this will use the last created instance from the Synapse class constructor TYPE: `Optional[Synapse]` DEFAULT: `None`
`**kwargs`	Additional arguments that are passed to the `pd.DataFrame` function when the `values` argument is a path to a csv file. DEFAULT: `{}`

Update custom column values in a Dataset Collection.

from synapseclient import Synapse
from synapseclient.models import DatasetCollection

syn = Synapse()
syn.login()

my_collection = DatasetCollection(id="syn1234").get()

# my_annotation must already exist in the dataset collection as a custom column
modified_data = pd.DataFrame(
    {"id": ["syn1234"], "my_annotation": ["good data"]}
)
my_collection.update_rows(values=modified_data, primary_keys=["id"], dry_run=False)

Source code in synapseclient/models/dataset.py

def update_rows(
    self,
    values: DATA_FRAME_TYPE,
    primary_keys: List[str],
    dry_run: bool = False,
    *,
    rows_per_query: int = 50000,
    update_size_bytes: int = 1.9 * MB,
    insert_size_bytes: int = 900 * MB,
    job_timeout: int = 600,
    wait_for_eventually_consistent_view: bool = False,
    wait_for_eventually_consistent_view_timeout: int = 600,
    synapse_client: Optional[Synapse] = None,
    **kwargs,
) -> None:
    """Update the values of rows in the dataset collection. This method can only
    be used to update values in custom columns. Default columns cannot be updated, but
    may be used as primary keys.

    Limitations:

    - When updating many rows the requests to Synapse will be chunked into smaller
        requests. The limit is 2MB per request. This chunking will happen
        automatically and should not be a concern for most users. If you are
        having issues with the request being too large you may lower the
        number of rows you are trying to update.
    - The `primary_keys` argument must contain at least one column.
    - The `primary_keys` argument cannot contain columns that are a LIST type.
    - The `primary_keys` argument cannot contain columns that are a JSON type.
    - The values used as the `primary_keys` must be unique in the table. If there
        are multiple rows with the same values in the `primary_keys` the behavior
        is that an exception will be raised.
    - The columns used in `primary_keys` cannot contain updated values. Since
        the values in these columns are used to determine if a row exists, they
        cannot be updated in the same transaction.

    Arguments:
        values: Supports storing data from the following sources:

            - A string holding the path to a CSV file. The data will be read into a
                [Pandas DataFrame](http://pandas.pydata.org/pandas-docs/stable/api.html#dataframe).
                The code makes assumptions about the format of the columns in the
                CSV as detailed in the [csv_to_pandas_df][synapseclient.models.mixins.table_components.csv_to_pandas_df]
                function. You may pass in additional arguments to the `csv_to_pandas_df`
                function by passing them in as keyword arguments to this function.
            - A dictionary where the key is the column name and the value is one or
                more values. The values will be wrapped into a [Pandas DataFrame](http://pandas.pydata.org/pandas-docs/stable/api.html#dataframe). You may pass in additional arguments to the `pd.DataFrame` function by passing them in as keyword arguments to this function. Read about the available arguments in the [Pandas DataFrame](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html) documentation.
            - A [Pandas DataFrame](http://pandas.pydata.org/pandas-docs/stable/api.html#dataframe)

        primary_keys: The columns to use to determine if a row already exists. If
            a row exists with the same values in the columns specified in this list
            the row will be updated. If a row does not exist nothing will be done.

        dry_run: If set to True the data will not be updated in Synapse. A message
            will be printed to the console with the number of rows that would have
            been updated and inserted. If you would like to see the data that would
            be updated and inserted you may set the `dry_run` argument to True and
            set the log level to DEBUG by setting the debug flag when creating
            your Synapse class instance like: `syn = Synapse(debug=True)`.

        rows_per_query: The number of rows that will be queried from Synapse per
            request. Since we need to query for the data that is being updated
            this will determine the number of rows that are queried at a time.
            The default is 50,000 rows.

        update_size_bytes: The maximum size of the request that will be sent to Synapse
            when updating rows of data. The default is 1.9MB.

        insert_size_bytes: The maximum size of the request that will be sent to Synapse
            when inserting rows of data. The default is 900MB.

        job_timeout: The maximum amount of time to wait for a job to complete.
            This is used when inserting, and updating rows of data. Each individual
            request to Synapse will be sent as an independent job. If the timeout
            is reached a `SynapseTimeoutError` will be raised.
            The default is 600 seconds

        wait_for_eventually_consistent_view: Only used if the table is a view. If
            set to True this will wait for the view to reflect any changes that
            you've made to the view. This is useful if you need to query the view
            after making changes to the data.

        wait_for_eventually_consistent_view_timeout: The maximum amount of time to
            wait for a view to be eventually consistent. The default is 600 seconds.

        synapse_client: If not passed in and caching was not disabled by
            `Synapse.allow_client_caching(False)` this will use the last created
            instance from the Synapse class constructor

        **kwargs: Additional arguments that are passed to the `pd.DataFrame`
            function when the `values` argument is a path to a csv file.


    Example: Update custom column values in a Dataset Collection.
        &nbsp;

        ```python
        from synapseclient import Synapse
        from synapseclient.models import DatasetCollection

        syn = Synapse()
        syn.login()

        my_collection = DatasetCollection(id="syn1234").get()

        # my_annotation must already exist in the dataset collection as a custom column
        modified_data = pd.DataFrame(
            {"id": ["syn1234"], "my_annotation": ["good data"]}
        )
        my_collection.update_rows(values=modified_data, primary_keys=["id"], dry_run=False)
        ```
    """
    return None

snapshot ¶

snapshot(*, comment: Optional[str] = None, label: Optional[str] = None, include_activity: bool = True, associate_activity_to_new_version: bool = True, synapse_client: Optional[Synapse] = None) -> TableUpdateTransaction

Creates a snapshot of the dataset collection. A snapshot is a saved, read-only version of the dataset collection at the time it was created. Dataset collection snapshots are created using the asyncronous job API.

PARAMETER	DESCRIPTION
`comment`	A unique comment to associate with the snapshot. TYPE: `Optional[str]` DEFAULT: `None`
`label`	A unique label to associate with the snapshot. TYPE: `Optional[str]` DEFAULT: `None`
`include_activity`	If True the activity will be included in snapshot if it exists. In order to include the activity, the activity must have already been stored in Synapse by using the `activity` attribute on the Dataset Collection and calling the `store()` method on the Dataset Collection instance. Adding an activity to a snapshot of a dataset collection is meant to capture the provenance of the data at the time of the snapshot. Defaults to True. TYPE: `bool` DEFAULT: `True`
`associate_activity_to_new_version`	If True the activity will be associated with the new version of the dataset collection. If False the activity will not be associated with the new version of the dataset collection. Defaults to True. TYPE: `bool` DEFAULT: `True`
`synapse_client`	If not passed in and caching was not disabled by `Synapse.allow_client_caching(False)` this will use the last created instance from the Synapse class constructor. TYPE: `Optional[Synapse]` DEFAULT: `None`

RETURNS	DESCRIPTION
`TableUpdateTransaction`	A `TableUpdateTransaction` object which includes the version number of the snapshot.

Save a snapshot of a Dataset Collection.

from synapseclient import Synapse
from synapseclient.models import DatasetCollection

syn = Synapse()
syn.login()

my_collection = DatasetCollection(id="syn1234").get()
my_collection.snapshot(comment="My first snapshot", label="My first snapshot")

Source code in synapseclient/models/dataset.py

def snapshot(
    self,
    *,
    comment: Optional[str] = None,
    label: Optional[str] = None,
    include_activity: bool = True,
    associate_activity_to_new_version: bool = True,
    synapse_client: Optional[Synapse] = None,
) -> "TableUpdateTransaction":
    """Creates a snapshot of the dataset collection. A snapshot is a saved, read-only version of the dataset collection
    at the time it was created. Dataset collection snapshots are created using the asyncronous job API.

    Arguments:
        comment: A unique comment to associate with the snapshot.
        label: A unique label to associate with the snapshot.
        include_activity: If True the activity will be included in snapshot if it
            exists. In order to include the activity, the activity must have already
            been stored in Synapse by using the `activity` attribute on the Dataset Collection
            and calling the `store()` method on the Dataset Collection instance. Adding an
            activity to a snapshot of a dataset collection is meant to capture the provenance of
            the data at the time of the snapshot. Defaults to True.
        associate_activity_to_new_version: If True the activity will be associated
            with the new version of the dataset collection. If False the activity will not be
            associated with the new version of the dataset collection. Defaults to True.
        synapse_client: If not passed in and caching was not disabled by
            `Synapse.allow_client_caching(False)` this will use the last created
            instance from the Synapse class constructor.

    Returns:
        A `TableUpdateTransaction` object which includes the version number of the snapshot.

    Example: Save a snapshot of a Dataset Collection.
        &nbsp;

        ```python
        from synapseclient import Synapse
        from synapseclient.models import DatasetCollection

        syn = Synapse()
        syn.login()

        my_collection = DatasetCollection(id="syn1234").get()
        my_collection.snapshot(comment="My first snapshot", label="My first snapshot")
        ```
    """
    return TableUpdateTransaction

query `staticmethod` ¶

query(query: str, include_row_id_and_row_version: bool = True, convert_to_datetime: bool = False, download_location=None, quote_character='"', escape_character='\\', line_end=str(linesep), separator=',', header=True, *, synapse_client: Optional[Synapse] = None, **kwargs) -> Union[DATA_FRAME_TYPE, str]

Query for data on a table stored in Synapse. The results will always be returned as a Pandas DataFrame unless you specify a download_location in which case the results will be downloaded to that location. There are a number of arguments that you may pass to this function depending on if you are getting the results back as a DataFrame or downloading the results to a file.

PARAMETER	DESCRIPTION
`query`	The query to run. The query must be valid syntax that Synapse can understand. See this document that describes the expected syntax of the query: https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/web/controller/TableExamples.html TYPE: `str`
`include_row_id_and_row_version`	If True the `ROW_ID` and `ROW_VERSION` columns will be returned in the DataFrame. These columns are required if using the query results to update rows in the table. These columns are the primary keys used by Synapse to uniquely identify rows in the table. TYPE: `bool` DEFAULT: `True`
`convert_to_datetime`	(DataFrame only) If set to True, will convert all Synapse DATE columns from UNIX timestamp integers into UTC datetime objects TYPE: `bool` DEFAULT: `False`
`download_location`	(CSV Only) If set to a path the results will be downloaded to that directory. The results will be downloaded as a CSV file. A path to the downloaded file will be returned instead of a DataFrame. DEFAULT: `None`
`quote_character`	(CSV Only) The character to use to quote fields. The default is a double quote. DEFAULT: `'"'`
`escape_character`	(CSV Only) The character to use to escape special characters. The default is a backslash. DEFAULT: `'\\'`
`line_end`	(CSV Only) The character to use to end a line. The default is the system's line separator. DEFAULT: `str(linesep)`
`separator`	(CSV Only) The character to use to separate fields. The default is a comma. DEFAULT: `','`
`header`	(CSV Only) If set to True the first row will be used as the header row. The default is True. DEFAULT: `True`
`**kwargs`	(DataFrame only) Additional keyword arguments to pass to pandas.read_csv. See https://pandas.pydata.org/docs/reference/api/pandas.read_csv.html for complete list of supported arguments. This is exposed as internally the query downloads a CSV from Synapse and then loads it into a dataframe. DEFAULT: `{}`
`synapse_client`	If not passed in and caching was not disabled by `Synapse.allow_client_caching(False)` this will use the last created instance from the Synapse class constructor. TYPE: `Optional[Synapse]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Union[DATA_FRAME_TYPE, str]`	The results of the query as a Pandas DataFrame or a path to the downloaded
`Union[DATA_FRAME_TYPE, str]`	query results if `download_location` is set.

Querying for data

This example shows how you may query for data in a table and print out the results.

from synapseclient import Synapse
from synapseclient.models import query

syn = Synapse()
syn.login()

results = query(query="SELECT * FROM syn1234")
print(results)

Source code in synapseclient/models/mixins/table_components.py

@staticmethod
def query(
    query: str,
    include_row_id_and_row_version: bool = True,
    convert_to_datetime: bool = False,
    download_location=None,
    quote_character='"',
    escape_character="\\",
    line_end=str(os.linesep),
    separator=",",
    header=True,
    *,
    synapse_client: Optional[Synapse] = None,
    **kwargs,
) -> Union[DATA_FRAME_TYPE, str]:
    """Query for data on a table stored in Synapse. The results will always be
    returned as a Pandas DataFrame unless you specify a `download_location` in which
    case the results will be downloaded to that location. There are a number of
    arguments that you may pass to this function depending on if you are getting
    the results back as a DataFrame or downloading the results to a file.

    Arguments:
        query: The query to run. The query must be valid syntax that Synapse can
            understand. See this document that describes the expected syntax of the
            query:
            <https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/web/controller/TableExamples.html>
        include_row_id_and_row_version: If True the `ROW_ID` and `ROW_VERSION`
            columns will be returned in the DataFrame. These columns are required
            if using the query results to update rows in the table. These columns
            are the primary keys used by Synapse to uniquely identify rows in the
            table.
        convert_to_datetime: (DataFrame only) If set to True, will convert all
            Synapse DATE columns from UNIX timestamp integers into UTC datetime
            objects

        download_location: (CSV Only) If set to a path the results will be
            downloaded to that directory. The results will be downloaded as a CSV
            file. A path to the downloaded file will be returned instead of a
            DataFrame.

        quote_character: (CSV Only) The character to use to quote fields. The
            default is a double quote.

        escape_character: (CSV Only) The character to use to escape special
            characters. The default is a backslash.

        line_end: (CSV Only) The character to use to end a line. The default is
            the system's line separator.

        separator: (CSV Only) The character to use to separate fields. The default
            is a comma.

        header: (CSV Only) If set to True the first row will be used as the header
            row. The default is True.

        **kwargs: (DataFrame only) Additional keyword arguments to pass to
            pandas.read_csv. See
            <https://pandas.pydata.org/docs/reference/api/pandas.read_csv.html>
            for complete list of supported arguments. This is exposed as
            internally the query downloads a CSV from Synapse and then loads
            it into a dataframe.
        synapse_client: If not passed in and caching was not disabled by
            `Synapse.allow_client_caching(False)` this will use the last created
            instance from the Synapse class constructor.

    Returns:
        The results of the query as a Pandas DataFrame or a path to the downloaded
        query results if `download_location` is set.

    Example: Querying for data
        This example shows how you may query for data in a table and print out the
        results.

        ```python
        from synapseclient import Synapse
        from synapseclient.models import query

        syn = Synapse()
        syn.login()

        results = query(query="SELECT * FROM syn1234")
        print(results)
        ```
    """
    # Replaced at runtime
    return ""

query_part_mask `staticmethod` ¶

query_part_mask(query: str, part_mask: int, *, synapse_client: Optional[Synapse] = None) -> QueryResultBundle

Query for data on a table stored in Synapse. This is a more advanced use case of the query function that allows you to determine what addiitional metadata about the table or query should also be returned. If you do not need this additional information then you are better off using the query function.

The query for this method uses this Rest API: https://rest-docs.synapse.org/rest/POST/entity/id/table/query/async/start.html

PARAMETER	DESCRIPTION
`query`	The query to run. The query must be valid syntax that Synapse can understand. See this document that describes the expected syntax of the query: https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/web/controller/TableExamples.html TYPE: `str`
`part_mask`	The bitwise OR of the part mask values you want to return in the results. The following list of part masks are implemented to be returned in the results: Query Results (queryResults) = 0x1 Query Count (queryCount) = 0x2 The sum of the file sizes (sumFileSizesBytes) = 0x40 The last updated on date of the table (lastUpdatedOn) = 0x80 TYPE: `int`
`synapse_client`	If not passed in and caching was not disabled by `Synapse.allow_client_caching(False)` this will use the last created instance from the Synapse class constructor. TYPE: `Optional[Synapse]` DEFAULT: `None`

RETURNS	DESCRIPTION
`QueryResultBundle`	The results of the query as a Pandas DataFrame.

Querying for data with a part mask

This example shows how to use the bitwise OR of Python to combine the part mask values and then use that to query for data in a table and print out the results.

In this case we are getting the results of the query, the count of rows, and the last updated on date of the table.

from synapseclient import Synapse
from synapseclient.models import query_part_mask

syn = Synapse()
syn.login()

QUERY_RESULTS = 0x1
QUERY_COUNT = 0x2
LAST_UPDATED_ON = 0x80

# Combine the part mask values using bitwise OR
part_mask = QUERY_RESULTS | QUERY_COUNT | LAST_UPDATED_ON

result = query_part_mask(query="SELECT * FROM syn1234", part_mask=part_mask)
print(result)

Source code in synapseclient/models/mixins/table_components.py

@staticmethod
def query_part_mask(
    query: str,
    part_mask: int,
    *,
    synapse_client: Optional[Synapse] = None,
) -> QueryResultBundle:
    """Query for data on a table stored in Synapse. This is a more advanced use case
    of the `query` function that allows you to determine what addiitional metadata
    about the table or query should also be returned. If you do not need this
    additional information then you are better off using the `query` function.

    The query for this method uses this Rest API:
    <https://rest-docs.synapse.org/rest/POST/entity/id/table/query/async/start.html>

    Arguments:
        query: The query to run. The query must be valid syntax that Synapse can
            understand. See this document that describes the expected syntax of the
            query:
            <https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/web/controller/TableExamples.html>
        part_mask: The bitwise OR of the part mask values you want to return in the
            results. The following list of part masks are implemented to be returned
            in the results:

            - Query Results (queryResults) = 0x1
            - Query Count (queryCount) = 0x2
            - The sum of the file sizes (sumFileSizesBytes) = 0x40
            - The last updated on date of the table (lastUpdatedOn) = 0x80

        synapse_client: If not passed in and caching was not disabled by
            `Synapse.allow_client_caching(False)` this will use the last created
            instance from the Synapse class constructor.

    Returns:
        The results of the query as a Pandas DataFrame.

    Example: Querying for data with a part mask
        This example shows how to use the bitwise `OR` of Python to combine the
        part mask values and then use that to query for data in a table and print
        out the results.

        In this case we are getting the results of the query, the count of rows, and
        the last updated on date of the table.

        ```python
        from synapseclient import Synapse
        from synapseclient.models import query_part_mask

        syn = Synapse()
        syn.login()

        QUERY_RESULTS = 0x1
        QUERY_COUNT = 0x2
        LAST_UPDATED_ON = 0x80

        # Combine the part mask values using bitwise OR
        part_mask = QUERY_RESULTS | QUERY_COUNT | LAST_UPDATED_ON

        result = query_part_mask(query="SELECT * FROM syn1234", part_mask=part_mask)
        print(result)
        ```
    """
    # Replaced at runtime
    return QueryResultBundle(result=None)

add_column ¶

add_column(column: Union[Column, List[Column]], index: int = None) -> None

Add column(s) to the table. Note that this does not store the column(s) in Synapse. You must call the .store() function on this table class instance to store the column(s) in Synapse. This is a convenience function to eliminate the need to manually add the column(s) to the dictionary.

This function will add an item to the .columns attribute of this class instance. .columns is a dictionary where the key is the name of the column and the value is the Column object.

PARAMETER	DESCRIPTION
`column`	The column(s) to add, may be a single Column object or a list of Column objects. TYPE: `Union[Column, List[Column]]`
`index`	The index to insert the column at. If not passed in the column will be added to the end of the list. TYPE: `int` DEFAULT: `None`

RETURNS	DESCRIPTION
`None`	None

Adding a single column

This example shows how you may add a single column to a table and then store the change back in Synapse.

from synapseclient import Synapse
from synapseclient.models import Column, ColumnType, Table

syn = Synapse()
syn.login()

table = Table(
    id="syn1234"
).get(include_columns=True)

table.add_column(
    Column(name="my_column", column_type=ColumnType.STRING)
)
table.store()

Adding multiple columns

This example shows how you may add multiple columns to a table and then store the change back in Synapse.

from synapseclient import Synapse
from synapseclient.models import Column, ColumnType, Table

syn = Synapse()
syn.login()

table = Table(
    id="syn1234"
).get(include_columns=True)

table.add_column([
    Column(name="my_column", column_type=ColumnType.STRING),
    Column(name="my_column2", column_type=ColumnType.INTEGER),
])
table.store()

Adding a column at a specific index

This example shows how you may add a column at a specific index to a table and then store the change back in Synapse. If the index is out of bounds the column will be added to the end of the list.

from synapseclient import Synapse
from synapseclient.models import Column, ColumnType, Table

syn = Synapse()
syn.login()

table = Table(
    id="syn1234"
).get(include_columns=True)

table.add_column(
    Column(name="my_column", column_type=ColumnType.STRING),
    # Add the column at the beginning of the list
    index=0
)
table.store()

Adding a single column (async)

This example shows how you may add a single column to a table and then store the change back in Synapse.

import asyncio
from synapseclient import Synapse
from synapseclient.models import Column, ColumnType, Table

syn = Synapse()
syn.login()

async def main():
    table = await Table(
        id="syn1234"
    ).get_async(include_columns=True)

    table.add_column(
        Column(name="my_column", column_type=ColumnType.STRING)
    )
    await table.store_async()

asyncio.run(main())

Adding multiple columns (async)

This example shows how you may add multiple columns to a table and then store the change back in Synapse.

import asyncio
from synapseclient import Synapse
from synapseclient.models import Column, ColumnType, Table

syn = Synapse()
syn.login()

async def main():
    table = await Table(
        id="syn1234"
    ).get_async(include_columns=True)

    table.add_column([
        Column(name="my_column", column_type=ColumnType.STRING),
        Column(name="my_column2", column_type=ColumnType.INTEGER),
    ])
    await table.store_async()

asyncio.run(main())

Adding a column at a specific index (async)

This example shows how you may add a column at a specific index to a table and then store the change back in Synapse. If the index is out of bounds the column will be added to the end of the list.

import asyncio
from synapseclient import Synapse
from synapseclient.models import Column, ColumnType, Table

syn = Synapse()
syn.login()

async def main():
    table = await Table(
        id="syn1234"
    ).get_async(include_columns=True)

    table.add_column(
        Column(name="my_column", column_type=ColumnType.STRING),
        # Add the column at the beginning of the list
        index=0
    )
    await table.store_async()

asyncio.run(main())

Source code in synapseclient/models/mixins/table_components.py

def add_column(
    self, column: Union["Column", List["Column"]], index: int = None
) -> None:
    """Add column(s) to the table. Note that this does not store the column(s) in
    Synapse. You must call the `.store()` function on this table class instance to
    store the column(s) in Synapse. This is a convenience function to eliminate
    the need to manually add the column(s) to the dictionary.


    This function will add an item to the `.columns` attribute of this class
    instance. `.columns` is a dictionary where the key is the name of the column
    and the value is the Column object.

    Arguments:
        column: The column(s) to add, may be a single Column object or a list of
            Column objects.
        index: The index to insert the column at. If not passed in the column will
            be added to the end of the list.

    Returns:
        None

    Example: Adding a single column
        This example shows how you may add a single column to a table and then store
        the change back in Synapse.

        ```python
        from synapseclient import Synapse
        from synapseclient.models import Column, ColumnType, Table

        syn = Synapse()
        syn.login()

        table = Table(
            id="syn1234"
        ).get(include_columns=True)

        table.add_column(
            Column(name="my_column", column_type=ColumnType.STRING)
        )
        table.store()
        ```


    Example: Adding multiple columns
        This example shows how you may add multiple columns to a table and then store
        the change back in Synapse.

        ```python
        from synapseclient import Synapse
        from synapseclient.models import Column, ColumnType, Table

        syn = Synapse()
        syn.login()

        table = Table(
            id="syn1234"
        ).get(include_columns=True)

        table.add_column([
            Column(name="my_column", column_type=ColumnType.STRING),
            Column(name="my_column2", column_type=ColumnType.INTEGER),
        ])
        table.store()
        ```

    Example: Adding a column at a specific index
        This example shows how you may add a column at a specific index to a table
        and then store the change back in Synapse. If the index is out of bounds the
        column will be added to the end of the list.

        ```python
        from synapseclient import Synapse
        from synapseclient.models import Column, ColumnType, Table

        syn = Synapse()
        syn.login()

        table = Table(
            id="syn1234"
        ).get(include_columns=True)

        table.add_column(
            Column(name="my_column", column_type=ColumnType.STRING),
            # Add the column at the beginning of the list
            index=0
        )
        table.store()
        ```

    Example: Adding a single column (async)
        This example shows how you may add a single column to a table and then store
        the change back in Synapse.

        ```python
        import asyncio
        from synapseclient import Synapse
        from synapseclient.models import Column, ColumnType, Table

        syn = Synapse()
        syn.login()

        async def main():
            table = await Table(
                id="syn1234"
            ).get_async(include_columns=True)

            table.add_column(
                Column(name="my_column", column_type=ColumnType.STRING)
            )
            await table.store_async()

        asyncio.run(main())
        ```

    Example: Adding multiple columns (async)
        This example shows how you may add multiple columns to a table and then store
        the change back in Synapse.

        ```python
        import asyncio
        from synapseclient import Synapse
        from synapseclient.models import Column, ColumnType, Table

        syn = Synapse()
        syn.login()

        async def main():
            table = await Table(
                id="syn1234"
            ).get_async(include_columns=True)

            table.add_column([
                Column(name="my_column", column_type=ColumnType.STRING),
                Column(name="my_column2", column_type=ColumnType.INTEGER),
            ])
            await table.store_async()

        asyncio.run(main())
        ```

    Example: Adding a column at a specific index (async)
        This example shows how you may add a column at a specific index to a table
        and then store the change back in Synapse. If the index is out of bounds the
        column will be added to the end of the list.

        ```python
        import asyncio
        from synapseclient import Synapse
        from synapseclient.models import Column, ColumnType, Table

        syn = Synapse()
        syn.login()

        async def main():
            table = await Table(
                id="syn1234"
            ).get_async(include_columns=True)

            table.add_column(
                Column(name="my_column", column_type=ColumnType.STRING),
                # Add the column at the beginning of the list
                index=0
            )
            await table.store_async()

        asyncio.run(main())
        ```
    """
    if not self._last_persistent_instance:
        raise ValueError(
            "This method is only supported after interacting with Synapse via a `.get()` or `.store()` operation"
        )

    if index is not None:
        if isinstance(column, list):
            columns_to_insert = []
            for i, col in enumerate(column):
                if col.name in self.columns:
                    raise ValueError(f"Duplicate column name: {col.name}")
                columns_to_insert.append((col.name, col))
            insert_index = min(index, len(self.columns))
            self.columns = OrderedDict(
                list(self.columns.items())[:insert_index]
                + columns_to_insert
                + list(self.columns.items())[insert_index:]
            )
        else:
            if column.name in self.columns:
                raise ValueError(f"Duplicate column name: {column.name}")
            insert_index = min(index, len(self.columns))
            self.columns = OrderedDict(
                list(self.columns.items())[:insert_index]
                + [(column.name, column)]
                + list(self.columns.items())[insert_index:]
            )

    else:
        if isinstance(column, list):
            for col in column:
                if col.name in self.columns:
                    raise ValueError(f"Duplicate column name: {col.name}")
                self.columns[col.name] = col
        else:
            if column.name in self.columns:
                raise ValueError(f"Duplicate column name: {column.name}")
            self.columns[column.name] = column

delete_column ¶

delete_column(name: str) -> None

Mark a column for deletion. Note that this does not delete the column from Synapse. You must call the .store() function on this table class instance to delete the column from Synapse. This is a convenience function to eliminate the need to manually delete the column from the dictionary and add it to the ._columns_to_delete attribute.

PARAMETER	DESCRIPTION
`name`	The name of the column to delete. TYPE: `str`

RETURNS	DESCRIPTION
`None`	None

Deleting a column

This example shows how you may delete a column from a table and then store the change back in Synapse.

from synapseclient import Synapse
from synapseclient.models import Table

syn = Synapse()
syn.login()

table = Table(
    id="syn1234"
).get(include_columns=True)

table.delete_column(name="my_column")
table.store()

Deleting a column (async)

This example shows how you may delete a column from a table and then store the change back in Synapse.

import asyncio
from synapseclient import Synapse
from synapseclient.models import Table

syn = Synapse()
syn.login()

async def main():
    table = await Table(
        id="syn1234"
    ).get_async(include_columns=True)

    table.delete_column(name="my_column")
    table.store_async()

asyncio.run(main())

Source code in synapseclient/models/mixins/table_components.py

def delete_column(self, name: str) -> None:
    """
    Mark a column for deletion. Note that this does not delete the column from
    Synapse. You must call the `.store()` function on this table class instance to
    delete the column from Synapse. This is a convenience function to eliminate
    the need to manually delete the column from the dictionary and add it to the
    `._columns_to_delete` attribute.

    Arguments:
        name: The name of the column to delete.

    Returns:
        None

    Example: Deleting a column
        This example shows how you may delete a column from a table and then store
        the change back in Synapse.

        ```python
        from synapseclient import Synapse
        from synapseclient.models import Table

        syn = Synapse()
        syn.login()

        table = Table(
            id="syn1234"
        ).get(include_columns=True)

        table.delete_column(name="my_column")
        table.store()
        ```

    Example: Deleting a column (async)
        This example shows how you may delete a column from a table and then store
        the change back in Synapse.

        ```python
        import asyncio
        from synapseclient import Synapse
        from synapseclient.models import Table

        syn = Synapse()
        syn.login()

        async def main():
            table = await Table(
                id="syn1234"
            ).get_async(include_columns=True)

            table.delete_column(name="my_column")
            table.store_async()

        asyncio.run(main())
        ```
    """
    if not self._last_persistent_instance:
        raise ValueError(
            "This method is only supported after interacting with Synapse via a `.get()` or `.store()` operation"
        )
    if not self.columns:
        raise ValueError(
            "There are no columns. Make sure you use the `include_columns` parameter in the `.get()` method."
        )

    column_to_delete = self.columns.get(name, None)
    if not column_to_delete:
        raise ValueError(f"Column with name {name} does not exist in the table.")

    self._columns_to_delete[column_to_delete.id] = column_to_delete
    self.columns.pop(column_to_delete.name, None)

reorder_column ¶

reorder_column(name: str, index: int) -> None

Reorder a column in the table. Note that this does not store the column in Synapse. You must call the .store() function on this table class instance to store the column in Synapse. This is a convenience function to eliminate the need to manually reorder the .columns attribute dictionary.

You must ensure that the index is within the bounds of the number of columns in the table. If you pass in an index that is out of bounds the column will be added to the end of the list.

PARAMETER	DESCRIPTION
`name`	The name of the column to reorder. TYPE: `str`
`index`	The index to move the column to starting with 0. TYPE: `int`

RETURNS	DESCRIPTION
`None`	None

Reordering a column

This example shows how you may reorder a column in a table and then store the change back in Synapse.

from synapseclient import Synapse
from synapseclient.models import Column, ColumnType, Table

syn = Synapse()
syn.login()

table = Table(
    id="syn1234"
).get(include_columns=True)

# Move the column to the beginning of the list
table.reorder_column(name="my_column", index=0)
table.store()

Reordering a column (async)

This example shows how you may reorder a column in a table and then store the change back in Synapse.

import asyncio
from synapseclient import Synapse
from synapseclient.models import Column, ColumnType, Table

syn = Synapse()
syn.login()

async def main():
    table = await Table(
        id="syn1234"
    ).get_async(include_columns=True)

    # Move the column to the beginning of the list
    table.reorder_column(name="my_column", index=0)
    table.store_async()

asyncio.run(main())

Source code in synapseclient/models/mixins/table_components.py

def reorder_column(self, name: str, index: int) -> None:
    """Reorder a column in the table. Note that this does not store the column in
    Synapse. You must call the `.store()` function on this table class instance to
    store the column in Synapse. This is a convenience function to eliminate
    the need to manually reorder the `.columns` attribute dictionary.

    You must ensure that the index is within the bounds of the number of columns in
    the table. If you pass in an index that is out of bounds the column will be
    added to the end of the list.

    Arguments:
        name: The name of the column to reorder.
        index: The index to move the column to starting with 0.

    Returns:
        None

    Example: Reordering a column
        This example shows how you may reorder a column in a table and then store
        the change back in Synapse.

        ```python
        from synapseclient import Synapse
        from synapseclient.models import Column, ColumnType, Table

        syn = Synapse()
        syn.login()

        table = Table(
            id="syn1234"
        ).get(include_columns=True)

        # Move the column to the beginning of the list
        table.reorder_column(name="my_column", index=0)
        table.store()
        ```


    Example: Reordering a column (async)
        This example shows how you may reorder a column in a table and then store
        the change back in Synapse.

        ```python
        import asyncio
        from synapseclient import Synapse
        from synapseclient.models import Column, ColumnType, Table

        syn = Synapse()
        syn.login()

        async def main():
            table = await Table(
                id="syn1234"
            ).get_async(include_columns=True)

            # Move the column to the beginning of the list
            table.reorder_column(name="my_column", index=0)
            table.store_async()

        asyncio.run(main())
        ```
    """
    if not self._last_persistent_instance:
        raise ValueError(
            "This method is only supported after interacting with Synapse via a `.get()` or `.store()` operation"
        )

    column_to_reorder = self.columns.pop(name, None)
    if index >= len(self.columns):
        self.columns[name] = column_to_reorder
        return self

    self.columns = OrderedDict(
        list(self.columns.items())[:index]
        + [(name, column_to_reorder)]
        + list(self.columns.items())[index:]
    )

get_permissions ¶

get_permissions(*, synapse_client: Optional[Synapse] = None) -> Permissions

Get the permissions that the caller has on an Entity.

PARAMETER	DESCRIPTION
`synapse_client`	If not passed in and caching was not disabled by `Synapse.allow_client_caching(False)` this will use the last created instance from the Synapse class constructor. TYPE: `Optional[Synapse]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Permissions`	A Permissions object

Using this function:

Getting permissions for a Synapse Entity

from synapseclient import Synapse
from synapseclient.models import File

syn = Synapse()
syn.login()

permissions = File(id="syn123").get_permissions()

Getting access types list from the Permissions object

permissions.access_types

Source code in synapseclient/models/protocols/access_control_protocol.py

def get_permissions(
    self,
    *,
    synapse_client: Optional[Synapse] = None,
) -> "Permissions":
    """
    Get the [permissions][synapseclient.core.models.permission.Permissions]
    that the caller has on an Entity.

    Arguments:
        synapse_client: If not passed in and caching was not disabled by
            `Synapse.allow_client_caching(False)` this will use the last created
            instance from the Synapse class constructor.

    Returns:
        A Permissions object


    Example: Using this function:
        Getting permissions for a Synapse Entity

        ```python
        from synapseclient import Synapse
        from synapseclient.models import File

        syn = Synapse()
        syn.login()

        permissions = File(id="syn123").get_permissions()
        ```

        Getting access types list from the Permissions object

        ```
        permissions.access_types
        ```
    """
    return self

get_acl ¶

get_acl(principal_id: int = None, *, synapse_client: Optional[Synapse] = None) -> List[str]

Get the ACL that a user or group has on an Entity.

PARAMETER	DESCRIPTION
`principal_id`	Identifier of a user or group (defaults to PUBLIC users) TYPE: `int` DEFAULT: `None`
`synapse_client`	If not passed in and caching was not disabled by `Synapse.allow_client_caching(False)` this will use the last created instance from the Synapse class constructor. TYPE: `Optional[Synapse]` DEFAULT: `None`

RETURNS	DESCRIPTION
`List[str]`	An array containing some combination of ['READ', 'UPDATE', 'CREATE', 'DELETE', 'DOWNLOAD', 'MODERATE', 'CHANGE_PERMISSIONS', 'CHANGE_SETTINGS'] or an empty array

Source code in synapseclient/models/protocols/access_control_protocol.py

def get_acl(
    self, principal_id: int = None, *, synapse_client: Optional[Synapse] = None
) -> List[str]:
    """
    Get the [ACL][synapseclient.core.models.permission.Permissions.access_types]
    that a user or group has on an Entity.

    Arguments:
        principal_id: Identifier of a user or group (defaults to PUBLIC users)
        synapse_client: If not passed in and caching was not disabled by
            `Synapse.allow_client_caching(False)` this will use the last created
            instance from the Synapse class constructor.

    Returns:
        An array containing some combination of
            ['READ', 'UPDATE', 'CREATE', 'DELETE', 'DOWNLOAD', 'MODERATE',
            'CHANGE_PERMISSIONS', 'CHANGE_SETTINGS']
            or an empty array
    """
    return [""]

set_permissions ¶

set_permissions(principal_id: int = None, access_type: List[str] = None, modify_benefactor: bool = False, warn_if_inherits: bool = True, overwrite: bool = True, *, synapse_client: Optional[Synapse] = None) -> Dict[str, Union[str, list]]

Sets permission that a user or group has on an Entity. An Entity may have its own ACL or inherit its ACL from a benefactor.

PARAMETER	DESCRIPTION
`principal_id`	Identifier of a user or group. `273948` is for all registered Synapse users and `273949` is for public access. None implies public access. TYPE: `int` DEFAULT: `None`
`access_type`	Type of permission to be granted. One or more of CREATE, READ, DOWNLOAD, UPDATE, DELETE, CHANGE_PERMISSIONS. Defaults to ['READ', 'DOWNLOAD'] TYPE: `List[str]` DEFAULT: `None`
`modify_benefactor`	Set as True when modifying a benefactor's ACL. The term 'benefactor' is used to indicate which Entity an Entity inherits its ACL from. For example, a newly created Project will be its own benefactor, while a new FileEntity's benefactor will start off as its containing Project. If the entity already has local sharing settings the benefactor would be itself. It may also be the immediate parent, somewhere in the parent tree, or the project itself. TYPE: `bool` DEFAULT: `False`
`warn_if_inherits`	When `modify_benefactor` is True, this does not have any effect. When `modify_benefactor` is False, and `warn_if_inherits` is True, a warning log message is produced if the benefactor for the entity you passed into the function is not itself, i.e., it's the parent folder, or another entity in the parent tree. TYPE: `bool` DEFAULT: `True`
`overwrite`	By default this function overwrites existing permissions for the specified user. Set this flag to False to add new permissions non-destructively. TYPE: `bool` DEFAULT: `True`
`synapse_client`	If not passed in and caching was not disabled by `Synapse.allow_client_caching(False)` this will use the last created instance from the Synapse class constructor. TYPE: `Optional[Synapse]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Dict[str, Union[str, list]]`	An Access Control List object

Setting permissions

Grant all registered users download access

from synapseclient import Synapse
from synapseclient.models import File

syn = Synapse()
syn.login()

File(id="syn123").set_permissions(principal_id=273948, access_type=['READ','DOWNLOAD'])

Grant the public view access

from synapseclient import Synapse
from synapseclient.models import File

syn = Synapse()
syn.login()

File(id="syn123").set_permissions(principal_id=273949, access_type=['READ'])

Source code in synapseclient/models/protocols/access_control_protocol.py

def set_permissions(
    self,
    principal_id: int = None,
    access_type: List[str] = None,
    modify_benefactor: bool = False,
    warn_if_inherits: bool = True,
    overwrite: bool = True,
    *,
    synapse_client: Optional[Synapse] = None,
) -> Dict[str, Union[str, list]]:
    """
    Sets permission that a user or group has on an Entity.
    An Entity may have its own ACL or inherit its ACL from a benefactor.

    Arguments:
        principal_id: Identifier of a user or group. `273948` is for all
            registered Synapse users and `273949` is for public access.
            None implies public access.
        access_type: Type of permission to be granted. One or more of CREATE,
            READ, DOWNLOAD, UPDATE, DELETE, CHANGE_PERMISSIONS.

            **Defaults to ['READ', 'DOWNLOAD']**
        modify_benefactor: Set as True when modifying a benefactor's ACL. The term
            'benefactor' is used to indicate which Entity an Entity inherits its
            ACL from. For example, a newly created Project will be its own
            benefactor, while a new FileEntity's benefactor will start off as its
            containing Project. If the entity already has local sharing settings
            the benefactor would be itself. It may also be the immediate parent,
            somewhere in the parent tree, or the project itself.
        warn_if_inherits: When `modify_benefactor` is True, this does not have any
            effect. When `modify_benefactor` is False, and `warn_if_inherits` is
            True, a warning log message is produced if the benefactor for the
            entity you passed into the function is not itself, i.e., it's the
            parent folder, or another entity in the parent tree.
        overwrite: By default this function overwrites existing permissions for
            the specified user. Set this flag to False to add new permissions
            non-destructively.
        synapse_client: If not passed in and caching was not disabled by
            `Synapse.allow_client_caching(False)` this will use the last created
            instance from the Synapse class constructor.

    Returns:
        An Access Control List object

    Example: Setting permissions
        Grant all registered users download access

        ```python
        from synapseclient import Synapse
        from synapseclient.models import File

        syn = Synapse()
        syn.login()

        File(id="syn123").set_permissions(principal_id=273948, access_type=['READ','DOWNLOAD'])
        ```

        Grant the public view access

        ```python
        from synapseclient import Synapse
        from synapseclient.models import File

        syn = Synapse()
        syn.login()

        File(id="syn123").set_permissions(principal_id=273949, access_type=['READ'])
        ```
    """
    return {}

synapseclient.models.EntityRef `dataclass` ¶

Represents a reference to the id and version of an entity to be used in Dataset and DatasetCollection objects.

ATTRIBUTE	DESCRIPTION
`id`	The Synapse ID of the entity. TYPE: `str`
`version`	Indicates a specific version of the entity. TYPE: `int`

Source code in synapseclient/models/dataset.py

@dataclass
class EntityRef:
    """
    Represents a reference to the id and version of an entity to be used in `Dataset` and
    `DatasetCollection` objects.

    Attributes:
        id: The Synapse ID of the entity.
        version: Indicates a specific version of the entity.
    """

    id: str
    """The Synapse ID of the entity."""

    version: int
    """Indicates a specific version of the entity."""

    def to_synapse_request(self):
        """Converts the attributes of an EntityRef instance to a
        request expected of the Synapse REST API."""

        return {
            "entityId": self.id,
            "versionNumber": self.version,
        }

Attributes¶

id `instance-attribute` ¶

id: str

The Synapse ID of the entity.

version `instance-attribute` ¶

version: int

Indicates a specific version of the entity.

Functions¶

to_synapse_request ¶

to_synapse_request()

Converts the attributes of an EntityRef instance to a request expected of the Synapse REST API.

Source code in synapseclient/models/dataset.py

def to_synapse_request(self):
    """Converts the attributes of an EntityRef instance to a
    request expected of the Synapse REST API."""

    return {
        "entityId": self.id,
        "versionNumber": self.version,
    }

Dataset Collection¶

API reference¶

synapseclient.models.DatasetCollection dataclass ¶

Functions¶

add_item ¶

remove_item ¶

store ¶

get ¶

delete ¶

update_rows ¶

snapshot ¶

query staticmethod ¶

query_part_mask staticmethod ¶

add_column ¶

delete_column ¶

reorder_column ¶

get_permissions ¶

get_acl ¶

set_permissions ¶

synapseclient.models.EntityRef dataclass ¶

Attributes¶

id instance-attribute ¶

version instance-attribute ¶

Functions¶

to_synapse_request ¶

synapseclient.models.DatasetCollection `dataclass` ¶

query `staticmethod` ¶

query_part_mask `staticmethod` ¶

synapseclient.models.EntityRef `dataclass` ¶

id `instance-attribute` ¶

version `instance-attribute` ¶