Synapse Factory Operations¶

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.operations.get ¶

get(synapse_id: Optional[str] = None, *, entity_name: Optional[str] = None, parent_id: Optional[str] = None, version_number: Optional[int] = None, activity_options: Optional[ActivityOptions] = None, file_options: Optional[FileOptions] = None, table_options: Optional[TableOptions] = None, link_options: Optional[LinkOptions] = None, synapse_client: Optional[Synapse] = None) -> Union[Dataset, DatasetCollection, EntityView, File, Folder, Link, MaterializedView, Project, SubmissionView, Table, VirtualTable]

Factory method to retrieve any Synapse entity by its ID or by name and parent ID.

This method serves as a unified interface for retrieving any type of Synapse entity without needing to know the specific entity type beforehand. It automatically determines the entity type and returns the appropriate model instance.

You can retrieve entities in two ways:

By providing a synapse_id directly
By providing entity_name and optionally parent_id for lookup

PARAMETER	DESCRIPTION
`synapse_id`	The Synapse ID of the entity to retrieve (e.g., 'syn123456'). Mutually exclusive with entity_name. TYPE: `Optional[str]` DEFAULT: `None`
`entity_name`	The name of the entity to find. Must be used with this approach instead of synapse_id. When looking up projects, parent_id should be None. TYPE: `Optional[str]` DEFAULT: `None`
`parent_id`	The parent entity ID when looking up by name. Set to None when looking up projects by name. Only used with entity_name. TYPE: `Optional[str]` DEFAULT: `None`
`version_number`	The specific version number of the entity to retrieve. Only applies to versionable entities (File, Table, Dataset). If not specified, the most recent version will be retrieved. Ignored for other entity types. TYPE: `Optional[int]` DEFAULT: `None`
`activity_options`	Activity-specific configuration options. Can be applied to any entity type to include activity information. TYPE: `Optional[ActivityOptions]` DEFAULT: `None`
`file_options`	File-specific configuration options. Only applies to File entities. Ignored for other entity types. TYPE: `Optional[FileOptions]` DEFAULT: `None`
`table_options`	Table-specific configuration options. Only applies to Table-like entities (Table, Dataset, EntityView, MaterializedView, SubmissionView, VirtualTable, DatasetCollection). Ignored for other entity types. TYPE: `Optional[TableOptions]` DEFAULT: `None`
`link_options`	Link-specific configuration options. Only applies when the entity is a Link. Ignored for other entity types. TYPE: `Optional[LinkOptions]` 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
`Union[Dataset, DatasetCollection, EntityView, File, Folder, Link, MaterializedView, Project, SubmissionView, Table, VirtualTable]`	The appropriate Synapse entity model instance based on the entity type.

RAISES	DESCRIPTION
`ValueError`	If both synapse_id and entity_name are provided, or if neither is provided.
`ValueError`	If entity_name is provided without this being a valid lookup scenario.
`ValueError`	If the synapse_id is not a valid Synapse ID format.

Note

When using entity_name lookup:

For projects: leave parent_id=None
For all other entities: provide the parent_id of the containing folder/project

Retrieving entities by ID

Get any entity by Synapse ID:

from synapseclient import Synapse
from synapseclient.models import File, Project
from synapseclient.operations import get

syn = Synapse()
syn.login()

# Works for any entity type
entity = get(synapse_id="syn123456")

# The returned object will be the appropriate type
if isinstance(entity, File):
    print(f"File: {entity.name}")
elif isinstance(entity, Project):
    print(f"Project: {entity.name}")

Retrieving entities by name

Get an entity by name and parent:

from synapseclient import Synapse
from synapseclient.operations import get

syn = Synapse()
syn.login()

# Get a file by name within a folder
entity = get(
    entity_name="my_file.txt",
    parent_id="syn123456"
)

# Get a project by name (parent_id=None)
project = get(
    entity_name="My Project",
    parent_id=None
)

Retrieving a specific version

Get a specific version of a versionable entity:

from synapseclient import Synapse
from synapseclient.operations import get

syn = Synapse()
syn.login()

entity = get(synapse_id="syn123456", version_number=2)

Retrieving a file with custom options

Get file metadata with specific download options:

from synapseclient import Synapse
from synapseclient.operations import get, FileOptions, ActivityOptions

syn = Synapse()
syn.login()

file_entity = get(
    synapse_id="syn123456",
    activity_options=ActivityOptions(include_activity=True),
    file_options=FileOptions(
        download_file=False
    )
)

Retrieving a table with activity and columns

Get table with activity and column information:

from synapseclient import Synapse
from synapseclient.operations import get, ActivityOptions, TableOptions

syn = Synapse()
syn.login()

table_entity = get(
    synapse_id="syn123456",
    activity_options=ActivityOptions(include_activity=True),
    table_options=TableOptions(include_columns=True)
)

Following links

Get the target of a link entity:

from synapseclient import Synapse
from synapseclient.operations import get, LinkOptions

syn = Synapse()
syn.login()

target_entity = get(
    synapse_id="syn123456",
    link_options=LinkOptions(follow_link=True)
)

Working with Link entities

Get a Link entity without following it:

from synapseclient import Synapse
from synapseclient.operations import get, LinkOptions

syn = Synapse()
syn.login()

# Get the link entity itself
link_entity = get(
    synapse_id="syn123456",  # Example link ID
    link_options=LinkOptions(follow_link=False)
)
print(f"Link: {link_entity.name} -> {link_entity.target_id}")

# Then follow the link to get the target
target_entity = get(
    synapse_id="syn123456",
    link_options=LinkOptions(follow_link=True)
)
print(f"Target: {target_entity.name} (type: {type(target_entity).__name__})")

Comprehensive File options

Download file with custom location and collision handling:

from synapseclient import Synapse
from synapseclient.operations import get, FileOptions

syn = Synapse()
syn.login()

file_entity = get(
    synapse_id="syn123456",
    file_options=FileOptions(
        download_file=True,
        download_location="/path/to/download/",
        if_collision="overwrite.local"
    )
)
print(f"Downloaded file: {file_entity.name} to {file_entity.path}")

Table options for table-like entities

Get table entities with column information:

from synapseclient import Synapse
from synapseclient.operations import get, TableOptions

syn = Synapse()
syn.login()

# Works for Table, Dataset, EntityView, MaterializedView,
# SubmissionView, VirtualTable, and DatasetCollection
table_entity = get(
    synapse_id="syn123456",  # Example table ID
    table_options=TableOptions(include_columns=True)
)
print(f"Table: {table_entity.name} with {len(table_entity.columns)} columns")

Combining multiple options

Get a File with both activity and custom download options:

from synapseclient import Synapse
from synapseclient.operations import get, FileOptions, ActivityOptions

syn = Synapse()
syn.login()

file_entity = get(
    synapse_id="syn123456",
    activity_options=ActivityOptions(include_activity=True),
    file_options=FileOptions(
        download_file=False
    )
)
print(f"File: {file_entity.name} (activity included: {file_entity.activity is not None})")

Working with entity instances

Pass an existing entity instance to refresh or apply new options:

from synapseclient import Synapse
from synapseclient.operations import get, FileOptions

syn = Synapse()
syn.login()

# Get an entity first
entity = get(synapse_id="syn123456")
print(f"Original entity: {entity.name}")

# Then use the entity instance to get it again with different options
refreshed_entity = get(
    entity,
    file_options=FileOptions(download_file=False)
)
print(f"Refreshed entity: {refreshed_entity.name} (download_file: {refreshed_entity.download_file})")

Source code in synapseclient/operations/factory_operations.py

def get(
    synapse_id: Optional[str] = None,
    *,
    entity_name: Optional[str] = None,
    parent_id: Optional[str] = None,
    version_number: Optional[int] = None,
    activity_options: Optional[ActivityOptions] = None,
    file_options: Optional[FileOptions] = None,
    table_options: Optional[TableOptions] = None,
    link_options: Optional[LinkOptions] = None,
    synapse_client: Optional["Synapse"] = None,
) -> Union[
    "Dataset",
    "DatasetCollection",
    "EntityView",
    "File",
    "Folder",
    "Link",
    "MaterializedView",
    "Project",
    "SubmissionView",
    "Table",
    "VirtualTable",
]:
    """
    Factory method to retrieve any Synapse entity by its ID or by name and parent ID.

    This method serves as a unified interface for retrieving any type of Synapse entity
    without needing to know the specific entity type beforehand. It automatically
    determines the entity type and returns the appropriate model instance.

    You can retrieve entities in two ways:

    1. By providing a synapse_id directly
    2. By providing entity_name and optionally parent_id for lookup

    Arguments:
        synapse_id: The Synapse ID of the entity to retrieve (e.g., 'syn123456').
            Mutually exclusive with entity_name.
        entity_name: The name of the entity to find. Must be used with this approach
            instead of synapse_id. When looking up projects, parent_id should be None.
        parent_id: The parent entity ID when looking up by name. Set to None when
            looking up projects by name. Only used with entity_name.
        version_number: The specific version number of the entity to retrieve. Only
            applies to versionable entities (File, Table, Dataset). If not specified,
            the most recent version will be retrieved. Ignored for other entity types.
        activity_options: Activity-specific configuration options. Can be applied to
            any entity type to include activity information.
        file_options: File-specific configuration options. Only applies to File entities.
            Ignored for other entity types.
        table_options: Table-specific configuration options. Only applies to Table-like
            entities (Table, Dataset, EntityView, MaterializedView, SubmissionView,
            VirtualTable, DatasetCollection). Ignored for other entity types.
        link_options: Link-specific configuration options. Only applies when the entity
            is a Link. Ignored for other entity types.
        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 appropriate Synapse entity model instance based on the entity type.

    Raises:
        ValueError: If both synapse_id and entity_name are provided, or if neither is provided.
        ValueError: If entity_name is provided without this being a valid lookup scenario.
        ValueError: If the synapse_id is not a valid Synapse ID format.

    Note:
        When using entity_name lookup:

        - For projects: leave parent_id=None
        - For all other entities: provide the parent_id of the containing folder/project

    Example: Retrieving entities by ID
        Get any entity by Synapse ID:

        ```python
        from synapseclient import Synapse
        from synapseclient.models import File, Project
        from synapseclient.operations import get

        syn = Synapse()
        syn.login()

        # Works for any entity type
        entity = get(synapse_id="syn123456")

        # The returned object will be the appropriate type
        if isinstance(entity, File):
            print(f"File: {entity.name}")
        elif isinstance(entity, Project):
            print(f"Project: {entity.name}")
        ```

    Example: Retrieving entities by name
        Get an entity by name and parent:

        ```python
        from synapseclient import Synapse
        from synapseclient.operations import get

        syn = Synapse()
        syn.login()

        # Get a file by name within a folder
        entity = get(
            entity_name="my_file.txt",
            parent_id="syn123456"
        )

        # Get a project by name (parent_id=None)
        project = get(
            entity_name="My Project",
            parent_id=None
        )
        ```

    Example: Retrieving a specific version
        Get a specific version of a versionable entity:

        ```python
        from synapseclient import Synapse
        from synapseclient.operations import get

        syn = Synapse()
        syn.login()

        entity = get(synapse_id="syn123456", version_number=2)
        ```

    Example: Retrieving a file with custom options
        Get file metadata with specific download options:

        ```python
        from synapseclient import Synapse
        from synapseclient.operations import get, FileOptions, ActivityOptions

        syn = Synapse()
        syn.login()

        file_entity = get(
            synapse_id="syn123456",
            activity_options=ActivityOptions(include_activity=True),
            file_options=FileOptions(
                download_file=False
            )
        )
        ```

    Example: Retrieving a table with activity and columns
        Get table with activity and column information:

        ```python
        from synapseclient import Synapse
        from synapseclient.operations import get, ActivityOptions, TableOptions

        syn = Synapse()
        syn.login()

        table_entity = get(
            synapse_id="syn123456",
            activity_options=ActivityOptions(include_activity=True),
            table_options=TableOptions(include_columns=True)
        )
        ```

    Example: Following links
        Get the target of a link entity:

        ```python
        from synapseclient import Synapse
        from synapseclient.operations import get, LinkOptions

        syn = Synapse()
        syn.login()

        target_entity = get(
            synapse_id="syn123456",
            link_options=LinkOptions(follow_link=True)
        )
        ```

    Example: Working with Link entities
        Get a Link entity without following it:

        ```python
        from synapseclient import Synapse
        from synapseclient.operations import get, LinkOptions

        syn = Synapse()
        syn.login()

        # Get the link entity itself
        link_entity = get(
            synapse_id="syn123456",  # Example link ID
            link_options=LinkOptions(follow_link=False)
        )
        print(f"Link: {link_entity.name} -> {link_entity.target_id}")

        # Then follow the link to get the target
        target_entity = get(
            synapse_id="syn123456",
            link_options=LinkOptions(follow_link=True)
        )
        print(f"Target: {target_entity.name} (type: {type(target_entity).__name__})")
        ```

    Example: Comprehensive File options
        Download file with custom location and collision handling:

        ```python
        from synapseclient import Synapse
        from synapseclient.operations import get, FileOptions

        syn = Synapse()
        syn.login()

        file_entity = get(
            synapse_id="syn123456",
            file_options=FileOptions(
                download_file=True,
                download_location="/path/to/download/",
                if_collision="overwrite.local"
            )
        )
        print(f"Downloaded file: {file_entity.name} to {file_entity.path}")
        ```

    Example: Table options for table-like entities
        Get table entities with column information:

        ```python
        from synapseclient import Synapse
        from synapseclient.operations import get, TableOptions

        syn = Synapse()
        syn.login()

        # Works for Table, Dataset, EntityView, MaterializedView,
        # SubmissionView, VirtualTable, and DatasetCollection
        table_entity = get(
            synapse_id="syn123456",  # Example table ID
            table_options=TableOptions(include_columns=True)
        )
        print(f"Table: {table_entity.name} with {len(table_entity.columns)} columns")
        ```

    Example: Combining multiple options
        Get a File with both activity and custom download options:

        ```python
        from synapseclient import Synapse
        from synapseclient.operations import get, FileOptions, ActivityOptions

        syn = Synapse()
        syn.login()

        file_entity = get(
            synapse_id="syn123456",
            activity_options=ActivityOptions(include_activity=True),
            file_options=FileOptions(
                download_file=False
            )
        )
        print(f"File: {file_entity.name} (activity included: {file_entity.activity is not None})")
        ```

    Example: Working with entity instances
        Pass an existing entity instance to refresh or apply new options:

        ```python
        from synapseclient import Synapse
        from synapseclient.operations import get, FileOptions

        syn = Synapse()
        syn.login()

        # Get an entity first
        entity = get(synapse_id="syn123456")
        print(f"Original entity: {entity.name}")

        # Then use the entity instance to get it again with different options
        refreshed_entity = get(
            entity,
            file_options=FileOptions(download_file=False)
        )
        print(f"Refreshed entity: {refreshed_entity.name} (download_file: {refreshed_entity.download_file})")
        ```
    """
    return wrap_async_to_sync(
        coroutine=get_async(
            synapse_id=synapse_id,
            entity_name=entity_name,
            parent_id=parent_id,
            version_number=version_number,
            activity_options=activity_options,
            file_options=file_options,
            table_options=table_options,
            link_options=link_options,
            synapse_client=synapse_client,
        )
    )

synapseclient.operations.FileOptions `dataclass` ¶

Configuration options specific to File entities when using the factory methods.

This dataclass allows you to customize how File entities are handled during retrieval, including download behavior, file location, and collision handling.

ATTRIBUTE	DESCRIPTION
`download_file`	Whether to automatically download the file content when retrieving the File entity. If True, the file will be downloaded to the local filesystem. If False, only the metadata will be retrieved. Default is True. TYPE: `bool`
`download_location`	The local directory path where the file should be downloaded. If None, the file will be downloaded to the default Synapse cache location. If specified, must be a valid directory path. Default is None. TYPE: `Optional[str]`
`if_collision`	Strategy to use when a file with the same name already exists at the download location. Valid options are: - "keep.both": Keep both files by appending a number to the new file - "overwrite.local": Overwrite the existing local file - "keep.local": Keep the existing local file and skip download Default is "keep.both". TYPE: `str`

Example

Configure file download options:

from synapseclient.operations import FileOptions

# Download file to specific location with overwrite
file_options = FileOptions(
    download_file=True,
    download_location="/path/to/downloads/",
    if_collision="overwrite.local"
)

# Only retrieve metadata, don't download file content
metadata_only = FileOptions(download_file=False)

Source code in synapseclient/operations/factory_operations.py

@dataclass
class FileOptions:
    """
    Configuration options specific to File entities when using the factory methods.

    This dataclass allows you to customize how File entities are handled during
    retrieval, including download behavior, file location, and collision handling.

    Attributes:
        download_file: Whether to automatically download the file content when
            retrieving the File entity. If True, the file will be downloaded to
            the local filesystem. If False, only the metadata will be retrieved.
            Default is True.
        download_location: The local directory path where the file should be
            downloaded. If None, the file will be downloaded to the default Synapse
            cache location. If specified,
            must be a valid directory path. Default is None.
        if_collision: Strategy to use when a file with the same name already
            exists at the download location. Valid options are:
            - "keep.both": Keep both files by appending a number to the new file
            - "overwrite.local": Overwrite the existing local file
            - "keep.local": Keep the existing local file and skip download
            Default is "keep.both".

    Example:
        Configure file download options:

        ```python
        from synapseclient.operations import FileOptions

        # Download file to specific location with overwrite
        file_options = FileOptions(
            download_file=True,
            download_location="/path/to/downloads/",
            if_collision="overwrite.local"
        )

        # Only retrieve metadata, don't download file content
        metadata_only = FileOptions(download_file=False)
        ```
    """

    download_file: bool = True
    download_location: Optional[str] = None
    if_collision: str = "keep.both"

synapseclient.operations.ActivityOptions `dataclass` ¶

Configuration options for entities that support activity/provenance tracking.

This dataclass controls whether activity information (provenance data) should be included when retrieving entities. Activity information tracks the computational steps, data sources, and relationships that led to the creation of an entity.

ATTRIBUTE	DESCRIPTION
`include_activity`	Whether to include activity/provenance information when retrieving the entity. If True, the returned entity will have its activity attribute populated with provenance data (if available). If False, the activity attribute will be None. Including activity may result in additional API calls and slower retrieval times. Default is False. TYPE: `bool`

Example

Configure activity inclusion:

from synapseclient.operations import ActivityOptions

# Include activity information
with_activity = ActivityOptions(include_activity=True)

# Skip activity information (faster retrieval)
without_activity = ActivityOptions(include_activity=False)

Note

Activity information is only available for entities that support provenance tracking (File, Table, Dataset, etc...). For other entity types, this option is ignored.

Source code in synapseclient/operations/factory_operations.py

@dataclass
class ActivityOptions:
    """
    Configuration options for entities that support activity/provenance tracking.

    This dataclass controls whether activity information (provenance data) should
    be included when retrieving entities. Activity information tracks the computational
    steps, data sources, and relationships that led to the creation of an entity.

    Attributes:
        include_activity: Whether to include activity/provenance information when
            retrieving the entity. If True, the returned entity will have its
            activity attribute populated with provenance data (if available).
            If False, the activity attribute will be None. Including activity
            may result in additional API calls and slower retrieval times.
            Default is False.

    Example:
        Configure activity inclusion:

        ```python
        from synapseclient.operations import ActivityOptions

        # Include activity information
        with_activity = ActivityOptions(include_activity=True)

        # Skip activity information (faster retrieval)
        without_activity = ActivityOptions(include_activity=False)
        ```

    Note:
        Activity information is only available for entities that support provenance
        tracking (File, Table, Dataset, etc...). For other entity
        types, this option is ignored.
    """

    include_activity: bool = False

synapseclient.operations.TableOptions `dataclass` ¶

Configuration options for table-like entities when using the factory methods.

This dataclass controls how table-like entities (Table, Dataset, EntityView, MaterializedView, SubmissionView, VirtualTable, and DatasetCollection) are retrieved, particularly whether column schema information should be included.

ATTRIBUTE DESCRIPTION

include_columns

Whether to include column schema information when retrieving table-like entities. If True, the returned entity will have its columns attribute populated with Column objects containing schema information (name, column_type, etc.). If False, the columns attribute will be an empty dict. Including columns may result in additional API calls but provides complete table structure information. Default is True.

TYPE: bool

Example

Configure table column inclusion:

from synapseclient.operations import TableOptions

# Include column schema information
with_columns = TableOptions(include_columns=True)

# Skip column information (faster retrieval)
without_columns = TableOptions(include_columns=False)

Source code in synapseclient/operations/factory_operations.py

@dataclass
class TableOptions:
    """
    Configuration options for table-like entities when using the factory methods.

    This dataclass controls how table-like entities (Table, Dataset, EntityView,
    MaterializedView, SubmissionView, VirtualTable, and DatasetCollection) are
    retrieved, particularly whether column schema information should be included.

    Attributes:
        include_columns: Whether to include column schema information when
            retrieving table-like entities. If True, the returned entity will
            have its columns attribute populated with Column objects containing
            schema information (name, column_type, etc.). If False, the columns
            attribute will be an empty dict. Including columns may result in
            additional API calls but provides complete table structure information.
            Default is True.

    Example:
        Configure table column inclusion:

        ```python
        from synapseclient.operations import TableOptions

        # Include column schema information
        with_columns = TableOptions(include_columns=True)

        # Skip column information (faster retrieval)
        without_columns = TableOptions(include_columns=False)
        ```
    """

    include_columns: bool = True

synapseclient.operations.LinkOptions `dataclass` ¶

Configuration options specific to Link entities when using the factory methods.

This dataclass controls how Link entities are handled during retrieval, particularly whether the link should be followed to return the target entity or if the Link entity itself should be returned.

ATTRIBUTE DESCRIPTION

follow_link

Whether to follow the link and return the target entity instead of the Link entity itself. If True, the factory method will return the entity that the Link points to (e.g., if a Link points to a File, a File object will be returned). If False, the Link entity itself will be returned, allowing you to inspect the link's properties such as target_id, target_version, etc. Default is True.

TYPE: bool

Example

Configure link following behavior:

from synapseclient.operations import LinkOptions

# Follow the link and return the target entity
follow_target = LinkOptions(follow_link=True)

# Return the Link entity itself
return_link = LinkOptions(follow_link=False)

Note

When follow_link=True, the returned entity type depends on what the Link points to (could be File, Project, Folder, etc.)
When follow_link=False, a Link entity is always returned

Source code in synapseclient/operations/factory_operations.py

@dataclass
class LinkOptions:
    """
    Configuration options specific to Link entities when using the factory methods.

    This dataclass controls how Link entities are handled during retrieval,
    particularly whether the link should be followed to return the target entity
    or if the Link entity itself should be returned.

    Attributes:
        follow_link: Whether to follow the link and return the target entity
            instead of the Link entity itself. If True, the factory method will
            return the entity that the Link points to (e.g., if a Link points
            to a File, a File object will be returned). If False, the Link
            entity itself will be returned, allowing you to inspect the link's
            properties such as target_id, target_version, etc. Default is True.

    Example:
        Configure link following behavior:

        ```python
        from synapseclient.operations import LinkOptions

        # Follow the link and return the target entity
        follow_target = LinkOptions(follow_link=True)

        # Return the Link entity itself
        return_link = LinkOptions(follow_link=False)
        ```

    Note:
        - When follow_link=True, the returned entity type depends on what the
          Link points to (could be File, Project, Folder, etc.)
        - When follow_link=False, a Link entity is always returned
    """

    follow_link: bool = True

synapseclient.operations.delete ¶

delete(entity: Union[str, CurationTask, Dataset, DatasetCollection, EntityView, Evaluation, File, Folder, Grid, JSONSchema, MaterializedView, Project, RecordSet, SchemaOrganization, SubmissionView, Table, Team, VirtualTable], version: Optional[Union[int, str]] = None, version_only: bool = False, *, synapse_client: Optional[Synapse] = None) -> None

Factory method to delete any Synapse entity.

This method serves as a unified interface for deleting any type of Synapse entity. It automatically applies the appropriate delete logic based on the entity type.

Version Deletion Behavior

The function supports deleting specific versions of entities with the following precedence order:

version parameter (highest priority): When provided, this version number will be used for deletion, overriding any version information from the entity object or the entity ID string.
Entity's version_number attribute (secondary): If the entity object has a version_number attribute set and no explicit version parameter is provided, this version will be used.
version_only parameter: When set to True, indicates that only a specific version should be deleted (not the entire entity). This parameter is only meaningful when combined with a version number from either the version parameter or the entity's version_number attribute.

Supported for version-specific deletion:

String ID with version (e.g., "syn123.4")
File, RecordSet (use version_only=True)
Table, Dataset, DatasetCollection, EntityView, MaterializedView, SubmissionView, VirtualTable (use version_only=True)

Not supported for version-specific deletion:

Project, Folder, Evaluation, Team, SchemaOrganization, CurationTask, Grid

PARAMETER	DESCRIPTION
`entity`	The entity instance to delete, or a Synapse ID string (e.g., "syn123456" or "syn123456.4" for a specific version). Must be one of the supported entity types or a valid Synapse ID. TYPE: `Union[str, CurationTask, Dataset, DatasetCollection, EntityView, Evaluation, File, Folder, Grid, JSONSchema, MaterializedView, Project, RecordSet, SchemaOrganization, SubmissionView, Table, Team, VirtualTable]`
`version`	Optional version number to delete. Takes precedence over any version information in the entity object or ID string. When provided with `version_only=True`, deletes only this specific version. TYPE: `Optional[Union[int, str]]` DEFAULT: `None`
`version_only`	If True, only the specified version will be deleted, not the entire entity. Requires a version number from either the `version` parameter or the entity's `version_number` attribute. This parameter is applicable for entities that support version-specific deletion (File, RecordSet, Table, Dataset, DatasetCollection, EntityView, MaterializedView, SubmissionView, VirtualTable, JSONSchema). 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
`None`	None

RAISES	DESCRIPTION
`ValueError`	If the entity is not a supported type or not a valid Synapse ID.
`ValueError`	If version_only is True but no version number is available.

Deleting a file by object

Delete a file from Synapse:

from synapseclient import Synapse
from synapseclient.models import File
from synapseclient.operations import delete

syn = Synapse()
syn.login()

file = File(id="syn123456")
delete(file)
print("File deleted successfully")

Deleting a specific version of a file

Delete only version 2 of a file, keeping other versions:

from synapseclient import Synapse
from synapseclient.models import File
from synapseclient.operations import delete

syn = Synapse()
syn.login()

# Method 1: Using version parameter (highest priority)
file = File(id="syn123456")
delete(file, version=2, version_only=True)

# Method 2: Using entity's version_number attribute
file = File(id="syn123456", version_number=2)
delete(file, version_only=True)

# Method 3: Using synapse ID with version
delete("syn123456.2", version_only=True)
print("File version 2 deleted successfully")

Deleting a file by ID string

Delete a file from Synapse using just its ID:

from synapseclient import Synapse
from synapseclient.operations import delete

syn = Synapse()
syn.login()

delete("syn123456")
print("Entity deleted successfully")

Deleting a project

Delete a project from Synapse:

from synapseclient import Synapse
from synapseclient.models import Project
from synapseclient.operations import delete

syn = Synapse()
syn.login()

project = Project(id="syn123456")
delete(project)
print("Project deleted successfully")

Deleting a specific version of a RecordSet

Delete only a specific version of a RecordSet:

from synapseclient import Synapse
from synapseclient.models import RecordSet
from synapseclient.operations import delete

syn = Synapse()
syn.login()

record_set = RecordSet(id="syn123456", version_number=3)
delete(record_set, version_only=True)
print("RecordSet version 3 deleted successfully")

Deleting a table

Delete a table from Synapse:

from synapseclient import Synapse
from synapseclient.models import Table
from synapseclient.operations import delete

syn = Synapse()
syn.login()

table = Table(id="syn123456")
delete(table)
print("Table deleted successfully")

Deleting a team

Delete a team from Synapse:

from synapseclient import Synapse
from synapseclient.models import Team
from synapseclient.operations import delete

syn = Synapse()
syn.login()

team = Team(id="123456")
delete(team)
print("Team deleted successfully")

Deleting a curation task

Delete a curation task from Synapse:

from synapseclient import Synapse
from synapseclient.models import CurationTask
from synapseclient.operations import delete

syn = Synapse()
syn.login()

task = CurationTask(task_id=123)
delete(task)
print("Curation task deleted successfully")

Source code in synapseclient/operations/delete_operations.py

def delete(
    entity: Union[
        str,
        "CurationTask",
        "Dataset",
        "DatasetCollection",
        "EntityView",
        "Evaluation",
        "File",
        "Folder",
        "Grid",
        "JSONSchema",
        "MaterializedView",
        "Project",
        "RecordSet",
        "SchemaOrganization",
        "SubmissionView",
        "Table",
        "Team",
        "VirtualTable",
    ],
    version: Optional[Union[int, str]] = None,
    version_only: bool = False,
    *,
    synapse_client: Optional["Synapse"] = None,
) -> None:
    """
    Factory method to delete any Synapse entity.

    This method serves as a unified interface for deleting any type of Synapse entity.
    It automatically applies the appropriate delete logic based on the entity type.

    Version Deletion Behavior:
        The function supports deleting specific versions of entities with the following
        precedence order:

        1. **version parameter** (highest priority): When provided, this version number
           will be used for deletion, overriding any version information from the entity
           object or the entity ID string.

        2. **Entity's version_number attribute** (secondary): If the entity object has
           a `version_number` attribute set and no explicit `version` parameter is
           provided, this version will be used.

        3. **version_only parameter**: When set to True, indicates that only a specific
           version should be deleted (not the entire entity). This parameter is only
           meaningful when combined with a version number from either the `version`
           parameter or the entity's `version_number` attribute.

        **Supported for version-specific deletion:**

        - String ID with version (e.g., "syn123.4")
        - File, RecordSet (use version_only=True)
        - Table, Dataset, DatasetCollection, EntityView, MaterializedView,
          SubmissionView, VirtualTable (use version_only=True)

        **Not supported for version-specific deletion:**

        - Project, Folder, Evaluation, Team, SchemaOrganization, CurationTask, Grid

    Arguments:
        entity: The entity instance to delete, or a Synapse ID string (e.g., "syn123456"
            or "syn123456.4" for a specific version). Must be one of the supported
            entity types or a valid Synapse ID.
        version: Optional version number to delete. Takes precedence over any version
            information in the entity object or ID string. When provided with
            `version_only=True`, deletes only this specific version.
        version_only: If True, only the specified version will be deleted, not the
            entire entity. Requires a version number from either the `version` parameter
            or the entity's `version_number` attribute. This parameter is applicable for
            entities that support version-specific deletion (File, RecordSet, Table,
            Dataset, DatasetCollection, EntityView, MaterializedView, SubmissionView,
            VirtualTable, JSONSchema).
        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 is not a supported type or not a valid Synapse ID.
        ValueError: If version_only is True but no version number is available.

    Example: Deleting a file by object
        Delete a file from Synapse:

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

        syn = Synapse()
        syn.login()

        file = File(id="syn123456")
        delete(file)
        print("File deleted successfully")
        ```

    Example: Deleting a specific version of a file
        Delete only version 2 of a file, keeping other versions:

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

        syn = Synapse()
        syn.login()

        # Method 1: Using version parameter (highest priority)
        file = File(id="syn123456")
        delete(file, version=2, version_only=True)

        # Method 2: Using entity's version_number attribute
        file = File(id="syn123456", version_number=2)
        delete(file, version_only=True)

        # Method 3: Using synapse ID with version
        delete("syn123456.2", version_only=True)
        print("File version 2 deleted successfully")
        ```

    Example: Deleting a file by ID string
        Delete a file from Synapse using just its ID:

        ```python
        from synapseclient import Synapse
        from synapseclient.operations import delete

        syn = Synapse()
        syn.login()

        delete("syn123456")
        print("Entity deleted successfully")
        ```

    Example: Deleting a project
        Delete a project from Synapse:

        ```python
        from synapseclient import Synapse
        from synapseclient.models import Project
        from synapseclient.operations import delete

        syn = Synapse()
        syn.login()

        project = Project(id="syn123456")
        delete(project)
        print("Project deleted successfully")
        ```

    Example: Deleting a specific version of a RecordSet
        Delete only a specific version of a RecordSet:

        ```python
        from synapseclient import Synapse
        from synapseclient.models import RecordSet
        from synapseclient.operations import delete

        syn = Synapse()
        syn.login()

        record_set = RecordSet(id="syn123456", version_number=3)
        delete(record_set, version_only=True)
        print("RecordSet version 3 deleted successfully")
        ```

    Example: Deleting a table
        Delete a table from Synapse:

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

        syn = Synapse()
        syn.login()

        table = Table(id="syn123456")
        delete(table)
        print("Table deleted successfully")
        ```

    Example: Deleting a team
        Delete a team from Synapse:

        ```python
        from synapseclient import Synapse
        from synapseclient.models import Team
        from synapseclient.operations import delete

        syn = Synapse()
        syn.login()

        team = Team(id="123456")
        delete(team)
        print("Team deleted successfully")
        ```

    Example: Deleting a curation task
        Delete a curation task from Synapse:

        ```python
        from synapseclient import Synapse
        from synapseclient.models import CurationTask
        from synapseclient.operations import delete

        syn = Synapse()
        syn.login()

        task = CurationTask(task_id=123)
        delete(task)
        print("Curation task deleted successfully")
        ```
    """
    return wrap_async_to_sync(
        coroutine=delete_async(
            entity=entity,
            version=version,
            version_only=version_only,
            synapse_client=synapse_client,
        )
    )

synapseclient.operations.store ¶

store(entity: Union[AgentSession, CurationTask, Dataset, DatasetCollection, EntityView, Evaluation, File, Folder, FormData, FormGroup, Grid, JSONSchema, Link, MaterializedView, Project, RecordSet, SchemaOrganization, SubmissionView, Table, Team, VirtualTable], parent: Optional[Union[Folder, Project]] = None, *, file_options: Optional[StoreFileOptions] = None, container_options: Optional[StoreContainerOptions] = None, table_options: Optional[StoreTableOptions] = None, json_schema_options: Optional[StoreJSONSchemaOptions] = None, grid_options: Optional[StoreGridOptions] = None, synapse_client: Optional[Synapse] = None) -> Union[AgentSession, CurationTask, Dataset, DatasetCollection, EntityView, Evaluation, File, Folder, FormData, FormGroup, Grid, JSONSchema, Link, MaterializedView, Project, RecordSet, SchemaOrganization, SubmissionView, Table, Team, VirtualTable]

Factory method to store any Synapse entity.

This method serves as a unified interface for storing any type of Synapse entity. It automatically applies the appropriate store logic based on the entity type and the options provided.

PARAMETER	DESCRIPTION
`entity`	The entity instance to store. Must be one of the supported entity types. TYPE: `Union[AgentSession, CurationTask, Dataset, DatasetCollection, EntityView, Evaluation, File, Folder, FormData, FormGroup, Grid, JSONSchema, Link, MaterializedView, Project, RecordSet, SchemaOrganization, SubmissionView, Table, Team, VirtualTable]`
`parent`	The parent folder or project to store the entity in. Only applicable for File, Folder, Link, and RecordSet entities. Ignored for other entity types. TYPE: `Optional[Union[Folder, Project]]` DEFAULT: `None`
`file_options`	File-specific configuration options. Only applies to File and RecordSet entities. Ignored for other entity types. TYPE: `Optional[StoreFileOptions]` DEFAULT: `None`
`container_options`	Container-specific configuration options. Only applies to Project and Folder entities. Ignored for other entity types. TYPE: `Optional[StoreContainerOptions]` DEFAULT: `None`
`table_options`	Table-specific configuration options. Only applies to Table-like entities (Table, Dataset, EntityView, MaterializedView, SubmissionView, VirtualTable, DatasetCollection). Ignored for other entity types. TYPE: `Optional[StoreTableOptions]` DEFAULT: `None`
`json_schema_options`	JSONSchema-specific configuration options. Only applies to JSONSchema entities. Required for JSONSchema. Ignored for other entity types. TYPE: `Optional[StoreJSONSchemaOptions]` DEFAULT: `None`
`grid_options`	Grid-specific configuration options. Only applies to Grid entities. Ignored for other entity types. TYPE: `Optional[StoreGridOptions]` 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
`Union[AgentSession, CurationTask, Dataset, DatasetCollection, EntityView, Evaluation, File, Folder, FormData, FormGroup, Grid, JSONSchema, Link, MaterializedView, Project, RecordSet, SchemaOrganization, SubmissionView, Table, Team, VirtualTable]`	The stored Synapse entity model instance.

RAISES	DESCRIPTION
`ValueError`	If the entity is not a supported type.

Storing a file

Store a file to Synapse:

from synapseclient import Synapse
from synapseclient.models import File
from synapseclient.operations import store

syn = Synapse()
syn.login()

file = File(path="/path/to/file.txt", parent_id="syn123456")
stored_file = store(file)
print(f"Stored file: {stored_file.name} (ID: {stored_file.id})")

Storing a file with custom options

Store a file with custom options:

from synapseclient import Synapse
from synapseclient.models import File
from synapseclient.operations import store, StoreFileOptions

syn = Synapse()
syn.login()

file = File(path="/path/to/file.txt", parent_id="syn123456")
stored_file = store(
    file,
    file_options=StoreFileOptions(
        synapse_store=True,
        content_type="text/plain",
        merge_existing_annotations=True
    )
)
print(f"Stored file: {stored_file.name}")

Storing a folder

Store a folder to Synapse:

from synapseclient import Synapse
from synapseclient.models import Folder
from synapseclient.operations import store

syn = Synapse()
syn.login()

folder = Folder(name="My Folder", parent_id="syn123456")
stored_folder = store(folder)
print(f"Stored folder: {stored_folder.name} (ID: {stored_folder.id})")

Storing a project

Store a project to Synapse:

from synapseclient import Synapse
from synapseclient.models import Project
from synapseclient.operations import store

syn = Synapse()
syn.login()

project = Project(name="My Project")
stored_project = store(project)
print(f"Stored project: {stored_project.name} (ID: {stored_project.id})")

Storing a table

Store a table to Synapse:

from synapseclient import Synapse
from synapseclient.models import Table, Column, ColumnType
from synapseclient.operations import store, StoreTableOptions

syn = Synapse()
syn.login()

table = Table(
    name="My Table",
    parent_id="syn123456",
    columns=[Column(name="col1", column_type=ColumnType.STRING, maximum_size=50)]
)
stored_table = store(
    table,
    table_options=StoreTableOptions(dry_run=False, job_timeout=600)
)
print(f"Stored table: {stored_table.name} (ID: {stored_table.id})")

Storing a link

Store a link to Synapse:

from synapseclient import Synapse
from synapseclient.models import Link
from synapseclient.operations import store

syn = Synapse()
syn.login()

link = Link(name="My Link", parent_id="syn123456", target_id="syn789")
stored_link = store(link)
print(f"Stored link: {stored_link.name} (ID: {stored_link.id})")

Storing with parent parameter

Store an entity by passing the parent as a parameter:

from synapseclient import Synapse
from synapseclient.models import File, Folder
from synapseclient.operations import store

syn = Synapse()
syn.login()

parent_folder = Folder(id="syn123456")
file = File(path="/path/to/file.txt")
stored_file = store(file, parent=parent_folder)
print(f"Stored file: {stored_file.name} in folder {parent_folder.id}")

Storing an Evaluation

Store an evaluation (challenge queue):

from synapseclient import Synapse
from synapseclient.models import Evaluation
from synapseclient.operations import store

syn = Synapse()
syn.login()

evaluation = Evaluation(
    name="My Challenge Evaluation",
    description="Evaluation for my data challenge",
    content_source="syn123456"
)
stored_evaluation = store(evaluation)
print(f"Stored evaluation: {stored_evaluation.name} (ID: {stored_evaluation.id})")

Creating a Team

Create a new team (note: Teams use create, not update):

from synapseclient import Synapse
from synapseclient.models import Team
from synapseclient.operations import store

syn = Synapse()
syn.login()

team = Team(
    name="My Research Team",
    description="A team for collaborative research"
)
created_team = store(team)
print(f"Created team: {created_team.name} (ID: {created_team.id})")

Storing a CurationTask

Store a curation task:

from synapseclient import Synapse
from synapseclient.models import CurationTask, FileBasedMetadataTaskProperties
from synapseclient.operations import store

syn = Synapse()
syn.login()

file_properties = FileBasedMetadataTaskProperties(
    upload_folder_id="syn1234567",
    file_view_id="syn2345678"
)
task = CurationTask(
    project_id="syn9876543",
    data_type="genomics_data",
    instructions="Upload your genomics files",
    task_properties=file_properties
)
stored_task = store(task)
print(f"Stored curation task: {stored_task.task_id}")