How to get the snapshot id of a tag

[frankliee]

Question

pyiceberg has provided the snapshot_id for scanning, but there is not api to get the snapshot_id from a given tag

scan(xxx, snapshot_id: Optional[int] = None, xxx)

[ForeverAngry]

I think this would probably require an update to the table __init__.py file, soemthing like this:

    def scan_by_tag(
        self,
        tag_name: str,
        row_filter: Union[str, BooleanExpression] = ALWAYS_TRUE,
        selected_fields: Tuple[str, ...] = ("*",),
        case_sensitive: bool = True,
        options: Properties = EMPTY_DICT,
        limit: Optional[int] = None,
    ) -> DataScan:
        """
        Fetch a DataScan for the snapshot referenced by the given tag.

        Args:
            tag_name: Name of the tag to scan
            row_filter: A string or BooleanExpression that describes the desired rows
            selected_fields: A tuple of strings representing the column names to return
            case_sensitive: If True column matching is case sensitive
            options: Additional Table properties as a dictionary of string key value pairs
            limit: An integer representing the number of rows to return

        Returns:
            A DataScan for the snapshot referenced by the given tag

        Raises:
            ValueError: If the tag does not exist or is not a valid tag
        """
        snapshot_id = self.get_snapshot_id_by_tag(tag_name)
        return self.scan(
            row_filter=row_filter,
            selected_fields=selected_fields,
            case_sensitive=case_sensitive,
            snapshot_id=snapshot_id,
            options=options,
            limit=limit,
        )


    def get_snapshot_id_by_tag(self, tag_name: str) -> int:
        """
        Get the snapshot ID associated with a given tag.

        Args:
            tag_name (str): The name of the tag.

        Returns:
            int: The snapshot ID associated with the tag.

        Raises:
            ValueError: If the tag does not exist or is not a valid tag.
        """
        ref = self._transaction.table_metadata.refs.get(tag_name)
        if ref is None or ref.snapshot_ref_type != SnapshotRefType.TAG:
            raise ValueError(f"Tag '{tag_name}' does not exist or is not a valid tag.")
        return ref.snapshot_id

@kevinjqliu @jayceslesar any thoughts?

Im happy to add it, if it would be helpful.

[jayceslesar]

Can we not get the snapshot_id via the table.refs() and pass one of those in?

Or even better there is snapshot_by_name

[ForeverAngry]

@jayceslesar your thinking something like this, yeah?

def scan_by_tag(
    self,
    tag_name: str,
    row_filter: Union[str, BooleanExpression] = ALWAYS_TRUE,
    selected_fields: Tuple[str, ...] = ("*",),
    case_sensitive: bool = True,
    options: Properties = EMPTY_DICT,
    limit: Optional[int] = None,
) -> DataScan:
    """
    Fetch a DataScan for the snapshot referenced by the given tag.
    """
    snapshot = self.snapshot_by_name(tag_name)
    if snapshot is None:
        raise ValueError(f"Tag '{tag_name}' does not exist or is not a valid tag.")
    return self.scan(
        row_filter=row_filter,
        selected_fields=selected_fields,
        case_sensitive=case_sensitive,
        snapshot_id=snapshot.snapshot_id,
        options=options,
        limit=limit,
    )

[kevinjqliu]

there is not api to get the snapshot_id from a given tag

as @.jayceslesar mentioned, Table has snapshot_by_name which can take in a tag name.

Something like this should work,

snapshot = tbl.snapshot_by_name(tag_name)
scan(xxx, snapshot_id = snapshot.snapshot_id, xxx)

I dont think we need a new scan api, we can just reuse the original

[frankliee]

there is not api to get the snapshot_id from a given tag

as @.jayceslesar mentioned, Table has snapshot_by_name which can take in a tag name.

Something like this should work,

snapshot = tbl.snapshot_by_name(tag_name)
scan(xxx, snapshot_id = snapshot.snapshot_id, xxx)

I dont think we need a new scan api, we can just reuse the original

I works

[jayceslesar]

It would be great to add an example of this to the docs I think, we only ever touch on the snapshot_by_name directly in the code reference, and refs are only mentioned in the inspecting tables section of the API tab