MaterializedView

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.MaterializedView dataclass

Bases: MaterializedViewSynchronousProtocol, AccessControllable, TableBase, ViewStoreMixin, DeleteMixin, GetMixin, QueryMixin

A materialized view is a type of table that is automatically built from a Synapse SQL query. Its content is read only and based off the defining_sql attribute. The SQL of the materialized view may contain JOIN clauses on multiple tables.

A MaterializedView object represents this concept in Synapse: https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/table/MaterializedView.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 materialized view are dynamic based on the select statement of the definingSQL. This list of columnIds is for read-only purposes. TYPE: Optional[OrderedDict]
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 materialized view. 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 materialized view with a defining SQL query.

 

from synapseclient import Synapse
from synapseclient.models import MaterializedView

syn = Synapse()
syn.login()

materialized_view = MaterializedView(
    name="My Materialized View",
    description="A test materialized view",
    parent_id="syn12345",
    defining_sql="SELECT * FROM syn67890"
)
materialized_view = materialized_view.store()
print(f"Created Materialized View with ID: {materialized_view.id}")

Update the defining SQL of an existing materialized view.

 

from synapseclient import Synapse
from synapseclient.models import MaterializedView

syn = Synapse()
syn.login()

materialized_view = MaterializedView(id="syn12345").get()
materialized_view.defining_sql = "SELECT column1, column2 FROM syn67890"
materialized_view = materialized_view.store()
print("Updated Materialized View defining SQL.")

Delete a materialized view.

 

from synapseclient import Synapse
from synapseclient.models import MaterializedView

syn = Synapse()
syn.login()

materialized_view = MaterializedView(id="syn12345")
materialized_view.delete()
print("Deleted Materialized View.")

Query data from a materialized view.

 

from synapseclient import Synapse
from synapseclient.models import query

syn = Synapse()
syn.login()

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

Retrieve and update annotations for a materialized view.

 

from synapseclient import Synapse
from synapseclient.models import MaterializedView

syn = Synapse()
syn.login()

materialized_view = MaterializedView(id="syn12345").get()
materialized_view.annotations["key1"] = ["value1"]
materialized_view.annotations["key2"] = ["value2"]
materialized_view.store()
print("Updated annotations for Materialized View.")

Create a materialized view with a JOIN clause.

 

from synapseclient import Synapse
from synapseclient.models import MaterializedView

syn = Synapse()
syn.login()

defining_sql = '''
SELECT t1.column1 AS new_column1, t2.column2 AS new_column2
FROM syn12345 t1
JOIN syn67890 t2
ON t1.id = t2.foreign_id
'''

materialized_view = MaterializedView(
    name="Join Materialized View",
    description="A materialized view with a JOIN clause",
    parent_id="syn11111",
    defining_sql=defining_sql,
)
materialized_view = materialized_view.store()
print(f"Created Materialized View with ID: {materialized_view.id}")

Create a materialized view with a LEFT JOIN clause.

 

from synapseclient import Synapse
from synapseclient.models import MaterializedView

syn = Synapse()
syn.login()

defining_sql = '''
SELECT t1.column1 AS new_column1, t2.column2 AS new_column2
FROM syn12345 t1
LEFT JOIN syn67890 t2
ON t1.id = t2.foreign_id
'''

materialized_view = MaterializedView(
    name="Left Join Materialized View",
    description="A materialized view with a LEFT JOIN clause",
    parent_id="syn11111",
    defining_sql=defining_sql,
)
materialized_view = materialized_view.store()
print(f"Created Materialized View with ID: {materialized_view.id}")

Create a materialized view with a RIGHT JOIN clause.

 

from synapseclient import Synapse
from synapseclient.models import MaterializedView

syn = Synapse()
syn.login()

defining_sql = '''
SELECT t1.column1 AS new_column1, t2.column2 AS new_column2
FROM syn12345 t1
RIGHT JOIN syn67890 t2
ON t1.id = t2.foreign_id
'''

materialized_view = MaterializedView(
    name="Right Join Materialized View",
    description="A materialized view with a RIGHT JOIN clause",
    parent_id="syn11111",
    defining_sql=defining_sql,
)
materialized_view = materialized_view.store()
print(f"Created Materialized View with ID: {materialized_view.id}")

Create a materialized view with a UNION clause.

 

from synapseclient import Synapse
from synapseclient.models import MaterializedView

syn = Synapse()
syn.login()

defining_sql = '''
SELECT column1 AS new_column1, column2 AS new_column2
FROM syn12345
UNION
SELECT column1 AS new_column1, column2 AS new_column2
FROM syn67890
'''

materialized_view = MaterializedView(
    name="Union Materialized View",
    description="A materialized view with a UNION clause",
    parent_id="syn11111",
    defining_sql=defining_sql,
)
materialized_view = materialized_view.store()
print(f"Created Materialized View with ID: {materialized_view.id}")

Source code in synapseclient/models/materializedview.py

@dataclass
@async_to_sync
class MaterializedView(
    MaterializedViewSynchronousProtocol,
    AccessControllable,
    TableBase,
    ViewStoreMixin,
    DeleteMixin,
    GetMixin,
    QueryMixin,
):
    """
    A materialized view is a type of table that is automatically built from a Synapse
    SQL query. Its content is read only and based off the `defining_sql` attribute.
    The SQL of the materialized view may contain JOIN clauses on multiple tables.

    A `MaterializedView` object represents this concept in Synapse:
    <https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/table/MaterializedView.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 materialized view 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
            materialized view.
        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 materialized view with a defining SQL query.
        &nbsp;

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

        syn = Synapse()
        syn.login()

        materialized_view = MaterializedView(
            name="My Materialized View",
            description="A test materialized view",
            parent_id="syn12345",
            defining_sql="SELECT * FROM syn67890"
        )
        materialized_view = materialized_view.store()
        print(f"Created Materialized View with ID: {materialized_view.id}")
        ```

    Example: Update the defining SQL of an existing materialized view.
        &nbsp;

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

        syn = Synapse()
        syn.login()

        materialized_view = MaterializedView(id="syn12345").get()
        materialized_view.defining_sql = "SELECT column1, column2 FROM syn67890"
        materialized_view = materialized_view.store()
        print("Updated Materialized View defining SQL.")
        ```

    Example: Delete a materialized view.
        &nbsp;

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

        syn = Synapse()
        syn.login()

        materialized_view = MaterializedView(id="syn12345")
        materialized_view.delete()
        print("Deleted Materialized View.")
        ```

    Example: Query data from a materialized view.
        &nbsp;

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

        syn = Synapse()
        syn.login()

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

    Example: Retrieve and update annotations for a materialized view.
        &nbsp;

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

        syn = Synapse()
        syn.login()

        materialized_view = MaterializedView(id="syn12345").get()
        materialized_view.annotations["key1"] = ["value1"]
        materialized_view.annotations["key2"] = ["value2"]
        materialized_view.store()
        print("Updated annotations for Materialized View.")
        ```

    Example: Create a materialized view with a JOIN clause.
        &nbsp;

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

        syn = Synapse()
        syn.login()

        defining_sql = '''
        SELECT t1.column1 AS new_column1, t2.column2 AS new_column2
        FROM syn12345 t1
        JOIN syn67890 t2
        ON t1.id = t2.foreign_id
        '''

        materialized_view = MaterializedView(
            name="Join Materialized View",
            description="A materialized view with a JOIN clause",
            parent_id="syn11111",
            defining_sql=defining_sql,
        )
        materialized_view = materialized_view.store()
        print(f"Created Materialized View with ID: {materialized_view.id}")
        ```

    Example: Create a materialized view with a LEFT JOIN clause.
        &nbsp;

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

        syn = Synapse()
        syn.login()

        defining_sql = '''
        SELECT t1.column1 AS new_column1, t2.column2 AS new_column2
        FROM syn12345 t1
        LEFT JOIN syn67890 t2
        ON t1.id = t2.foreign_id
        '''

        materialized_view = MaterializedView(
            name="Left Join Materialized View",
            description="A materialized view with a LEFT JOIN clause",
            parent_id="syn11111",
            defining_sql=defining_sql,
        )
        materialized_view = materialized_view.store()
        print(f"Created Materialized View with ID: {materialized_view.id}")
        ```

    Example: Create a materialized view with a RIGHT JOIN clause.
        &nbsp;

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

        syn = Synapse()
        syn.login()

        defining_sql = '''
        SELECT t1.column1 AS new_column1, t2.column2 AS new_column2
        FROM syn12345 t1
        RIGHT JOIN syn67890 t2
        ON t1.id = t2.foreign_id
        '''

        materialized_view = MaterializedView(
            name="Right Join Materialized View",
            description="A materialized view with a RIGHT JOIN clause",
            parent_id="syn11111",
            defining_sql=defining_sql,
        )
        materialized_view = materialized_view.store()
        print(f"Created Materialized View with ID: {materialized_view.id}")
        ```

    Example: Create a materialized view with a UNION clause.
        &nbsp;

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

        syn = Synapse()
        syn.login()

        defining_sql = '''
        SELECT column1 AS new_column1, column2 AS new_column2
        FROM syn12345
        UNION
        SELECT column1 AS new_column1, column2 AS new_column2
        FROM syn67890
        '''

        materialized_view = MaterializedView(
            name="Union Materialized View",
            description="A materialized view with a UNION clause",
            parent_id="syn11111",
            defining_sql=defining_sql,
        )
        materialized_view = materialized_view.store()
        print(f"Created Materialized View with ID: {materialized_view.id}")
        ```
    """

    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] = field(default_factory=OrderedDict, compare=False)
    """(Read Only) The columns of a materialized view 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 materialized
    view."""

    _last_persistent_instance: Optional["MaterializedView"] = 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, set_annotations: bool = True
    ) -> "MaterializedView":
        """
        Converts the data coming from the Synapse API into this datamodel.

        Arguments:
            entity: The data coming from the Synapse API

        Returns:
            The MaterializedView 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):
        """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.MATERIALIZED_VIEW,
            "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 non-row information about a MaterializedView including the annotations.

        Note: Columns in a MaterializedView 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 MaterializedView instance stored in synapse.

        Example: Create a new materialized view with a defining SQL query.
            &nbsp;

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

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

                materialized_view = MaterializedView(
                    name="My Materialized View",
                    description="A test materialized view",
                    parent_id="syn12345",
                    defining_sql="SELECT * FROM syn67890"
                )
                materialized_view = await materialized_view.store_async()
                print(f"Created Materialized View with ID: {materialized_view.id}")

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

        Example: Retrieve a materialized view by ID.
            &nbsp;

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

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

                materialized_view = await MaterializedView(id="syn12345").get_async()
                print(materialized_view)

            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 materialized view from synapse. This is not version specific. If you'd like
        to delete a specific version of the materialized view 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: Delete a materialized view.
            &nbsp;

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

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

                materialized_view = MaterializedView(id="syn12345")
                await materialized_view.delete_async()
                print("Deleted Materialized View.")

            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 non-row information about a MaterializedView including the annotations.

Note: Columns in a MaterializedView 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 MaterializedView instance stored in synapse.

Create a new materialized view with a defining SQL query.

 

from synapseclient import Synapse
from synapseclient.models import MaterializedView

syn = Synapse()
syn.login()

materialized_view = MaterializedView(
    name="My Materialized View",
    description="A test materialized view",
    parent_id="syn12345",
    defining_sql="SELECT * FROM syn67890"
)
materialized_view = materialized_view.store()
print(f"Created Materialized View with ID: {materialized_view.id}")

Update the defining SQL of an existing materialized view.

 

from synapseclient import Synapse
from synapseclient.models import MaterializedView

syn = Synapse()
syn.login()

materialized_view = MaterializedView(id="syn12345").get()
materialized_view.defining_sql = "SELECT column1, column2 FROM syn67890"
materialized_view = materialized_view.store()
print("Updated Materialized View defining SQL.")

Retrieve and update annotations for a materialized view.

 

from synapseclient import Synapse
from synapseclient.models import MaterializedView

syn = Synapse()
syn.login()

materialized_view = MaterializedView(id="syn12345").get()
materialized_view.annotations["key1"] = ["value1"]
materialized_view.annotations["key2"] = ["value2"]
materialized_view.store()
print("Updated annotations for Materialized View.")

Create a materialized view with a JOIN clause.

 

from synapseclient import Synapse
from synapseclient.models import MaterializedView

syn = Synapse()
syn.login()

defining_sql = '''
SELECT t1.column1 AS new_column1, t2.column2 AS new_column2
FROM syn12345 t1
JOIN syn67890 t2
ON t1.id = t2.foreign_id
'''

materialized_view = MaterializedView(
    name="Join Materialized View",
    description="A materialized view with a JOIN clause",
    parent_id="syn11111",
    defining_sql=defining_sql,
)
materialized_view = materialized_view.store()
print(f"Created Materialized View with ID: {materialized_view.id}")

Create a materialized view with a LEFT JOIN clause.

 

from synapseclient import Synapse
from synapseclient.models import MaterializedView

syn = Synapse()
syn.login()

defining_sql = '''
SELECT t1.column1 AS new_column1, t2.column2 AS new_column2
FROM syn12345 t1
LEFT JOIN syn67890 t2
ON t1.id = t2.foreign_id
'''

materialized_view = MaterializedView(
    name="Left Join Materialized View",
    description="A materialized view with a LEFT JOIN clause",
    parent_id="syn11111",
    defining_sql=defining_sql,
)
materialized_view = materialized_view.store()
print(f"Created Materialized View with ID: {materialized_view.id}")

Create a materialized view with a RIGHT JOIN clause.

 

from synapseclient import Synapse
from synapseclient.models import MaterializedView

syn = Synapse()
syn.login()

defining_sql = '''
SELECT t1.column1 AS new_column1, t2.column2 AS new_column2
FROM syn12345 t1
RIGHT JOIN syn67890 t2
ON t1.id = t2.foreign_id
'''

materialized_view = MaterializedView(
    name="Right Join Materialized View",
    description="A materialized view with a RIGHT JOIN clause",
    parent_id="syn11111",
    defining_sql=defining_sql,
)
materialized_view = materialized_view.store()
print(f"Created Materialized View with ID: {materialized_view.id}")

Create a materialized view with a UNION clause.

 

from synapseclient import Synapse
from synapseclient.models import MaterializedView

syn = Synapse()
syn.login()

defining_sql = '''
SELECT column1 AS new_column1, column2 AS new_column2
FROM syn12345
UNION
SELECT column1 AS new_column1, column2 AS new_column2
FROM syn67890
'''

materialized_view = MaterializedView(
    name="Union Materialized View",
    description="A materialized view with a UNION clause",
    parent_id="syn11111",
    defining_sql=defining_sql,
)
materialized_view = materialized_view.store()
print(f"Created Materialized View with ID: {materialized_view.id}")

Source code in synapseclient/models/materializedview.py

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

    Note: Columns in a MaterializedView 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 MaterializedView instance stored in synapse.

    Example: Create a new materialized view with a defining SQL query.
         

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

        syn = Synapse()
        syn.login()

        materialized_view = MaterializedView(
            name="My Materialized View",
            description="A test materialized view",
            parent_id="syn12345",
            defining_sql="SELECT * FROM syn67890"
        )
        materialized_view = materialized_view.store()
        print(f"Created Materialized View with ID: {materialized_view.id}")
        ```

    Example: Update the defining SQL of an existing materialized view.
         

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

        syn = Synapse()
        syn.login()

        materialized_view = MaterializedView(id="syn12345").get()
        materialized_view.defining_sql = "SELECT column1, column2 FROM syn67890"
        materialized_view = materialized_view.store()
        print("Updated Materialized View defining SQL.")
        ```

    Example: Retrieve and update annotations for a materialized view.
         

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

        syn = Synapse()
        syn.login()

        materialized_view = MaterializedView(id="syn12345").get()
        materialized_view.annotations["key1"] = ["value1"]
        materialized_view.annotations["key2"] = ["value2"]
        materialized_view.store()
        print("Updated annotations for Materialized View.")
        ```

    Example: Create a materialized view with a JOIN clause.
         

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

        syn = Synapse()
        syn.login()

        defining_sql = '''
        SELECT t1.column1 AS new_column1, t2.column2 AS new_column2
        FROM syn12345 t1
        JOIN syn67890 t2
        ON t1.id = t2.foreign_id
        '''

        materialized_view = MaterializedView(
            name="Join Materialized View",
            description="A materialized view with a JOIN clause",
            parent_id="syn11111",
            defining_sql=defining_sql,
        )
        materialized_view = materialized_view.store()
        print(f"Created Materialized View with ID: {materialized_view.id}")
        ```

    Example: Create a materialized view with a LEFT JOIN clause.
         

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

        syn = Synapse()
        syn.login()

        defining_sql = '''
        SELECT t1.column1 AS new_column1, t2.column2 AS new_column2
        FROM syn12345 t1
        LEFT JOIN syn67890 t2
        ON t1.id = t2.foreign_id
        '''

        materialized_view = MaterializedView(
            name="Left Join Materialized View",
            description="A materialized view with a LEFT JOIN clause",
            parent_id="syn11111",
            defining_sql=defining_sql,
        )
        materialized_view = materialized_view.store()
        print(f"Created Materialized View with ID: {materialized_view.id}")
        ```

    Example: Create a materialized view with a RIGHT JOIN clause.
         

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

        syn = Synapse()
        syn.login()

        defining_sql = '''
        SELECT t1.column1 AS new_column1, t2.column2 AS new_column2
        FROM syn12345 t1
        RIGHT JOIN syn67890 t2
        ON t1.id = t2.foreign_id
        '''

        materialized_view = MaterializedView(
            name="Right Join Materialized View",
            description="A materialized view with a RIGHT JOIN clause",
            parent_id="syn11111",
            defining_sql=defining_sql,
        )
        materialized_view = materialized_view.store()
        print(f"Created Materialized View with ID: {materialized_view.id}")
        ```

    Example: Create a materialized view with a UNION clause.
         

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

        syn = Synapse()
        syn.login()

        defining_sql = '''
        SELECT column1 AS new_column1, column2 AS new_column2
        FROM syn12345
        UNION
        SELECT column1 AS new_column1, column2 AS new_column2
        FROM syn67890
        '''

        materialized_view = MaterializedView(
            name="Union Materialized View",
            description="A materialized view with a UNION clause",
            parent_id="syn11111",
            defining_sql=defining_sql,
        )
        materialized_view = materialized_view.store()
        print(f"Created Materialized View with ID: {materialized_view.id}")
        ```
    """
    return self

get

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

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

Getting metadata about a MaterializedView using id

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

syn = Synapse()
syn.login()

materialized_view = MaterializedView(id="syn4567").get(include_activity=True)
print(materialized_view)

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

Getting metadata about a MaterializedView using name and parent_id

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

syn = Synapse()
syn.login()

materialized_view = MaterializedView(name="my_materialized_view", parent_id="syn1234").get(include_columns=True, include_activity=True)
print(materialized_view)
print(materialized_view.columns)
print(materialized_view.activity)

Source code in synapseclient/models/materializedview.py

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

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

        syn = Synapse()
        syn.login()

        materialized_view = MaterializedView(id="syn4567").get(include_activity=True)
        print(materialized_view)

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

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

        syn = Synapse()
        syn.login()

        materialized_view = MaterializedView(name="my_materialized_view", parent_id="syn1234").get(include_columns=True, include_activity=True)
        print(materialized_view)
        print(materialized_view.columns)
        print(materialized_view.activity)
        ```
    """
    return self

delete

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

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

Delete a materialized view.

 

from synapseclient import Synapse
from synapseclient.models import MaterializedView

syn = Synapse()
syn.login()

materialized_view = MaterializedView(id="syn12345")
materialized_view.delete()
print("Deleted Materialized View.")

Source code in synapseclient/models/materializedview.py

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

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

        syn = Synapse()
        syn.login()

        materialized_view = MaterializedView(id="syn12345")
        materialized_view.delete()
        print("Deleted Materialized View.")
        ```
    """
    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()