VirtualTable¶

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.VirtualTable `dataclass` ¶

Bases: VirtualTableSynchronousProtocol, AccessControllable, TableBase, TableStoreMixin, DeleteMixin, GetMixin, QueryMixin

A virtual table is a type of table that is dynamically built from a Synapse SQL query. Its content is read only and based off the defining_sql attribute. The SQL of the virtual table may NOT contain JOIN or UNION clauses and must reference a table that has a non-empty schema.

A VirtualTable object represents this VirtualTable API model in Synapse: https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/table/VirtualTable.html

ATTRIBUTE	DESCRIPTION
`id`	The unique immutable ID for this entity. Once issued, this ID is guaranteed to never change or be re-issued. TYPE: `Optional[str]`
`name`	The name of this entity. 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 this entity. 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 entity was created. TYPE: `Optional[str]`
`modified_on`	The date this entity 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 entity. TYPE: `Optional[str]`
`modified_by`	The ID of the user that last modified this entity. TYPE: `Optional[str]`
`parent_id`	The ID of the Entity that is the parent of this entity. TYPE: `Optional[str]`
`version_number`	The version number issued to this version on the object. TYPE: `Optional[int]`
`version_label`	The version label for this entity. TYPE: `Optional[str]`
`version_comment`	The version comment for this entity. TYPE: `Optional[str]`
`is_latest_version`	If this is the latest version of the object. TYPE: `Optional[bool]`
`columns`	(Read Only) The columns of a virtual table are dynamic based on the select statement of the definingSQL. This list of columnIds is for read-only purposes. TYPE: `Optional[OrderedDict[str, Column]]`
`is_search_enabled`	When creating or updating a table or view specifies if full text search should be enabled. TYPE: `Optional[bool]`
`defining_sql`	The synapse SQL statement that defines the data in the virtual table. This field may NOT contain JOIN or UNION clauses. If a JOIN or UNION clause is present, a `ValueError` will be raised when the `store` method is called. TYPE: `Optional[str]`
`annotations`	Additional metadata associated with the entityview. 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. To remove all annotations set this to an empty dict `{}` or None and store the entity. TYPE: `Optional[Dict[str, Union[List[str], List[bool], List[float], List[int], List[date], List[datetime]]]]`
`activity`	The Activity model represents the main record of Provenance in Synapse. TYPE: `Optional[Activity]`

Create a new virtual table with a defining SQL query.

from synapseclient import Synapse
from synapseclient.models import VirtualTable

syn = Synapse()
syn.login()

virtual_table = VirtualTable(
    name="My Virtual Table",
    description="A test virtual table",
    parent_id="syn12345",
    defining_sql="SELECT * FROM syn67890"
)
virtual_table = virtual_table.store()
print(f"Created Virtual Table with ID: {virtual_table.id}")

Update the defining SQL of an existing virtual table.

from synapseclient import Synapse
from synapseclient.models import VirtualTable

syn = Synapse()
syn.login()

virtual_table = VirtualTable(id="syn12345").get()
virtual_table.defining_sql = "SELECT column1, column2 FROM syn67890"
virtual_table = virtual_table.store()
print("Updated Virtual Table defining SQL.")

Delete a virtual table.

from synapseclient import Synapse
from synapseclient.models import VirtualTable

syn = Synapse()
syn.login()

virtual_table = VirtualTable(id="syn12345")
virtual_table.delete()
print("Deleted Virtual Table.")

Query data from a virtual table.

from synapseclient import Synapse
from synapseclient.models import query

syn = Synapse()
syn.login()

query_result = query("SELECT * FROM syn66080386")
print(query_result)

Source code in synapseclient/models/virtualtable.py

@dataclass
@async_to_sync
class VirtualTable(
    VirtualTableSynchronousProtocol,
    AccessControllable,
    TableBase,
    TableStoreMixin,
    DeleteMixin,
    GetMixin,
    QueryMixin,
):
    """
    A virtual table is a type of table that is dynamically built from a Synapse
    SQL query. Its content is read only and based off the `defining_sql` attribute.
    The SQL of the virtual table may NOT contain JOIN or UNION clauses and must
    reference a table that has a non-empty schema.

    A `VirtualTable` object represents this `VirtualTable` API model in Synapse:
    <https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/table/VirtualTable.html>

    Attributes:
        id: The unique immutable ID for this entity. Once issued, this ID is
            guaranteed to never change or be re-issued.
        name: The name of this entity. 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 this entity. 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 entity was created.
        modified_on: The date this entity was last modified. In YYYY-MM-DD-Thh:mm:ss.sssZ
            format.
        created_by: The ID of the user that created this entity.
        modified_by: The ID of the user that last modified this entity.
        parent_id: The ID of the Entity that is the parent of this entity.
        version_number: The version number issued to this version on the object.
        version_label: The version label for this entity.
        version_comment: The version comment for this entity.
        is_latest_version: If this is the latest version of the object.
        columns: (Read Only) The columns of a virtual table are dynamic based on
            the select statement of the definingSQL. This list of columnIds is for
            read-only purposes.
        is_search_enabled: When creating or updating a table or view specifies if full
            text search should be enabled.
        defining_sql: The synapse SQL statement that defines the data in the
            virtual table. This field may NOT contain JOIN or UNION clauses.
            If a JOIN or UNION clause is present, a `ValueError` will be raised
            when the `store` method is called.
        annotations: Additional metadata associated with the entityview. 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. To remove all
            annotations set this to an empty dict `{}` or None and store the entity.
        activity: The Activity model represents the main record of Provenance in
            Synapse.

    Example: Create a new virtual table with a defining SQL query.
        &nbsp;

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

        syn = Synapse()
        syn.login()

        virtual_table = VirtualTable(
            name="My Virtual Table",
            description="A test virtual table",
            parent_id="syn12345",
            defining_sql="SELECT * FROM syn67890"
        )
        virtual_table = virtual_table.store()
        print(f"Created Virtual Table with ID: {virtual_table.id}")
        ```

    Example: Update the defining SQL of an existing virtual table.
        &nbsp;

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

        syn = Synapse()
        syn.login()

        virtual_table = VirtualTable(id="syn12345").get()
        virtual_table.defining_sql = "SELECT column1, column2 FROM syn67890"
        virtual_table = virtual_table.store()
        print("Updated Virtual Table defining SQL.")
        ```

    Example: Delete a virtual table.
        &nbsp;

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

        syn = Synapse()
        syn.login()

        virtual_table = VirtualTable(id="syn12345")
        virtual_table.delete()
        print("Deleted Virtual Table.")
        ```

    Example: Query data from a virtual table.
        &nbsp;

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

        syn = Synapse()
        syn.login()

        query_result = query("SELECT * FROM syn66080386")
        print(query_result)
        ```
    """

    id: Optional[str] = None
    """The unique immutable ID for this entity. Once issued, this ID is
    guaranteed to never change or be re-issued."""

    name: Optional[str] = None
    """The name of this entity. 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 entity was created."""

    modified_on: Optional[str] = field(default=None, compare=False)
    """The date this entity 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 entity."""

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

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

    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 entity."""

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

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

    columns: Optional[OrderedDict[str, Column]] = field(
        default_factory=OrderedDict, compare=False
    )
    """(Read Only) The columns of a virtual table are dynamic based on
    the select statement of the definingSQL. This list of columnIds is for
    read-only purposes."""

    is_search_enabled: Optional[bool] = None
    """When creating or updating a table or view specifies if full text search
    should be enabled."""

    defining_sql: Optional[str] = None
    """The synapse SQL statement that defines the data in the virtual
    table. This field may NOT contain JOIN or UNION clauses. If a JOIN or UNION
    clause is present, a `ValueError` will be raised when the `store`
    method is called."""

    _last_persistent_instance: Optional["VirtualTable"] = 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."""

    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 entityview. 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. To remove all annotations set this
    to an empty dict `{}` or None and store the entity."""

    activity: Optional[Activity] = field(default=None, compare=False)
    """The Activity model represents the main record of Provenance in
    Synapse."""

    @property
    def has_changed(self) -> bool:
        """Checks if the object has changed since the last persistent instance."""
        return self._last_persistent_instance != self

    def _set_last_persistent_instance(self) -> None:
        """Stash the last time this object interacted with Synapse."""
        del self._last_persistent_instance
        self._last_persistent_instance = replace(self)
        self._last_persistent_instance.activity = (
            replace(self.activity) if self.activity and self.activity.id else None
        )
        self._last_persistent_instance.annotations = (
            deepcopy(self.annotations) if self.annotations else {}
        )

    def fill_from_dict(
        self, entity: Dict[str, Any], set_annotations: bool = True
    ) -> "VirtualTable":
        """
        Converts the data coming from the Synapse API into this datamodel.

        Arguments:
            entity: The data coming from the Synapse API

        Returns:
            The VirtualTable 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.defining_sql = entity.get("definingSQL", None)

        if set_annotations:
            self.annotations = entity.get("annotations", {})

        return self

    def to_synapse_request(self) -> Dict[str, Any]:
        """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.VIRTUAL_TABLE,
            "versionNumber": self.version_number,
            "versionLabel": self.version_label,
            "versionComment": self.version_comment,
            "isLatestVersion": self.is_latest_version,
            "isSearchEnabled": self.is_search_enabled,
            "definingSQL": self.defining_sql,
        }
        delete_none_keys(entity)
        result = {
            "entity": entity,
        }
        delete_none_keys(result)
        return result

    async def store_async(
        self,
        dry_run: bool = False,
        *,
        job_timeout: int = 600,
        synapse_client: Optional[Synapse] = None,
    ) -> "Self":
        """
        Asynchronously store metadata about a VirtualTable including the annotations.

        Note: Columns and rows in a VirtualTable are determined by the `defining_sql` attribute. To update
        the columns, you must update the `defining_sql` and store the view.

        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 VirtualTable instance stored in synapse.

        Raises:
            ValueError: If the defining_sql contains JOIN or UNION operations,
                which are not supported in VirtualTables.

        Raises:
            ValueError: If the defining_sql attribute is not set.

        Example: Create a new virtual table with a defining SQL query.
            &nbsp;

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

            async def main():
                syn = Synapse()
                await syn.login_async()

                virtual_table = VirtualTable(
                    name="My Virtual Table",
                    description="A test virtual table",
                    parent_id="syn12345",
                    defining_sql="SELECT * FROM syn67890"
                )
                virtual_table = await virtual_table.store_async()
                print(f"Created Virtual Table with ID: {virtual_table.id}")

            asyncio.run(main())
            ```
        """
        # Check for unsupported operations in defining_sql

        if self.defining_sql:
            sql_upper = self.defining_sql.upper()
            join_union_pattern = r"(?:^|\s)(?:JOIN|UNION)(?:\s|$)"

            if re.search(join_union_pattern, sql_upper):
                raise ValueError(
                    "VirtualTables do not support JOIN or UNION operations in the defining_sql. "
                    "If you need to combine data from multiple tables, consider using a MaterializedView instead."
                )
        else:
            raise ValueError(
                "The defining_sql attribute must be set for a VirtualTable."
            )

        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":
        """
        Asynchronously get the metadata about the VirtualTable 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 VirtualTable
                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 VirtualTable instance stored in synapse.

        Example: Retrieve a virtual table by ID.
            &nbsp;

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

            async def main():
                syn = Synapse()
                await syn.login_async()

                virtual_table = await VirtualTable(id="syn12345").get_async()
                print(virtual_table)

            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:
        """
        Asynchronously delete the virtual table from synapse. This is not version specific. If you'd like
        to delete a specific version of the virtual table 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.

        Example: Delete a virtual table.
            &nbsp;

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

            async def main():
                syn = Synapse()
                await syn.login_async()

                virtual_table = VirtualTable(id="syn12345")
                await virtual_table.delete_async()
                print("Deleted Virtual Table.")

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

Functions¶

store ¶

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

Store metadata about a VirtualTable including the annotations.

Note: Columns and rows in a VirtualTable are determined by the defining_sql attribute. To update the columns, you must update the defining_sql and store the view.

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 VirtualTable instance stored in synapse.

RAISES	DESCRIPTION
`ValueError`	If the defining_sql contains JOIN or UNION operations, which are not supported in VirtualTables.

Create a new virtual table with a defining SQL query.

from synapseclient import Synapse
from synapseclient.models import VirtualTable

syn = Synapse()
syn.login()

virtual_table = VirtualTable(
    name="My Virtual Table",
    description="A test virtual table",
    parent_id="syn12345",
    defining_sql="SELECT * FROM syn67890"
)
virtual_table = virtual_table.store()
print(f"Created Virtual Table with ID: {virtual_table.id}")

Update the defining SQL of an existing virtual table.

from synapseclient import Synapse
from synapseclient.models import VirtualTable

syn = Synapse()
syn.login()

virtual_table = VirtualTable(id="syn12345").get()
virtual_table.defining_sql = "SELECT column1, column2 FROM syn67890"
virtual_table = virtual_table.store()
print("Updated Virtual Table defining SQL.")

Source code in synapseclient/models/virtualtable.py

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

    Note: Columns and rows in a VirtualTable are determined by the `defining_sql` attribute. To update
    the columns, you must update the `defining_sql` and store the view.

    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 VirtualTable instance stored in synapse.

    Raises:
        ValueError: If the defining_sql contains JOIN or UNION operations,
            which are not supported in VirtualTables.

    Example: Create a new virtual table with a defining SQL query.
        &nbsp;

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

        syn = Synapse()
        syn.login()

        virtual_table = VirtualTable(
            name="My Virtual Table",
            description="A test virtual table",
            parent_id="syn12345",
            defining_sql="SELECT * FROM syn67890"
        )
        virtual_table = virtual_table.store()
        print(f"Created Virtual Table with ID: {virtual_table.id}")
        ```

    Example: Update the defining SQL of an existing virtual table.
        &nbsp;

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

        syn = Synapse()
        syn.login()

        virtual_table = VirtualTable(id="syn12345").get()
        virtual_table.defining_sql = "SELECT column1, column2 FROM syn67890"
        virtual_table = virtual_table.store()
        print("Updated Virtual Table defining SQL.")
        ```
    """
    return self

get ¶

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

Get the metadata about the VirtualTable 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 VirtualTable 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 VirtualTable instance stored in synapse.

Getting metadata about a VirtualTable using id

Get a VirtualTable 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 VirtualTable

syn = Synapse()
syn.login()

virtual_table = VirtualTable(id="syn4567").get(include_activity=True)
print(virtual_table)

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

Getting metadata about a VirtualTable using name and parent_id

Get a VirtualTable 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 VirtualTable

syn = Synapse()
syn.login()

virtual_table = VirtualTable(name="my_virtual_table", parent_id="syn1234").get(
    include_columns=True,
    include_activity=True
)
print(virtual_table)
print(virtual_table.columns)
print(virtual_table.activity)

Source code in synapseclient/models/virtualtable.py

def get(
    self,
    include_columns: bool = True,
    include_activity: bool = False,
    *,
    synapse_client: Optional[Synapse] = None,
) -> "Self":
    """
    Get the metadata about the VirtualTable 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 VirtualTable
            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 VirtualTable instance stored in synapse.

    Example: Getting metadata about a VirtualTable using id
        Get a VirtualTable 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 VirtualTable

        syn = Synapse()
        syn.login()

        virtual_table = VirtualTable(id="syn4567").get(include_activity=True)
        print(virtual_table)

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

    Example: Getting metadata about a VirtualTable using name and parent_id
        Get a VirtualTable 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 VirtualTable

        syn = Synapse()
        syn.login()

        virtual_table = VirtualTable(name="my_virtual_table", parent_id="syn1234").get(
            include_columns=True,
            include_activity=True
        )
        print(virtual_table)
        print(virtual_table.columns)
        print(virtual_table.activity)
        ```
    """
    return self

delete ¶

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

Delete the virtual table from synapse. This is not version specific. If you'd like to delete a specific version of the virtual table 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`

Delete a virtual table.

from synapseclient import Synapse
from synapseclient.models import VirtualTable

syn = Synapse()
syn.login()

virtual_table = VirtualTable(id="syn12345")
virtual_table.delete()
print("Deleted Virtual Table.")

Source code in synapseclient/models/virtualtable.py

def delete(self, *, synapse_client: Optional[Synapse] = None) -> None:
    """Delete the virtual table from synapse. This is not version specific. If you'd like
    to delete a specific version of the virtual table 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.

    Example: Delete a virtual table.
        &nbsp;

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

        syn = Synapse()
        syn.login()

        virtual_table = VirtualTable(id="syn12345")
        virtual_table.delete()
        print("Deleted Virtual Table.")
        ```
    """
    return None

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, **kwargs) -> QueryResultOutput

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
`QueryResultOutput`	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,
    **kwargs,
) -> "QueryResultOutput":
    """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)
        ```
    """
    return QueryResultOutput()

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, check_benefactor: bool = True, *, synapse_client: Optional[Synapse] = None) -> List[str]

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

Note: If the entity does not have local sharing settings, or ACL set directly on it, this will look up the ACL on the benefactor of the entity. The benefactor is the entity that the current entity inherits its permissions from. The benefactor is usually the parent entity, but it can be any ancestor in the hierarchy. For example, a newly created Project will be its own benefactor, while a new FileEntity's benefactor will start off as its containing Project or Folder. If the entity already has local sharing settings, the benefactor would be itself.

PARAMETER	DESCRIPTION
`principal_id`	Identifier of a user or group (defaults to PUBLIC users) TYPE: `int` DEFAULT: `None`
`check_benefactor`	If True (default), check the benefactor for the entity to get the ACL. If False, only check the entity itself. This is useful for checking the ACL of an entity that has local sharing settings, but you want to check the ACL of the entity itself and not the benefactor it may inherit from. 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
`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,
    check_benefactor: bool = True,
    *,
    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.

    Note: If the entity does not have local sharing settings, or ACL set directly
    on it, this will look up the ACL on the benefactor of the entity. The
    benefactor is the entity that the current entity inherits its permissions from.
    The benefactor is usually the parent entity, but it can be any ancestor in the
    hierarchy. For example, a newly created Project will be its own benefactor,
    while a new FileEntity's benefactor will start off as its containing Project or
    Folder. If the entity already has local sharing settings, the benefactor would
    be itself.

    Arguments:
        principal_id: Identifier of a user or group (defaults to PUBLIC users)
        check_benefactor: If True (default), check the benefactor for the entity
            to get the ACL. If False, only check the entity itself.
            This is useful for checking the ACL of an entity that has local sharing
            settings, but you want to check the ACL of the entity itself and not
            the benefactor it may inherit from.
        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 {}

delete_permissions ¶

delete_permissions(include_self: bool = True, include_container_content: bool = False, recursive: bool = False, target_entity_types: Optional[List[str]] = None, dry_run: bool = False, show_acl_details: bool = True, show_files_in_containers: bool = True, *, benefactor_tracker: Optional[BenefactorTracker] = None, synapse_client: Optional[Synapse] = None) -> None

Delete the entire Access Control List (ACL) for a given Entity. This is not scoped to a specific user or group, but rather removes all permissions associated with the Entity. After this operation, the Entity will inherit permissions from its benefactor, which is typically its parent entity or the Project it belongs to.

In order to remove permissions for a specific user or group, you should use the set_permissions method with the access_type set to an empty list.

By default, Entities such as FileEntity and Folder inherit their permission from their containing Project. For such Entities the Project is the Entity's 'benefactor'. This permission inheritance can be overridden by creating an ACL for the Entity. When this occurs the Entity becomes its own benefactor and all permission are determined by its own ACL.

If the ACL of an Entity is deleted, then its benefactor will automatically be set to its parent's benefactor.

Special notice for Projects: The ACL for a Project cannot be deleted, you must individually update or revoke the permissions for each user or group.

PARAMETER	DESCRIPTION
`include_self`	If True (default), delete the ACL of the current entity. If False, skip deleting the ACL of the current entity. TYPE: `bool` DEFAULT: `True`
`include_container_content`	If True, delete ACLs from contents directly within containers (files and folders inside self). This must be set to True for recursive to have any effect. Defaults to False. TYPE: `bool` DEFAULT: `False`
`recursive`	If True and the entity is a container (e.g., Project or Folder), recursively process child containers. Note that this must be used with include_container_content=True to have any effect. Setting recursive=True with include_container_content=False will raise a ValueError. Only works on classes that support the `sync_from_synapse_async` method. TYPE: `bool` DEFAULT: `False`
`target_entity_types`	Specify which entity types to process when deleting ACLs. Allowed values are "folder" and "file" (case-insensitive). If None, defaults to ["folder", "file"]. This does not affect the entity type of the current entity, which is always processed if `include_self=True`. TYPE: `Optional[List[str]]` DEFAULT: `None`
`dry_run`	If True, log the changes that would be made instead of actually performing the deletions. When enabled, all ACL deletion operations are simulated and logged at info level. Defaults to False. TYPE: `bool` DEFAULT: `False`
`show_acl_details`	When dry_run=True, controls whether current ACL details are displayed for entities that will have their permissions changed. If True (default), shows detailed ACL information. If False, hides ACL details for cleaner output. Has no effect when dry_run=False. TYPE: `bool` DEFAULT: `True`
`show_files_in_containers`	When dry_run=True, controls whether files within containers are displayed in the preview. If True (default), shows all files. If False, hides files when their only change is benefactor inheritance (but still shows files with local ACLs being deleted). Has no effect when dry_run=False. TYPE: `bool` DEFAULT: `True`
`benefactor_tracker`	Optional tracker for managing benefactor relationships. Used for recursive functionality to track which entities will be affected TYPE: `Optional[BenefactorTracker]` 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
`None`	None

RAISES	DESCRIPTION
`ValueError`	If the entity does not have an ID or if an invalid entity type is provided.
`SynapseHTTPError`	If there are permission issues or if the entity already inherits permissions.
`Exception`	For any other errors that may occur during the process.

Note: The caller must be granted ACCESS_TYPE.CHANGE_PERMISSIONS on the Entity to call this method.

Delete permissions for a single entity

from synapseclient import Synapse
from synapseclient.models import File

syn = Synapse()
syn.login()

File(id="syn123").delete_permissions()

Delete permissions recursively for a folder and all its children

from synapseclient import Synapse
from synapseclient.models import Folder

syn = Synapse()
syn.login()

# Delete permissions for this folder only (does not affect children)
Folder(id="syn123").delete_permissions()

# Delete permissions for all files and folders directly within this folder,
# but not the folder itself
Folder(id="syn123").delete_permissions(
    include_self=False,
    include_container_content=True
)

# Delete permissions for all items in the entire hierarchy (folders and their files)
# Both recursive and include_container_content must be True
Folder(id="syn123").delete_permissions(
    recursive=True,
    include_container_content=True
)

# Delete permissions only for folder entities within this folder recursively
# and their contents
Folder(id="syn123").delete_permissions(
    recursive=True,
    include_container_content=True,
    target_entity_types=["folder"]
)

# Delete permissions only for files within this folder and all subfolders
Folder(id="syn123").delete_permissions(
    include_self=False,
    recursive=True,
    include_container_content=True,
    target_entity_types=["file"]
)

# Dry run example: Log what would be deleted without making changes
Folder(id="syn123").delete_permissions(
    recursive=True,
    include_container_content=True,
    dry_run=True
)

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

def delete_permissions(
    self,
    include_self: bool = True,
    include_container_content: bool = False,
    recursive: bool = False,
    target_entity_types: Optional[List[str]] = None,
    dry_run: bool = False,
    show_acl_details: bool = True,
    show_files_in_containers: bool = True,
    *,
    benefactor_tracker: Optional["BenefactorTracker"] = None,
    synapse_client: Optional[Synapse] = None,
) -> None:
    """
    Delete the entire Access Control List (ACL) for a given Entity. This is not
    scoped to a specific user or group, but rather removes all permissions
    associated with the Entity. After this operation, the Entity will inherit
    permissions from its benefactor, which is typically its parent entity or
    the Project it belongs to.

    In order to remove permissions for a specific user or group, you
    should use the `set_permissions` method with the `access_type` set to
    an empty list.

    By default, Entities such as FileEntity and Folder inherit their permission from
    their containing Project. For such Entities the Project is the Entity's 'benefactor'.
    This permission inheritance can be overridden by creating an ACL for the Entity.
    When this occurs the Entity becomes its own benefactor and all permission are
    determined by its own ACL.

    If the ACL of an Entity is deleted, then its benefactor will automatically be set
    to its parent's benefactor.

    **Special notice for Projects:** The ACL for a Project cannot be deleted, you
    must individually update or revoke the permissions for each user or group.

    Arguments:
        include_self: If True (default), delete the ACL of the current entity.
            If False, skip deleting the ACL of the current entity.
        include_container_content: If True, delete ACLs from contents directly within
            containers (files and folders inside self). This must be set to
            True for recursive to have any effect. Defaults to False.
        recursive: If True and the entity is a container (e.g., Project or Folder),
            recursively process child containers. Note that this must be used with
            include_container_content=True to have any effect. Setting recursive=True
            with include_container_content=False will raise a ValueError.
            Only works on classes that support the `sync_from_synapse_async` method.
        target_entity_types: Specify which entity types to process when deleting ACLs.
            Allowed values are "folder" and "file" (case-insensitive).
            If None, defaults to ["folder", "file"]. This does not affect the
            entity type of the current entity, which is always processed if
            `include_self=True`.
        dry_run: If True, log the changes that would be made instead of actually
            performing the deletions. When enabled, all ACL deletion operations are
            simulated and logged at info level. Defaults to False.
        show_acl_details: When dry_run=True, controls whether current ACL details are
            displayed for entities that will have their permissions changed. If True (default),
            shows detailed ACL information. If False, hides ACL details for cleaner output.
            Has no effect when dry_run=False.
        show_files_in_containers: When dry_run=True, controls whether files within containers
            are displayed in the preview. If True (default), shows all files. If False, hides
            files when their only change is benefactor inheritance (but still shows files with
            local ACLs being deleted). Has no effect when dry_run=False.
        benefactor_tracker: Optional tracker for managing benefactor relationships.
            Used for recursive functionality to track which entities will be affected
        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

    Raises:
        ValueError: If the entity does not have an ID or if an invalid entity type is provided.
        SynapseHTTPError: If there are permission issues or if the entity already inherits permissions.
        Exception: For any other errors that may occur during the process.

    Note: The caller must be granted ACCESS_TYPE.CHANGE_PERMISSIONS on the Entity to
    call this method.

    Example: Delete permissions for a single entity
        ```python
        from synapseclient import Synapse
        from synapseclient.models import File

        syn = Synapse()
        syn.login()

        File(id="syn123").delete_permissions()

        ```

    Example: Delete permissions recursively for a folder and all its children
        ```python
        from synapseclient import Synapse
        from synapseclient.models import Folder

        syn = Synapse()
        syn.login()

        # Delete permissions for this folder only (does not affect children)
        Folder(id="syn123").delete_permissions()

        # Delete permissions for all files and folders directly within this folder,
        # but not the folder itself
        Folder(id="syn123").delete_permissions(
            include_self=False,
            include_container_content=True
        )

        # Delete permissions for all items in the entire hierarchy (folders and their files)
        # Both recursive and include_container_content must be True
        Folder(id="syn123").delete_permissions(
            recursive=True,
            include_container_content=True
        )

        # Delete permissions only for folder entities within this folder recursively
        # and their contents
        Folder(id="syn123").delete_permissions(
            recursive=True,
            include_container_content=True,
            target_entity_types=["folder"]
        )

        # Delete permissions only for files within this folder and all subfolders
        Folder(id="syn123").delete_permissions(
            include_self=False,
            recursive=True,
            include_container_content=True,
            target_entity_types=["file"]
        )

        # Dry run example: Log what would be deleted without making changes
        Folder(id="syn123").delete_permissions(
            recursive=True,
            include_container_content=True,
            dry_run=True
        )
        ```
    """
    return None

list_acl ¶

list_acl(recursive: bool = False, include_container_content: bool = False, target_entity_types: Optional[List[str]] = None, log_tree: bool = False, *, synapse_client: Optional[Synapse] = None, _progress_bar: Optional[tqdm] = None) -> AclListResult

List the Access Control Lists (ACLs) for this entity and optionally its children.

This function returns the local sharing settings for the entity and optionally its children. It provides a mapping of all ACLs for the given container/entity.

Important Note: This function returns the LOCAL sharing settings only, not the effective permissions that each Synapse User ID/Team has on the entities. More permissive permissions could be granted via a Team that the user has access to that has permissions on the entity, or through inheritance from parent entities.

PARAMETER	DESCRIPTION
`recursive`	If True and the entity is a container (e.g., Project or Folder), recursively process child containers. Note that this must be used with include_container_content=True to have any effect. Setting recursive=True with include_container_content=False will raise a ValueError. Only works on classes that support the `sync_from_synapse_async` method. TYPE: `bool` DEFAULT: `False`
`include_container_content`	If True, include ACLs from contents directly within containers (files and folders inside self). This must be set to True for recursive to have any effect. Defaults to False. TYPE: `bool` DEFAULT: `False`
`target_entity_types`	Specify which entity types to process when listing ACLs. Allowed values are "folder" and "file" (case-insensitive). If None, defaults to ["folder", "file"]. TYPE: `Optional[List[str]]` DEFAULT: `None`
`log_tree`	If True, logs the ACL results to console in ASCII tree format showing entity hierarchies and their ACL permissions in a tree-like structure. 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`
`_progress_bar`	Internal parameter. Progress bar instance to use for updates when called recursively. Should not be used by external callers. TYPE: `Optional[tqdm]` DEFAULT: `None`

RETURNS	DESCRIPTION
`AclListResult`	An AclListResult object containing a structured representation of ACLs where:
`AclListResult`	entity_acls: A list of EntityAcl objects, each representing one entity's ACL
`AclListResult`	Each EntityAcl contains acl_entries (a list of AclEntry objects)
`AclListResult`	Each AclEntry contains the principal_id and their list of permissions

RAISES	DESCRIPTION
`ValueError`	If the entity does not have an ID or if an invalid entity type is provided.
`SynapseHTTPError`	If there are permission issues accessing ACLs.
`Exception`	For any other errors that may occur during the process.

List ACLs for a single entity

from synapseclient import Synapse
from synapseclient.models import File

syn = Synapse()
syn.login()

acl_result = File(id="syn123").list_acl()
print(acl_result)

# Access entity ACLs (entity_acls is a list, not a dict)
for entity_acl in acl_result.all_entity_acls:
    if entity_acl.entity_id == "syn123":
        # Access individual ACL entries
        for acl_entry in entity_acl.acl_entries:
            if acl_entry.principal_id == "273948":
                print(f"Principal 273948 has permissions: {acl_entry.permissions}")

# I can also access the ACL for the file itself
print(acl_result.entity_acl)

print(acl_result)

List ACLs recursively for a folder and all its children

from synapseclient import Synapse
from synapseclient.models import Folder

syn = Synapse()
syn.login()

acl_result = Folder(id="syn123").list_acl(
    recursive=True,
    include_container_content=True
)

# Access each entity's ACL (entity_acls is a list)
for entity_acl in acl_result.all_entity_acls:
    print(f"Entity {entity_acl.entity_id} has ACL with {len(entity_acl.acl_entries)} principals")

# I can also access the ACL for the folder itself
print(acl_result.entity_acl)

# List ACLs for only folder entities
folder_acl_result = Folder(id="syn123").list_acl(
    recursive=True,
    include_container_content=True,
    target_entity_types=["folder"]
)

List ACLs with ASCII tree visualization

When log_tree=True, the ACLs will be logged in a tree format. Additionally, the ascii_tree attribute of the AclListResult will contain the ASCII tree representation of the ACLs.

from synapseclient import Synapse
from synapseclient.models import Folder

syn = Synapse()
syn.login()

acl_result = Folder(id="syn123").list_acl(
    recursive=True,
    include_container_content=True,
    log_tree=True, # Enable ASCII tree logging
)

# The ASCII tree representation of the ACLs will also be available
# in acl_result.ascii_tree
print(acl_result.ascii_tree)

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

def list_acl(
    self,
    recursive: bool = False,
    include_container_content: bool = False,
    target_entity_types: Optional[List[str]] = None,
    log_tree: bool = False,
    *,
    synapse_client: Optional[Synapse] = None,
    _progress_bar: Optional[tqdm] = None,  # Internal parameter for recursive calls
) -> "AclListResult":
    """
    List the Access Control Lists (ACLs) for this entity and optionally its children.

    This function returns the local sharing settings for the entity and optionally
    its children. It provides a mapping of all ACLs for the given container/entity.

    **Important Note:** This function returns the LOCAL sharing settings only, not
    the effective permissions that each Synapse User ID/Team has on the entities.
    More permissive permissions could be granted via a Team that the user has access
    to that has permissions on the entity, or through inheritance from parent entities.

    Arguments:
        recursive: If True and the entity is a container (e.g., Project or Folder),
            recursively process child containers. Note that this must be used with
            include_container_content=True to have any effect. Setting recursive=True
            with include_container_content=False will raise a ValueError.
            Only works on classes that support the `sync_from_synapse_async` method.
        include_container_content: If True, include ACLs from contents directly within
            containers (files and folders inside self). This must be set to
            True for recursive to have any effect. Defaults to False.
        target_entity_types: Specify which entity types to process when listing ACLs.
            Allowed values are "folder" and "file" (case-insensitive).
            If None, defaults to ["folder", "file"].
        log_tree: If True, logs the ACL results to console in ASCII tree format showing
            entity hierarchies and their ACL permissions in a tree-like structure.
            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.
        _progress_bar: Internal parameter. Progress bar instance to use for updates
            when called recursively. Should not be used by external callers.

    Returns:
        An AclListResult object containing a structured representation of ACLs where:
        - entity_acls: A list of EntityAcl objects, each representing one entity's ACL
        - Each EntityAcl contains acl_entries (a list of AclEntry objects)
        - Each AclEntry contains the principal_id and their list of permissions

    Raises:
        ValueError: If the entity does not have an ID or if an invalid entity type is provided.
        SynapseHTTPError: If there are permission issues accessing ACLs.
        Exception: For any other errors that may occur during the process.

    Example: List ACLs for a single entity
        ```python
        from synapseclient import Synapse
        from synapseclient.models import File

        syn = Synapse()
        syn.login()

        acl_result = File(id="syn123").list_acl()
        print(acl_result)

        # Access entity ACLs (entity_acls is a list, not a dict)
        for entity_acl in acl_result.all_entity_acls:
            if entity_acl.entity_id == "syn123":
                # Access individual ACL entries
                for acl_entry in entity_acl.acl_entries:
                    if acl_entry.principal_id == "273948":
                        print(f"Principal 273948 has permissions: {acl_entry.permissions}")

        # I can also access the ACL for the file itself
        print(acl_result.entity_acl)

        print(acl_result)

        ```

    Example: List ACLs recursively for a folder and all its children
        ```python
        from synapseclient import Synapse
        from synapseclient.models import Folder

        syn = Synapse()
        syn.login()

        acl_result = Folder(id="syn123").list_acl(
            recursive=True,
            include_container_content=True
        )

        # Access each entity's ACL (entity_acls is a list)
        for entity_acl in acl_result.all_entity_acls:
            print(f"Entity {entity_acl.entity_id} has ACL with {len(entity_acl.acl_entries)} principals")

        # I can also access the ACL for the folder itself
        print(acl_result.entity_acl)

        # List ACLs for only folder entities
        folder_acl_result = Folder(id="syn123").list_acl(
            recursive=True,
            include_container_content=True,
            target_entity_types=["folder"]
        )
        ```

    Example: List ACLs with ASCII tree visualization
        When `log_tree=True`, the ACLs will be logged in a tree format. Additionally,
        the `ascii_tree` attribute of the AclListResult will contain the ASCII tree
        representation of the ACLs.

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

        syn = Synapse()
        syn.login()

        acl_result = Folder(id="syn123").list_acl(
            recursive=True,
            include_container_content=True,
            log_tree=True, # Enable ASCII tree logging
        )

        # The ASCII tree representation of the ACLs will also be available
        # in acl_result.ascii_tree
        print(acl_result.ascii_tree)
        ```
    """
    return AclListResult()

VirtualTable¶

API reference¶

synapseclient.models.VirtualTable dataclass ¶

Functions¶

store ¶

get ¶

delete ¶

query staticmethod ¶

query_part_mask staticmethod ¶

get_permissions ¶

get_acl ¶

set_permissions ¶

delete_permissions ¶

list_acl ¶

synapseclient.models.VirtualTable `dataclass` ¶

query `staticmethod` ¶

query_part_mask `staticmethod` ¶