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.
        &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: 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}")
        ```
    """
    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.
        &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.")
        ```
    """
    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) -> QueryResultBundle

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

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

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

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

Querying for data with a part mask

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

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

from synapseclient import Synapse
from synapseclient.models import query_part_mask

syn = Synapse()
syn.login()

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

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

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

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

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

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

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

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

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

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

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

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

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

        syn = Synapse()
        syn.login()

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

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

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

get_permissions ¶

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

Get the permissions that the caller has on an Entity.

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

RETURNS	DESCRIPTION
`Permissions`	A Permissions object

Using this function:

Getting permissions for a Synapse Entity

from synapseclient import Synapse
from synapseclient.models import File

syn = Synapse()
syn.login()

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

Getting access types list from the Permissions object

permissions.access_types

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

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

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

    Returns:
        A Permissions object


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

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

        syn = Synapse()
        syn.login()

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

        Getting access types list from the Permissions object

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

get_acl ¶

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

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

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

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

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

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

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

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

set_permissions ¶

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

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

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

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

Setting permissions

Grant all registered users download access

from synapseclient import Synapse
from synapseclient.models import File

syn = Synapse()
syn.login()

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

Grant the public view access

from synapseclient import Synapse
from synapseclient.models import File

syn = Synapse()
syn.login()

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

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

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

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

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

    Returns:
        An Access Control List object

    Example: Setting permissions
        Grant all registered users download access

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

        syn = Synapse()
        syn.login()

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

        Grant the public view access

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

        syn = Synapse()
        syn.login()

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

MaterializedView¶

API reference¶

synapseclient.models.MaterializedView dataclass ¶

Functions¶

store ¶

get ¶

delete ¶

query staticmethod ¶

query_part_mask staticmethod ¶

get_permissions ¶

get_acl ¶

set_permissions ¶

synapseclient.models.MaterializedView `dataclass` ¶

query `staticmethod` ¶

query_part_mask `staticmethod` ¶