snowflake-ml-python 1.4.0__py3-none-any.whl → 1.5.0__py3-none-any.whl

snowflake/ml/feature_store/feature_view.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import json
 import re
 from collections import OrderedDict
-from dataclasses import dataclass
+from dataclasses import asdict, dataclass
 from enum import Enum
 from typing import Dict, List, Optional
 
@@ -29,22 +29,42 @@ from snowflake.snowpark.types import (
 _FEATURE_VIEW_NAME_DELIMITER = "$"
 _TIMESTAMP_COL_PLACEHOLDER = "FS_TIMESTAMP_COL_PLACEHOLDER_VAL"
 _FEATURE_OBJ_TYPE = "FEATURE_OBJ_TYPE"
-_FEATURE_VIEW_VERSION_RE = re.compile("^([A-Za-z0-9_]*)$")
+# Feature view version rule is aligned with dataset version rule in SQL.
+_FEATURE_VIEW_VERSION_RE = re.compile(r"^[a-zA-Z0-9][a-zA-Z0-9_.\-]*$")
+_FEATURE_VIEW_VERSION_MAX_LENGTH = 128
+
+
+@dataclass(frozen=True)
+class _FeatureViewMetadata:
+    """Represent metadata tracked on top of FV backend object"""
+
+    entities: List[str]
+    timestamp_col: str
+
+    def to_json(self) -> str:
+        return json.dumps(asdict(self))
+
+    @classmethod
+    def from_json(cls, json_str: str) -> _FeatureViewMetadata:
+        state_dict = json.loads(json_str)
+        return cls(**state_dict)
 
 
 class FeatureViewVersion(str):
     def __new__(cls, version: str) -> FeatureViewVersion:
-        if not _FEATURE_VIEW_VERSION_RE.match(version):
+        if not _FEATURE_VIEW_VERSION_RE.match(version) or len(version) > _FEATURE_VIEW_VERSION_MAX_LENGTH:
             raise snowml_exceptions.SnowflakeMLException(
                 error_code=error_codes.INVALID_ARGUMENT,
                 original_exception=ValueError(
-                    f"`{version}` is not a valid feature view version. Only letter, number and underscore is allowed."
+                    f"`{version}` is not a valid feature view version. "
+                    "It must start with letter or digit, and followed by letter, digit, '_', '-' or '.'. "
+                    f"The length limit is {_FEATURE_VIEW_VERSION_MAX_LENGTH}."
                 ),
             )
-        return super().__new__(cls, version.upper())
+        return super().__new__(cls, version)
 
     def __init__(self, version: str) -> None:
-        return super().__init__()
+        super().__init__()
 
 
 class FeatureViewStatus(Enum):
@@ -164,27 +184,19 @@ class FeatureView:
             res.append(name)
         return FeatureViewSlice(self, res)
 
-    def physical_name(self) -> SqlIdentifier:
-        """Returns the physical name for this feature in Snowflake.
-
-        Returns:
-            Physical name string.
-
-        Raises:
-            RuntimeError: if the FeatureView is not materialized.
-        """
-        if self.status == FeatureViewStatus.DRAFT or self.version is None:
-            raise RuntimeError(f"FeatureView {self.name} has not been materialized.")
-        return FeatureView._get_physical_name(self.name, self.version)
-
     def fully_qualified_name(self) -> str:
         """Returns the fully qualified name (<database_name>.<schema_name>.<feature_view_name>) for the
             FeatureView in Snowflake.
 
         Returns:
             fully qualified name string.
+
+        Raises:
+            RuntimeError: if the FeatureView is not registered.
         """
-        return f"{self._database}.{self._schema}.{self.physical_name()}"
+        if self.status == FeatureViewStatus.DRAFT or self.version is None:
+            raise RuntimeError(f"FeatureView {self.name} has not been registered.")
+        return f"{self._database}.{self._schema}.{FeatureView._get_physical_name(self.name, self.version)}"
 
     def attach_feature_desc(self, descs: Dict[str, str]) -> FeatureView:
         """
@@ -297,6 +309,11 @@ class FeatureView:
     def owner(self) -> Optional[str]:
         return self._owner
 
+    def _metadata(self) -> _FeatureViewMetadata:
+        entity_names = [e.name.identifier() for e in self.entities]
+        ts_col = self.timestamp_col.identifier() if self.timestamp_col is not None else _TIMESTAMP_COL_PLACEHOLDER
+        return _FeatureViewMetadata(entity_names, ts_col)
+
     def _get_query(self) -> str:
         if len(self._feature_df.queries["queries"]) != 1:
             raise ValueError(
@@ -386,7 +403,7 @@ Got {len(self._feature_df.queries['queries'])}: {self._feature_df.queries['queri
     def to_df(self, session: Session) -> DataFrame:
         values = list(self._to_dict().values())
         schema = [x.lstrip("_") for x in list(self._to_dict().keys())]
-        values.append(str(self.physical_name()))
+        values.append(str(FeatureView._get_physical_name(self._name, self._version)))  # type: ignore[arg-type]
         schema.append("physical_name")
         return session.create_dataframe([values], schema=schema)
 
@@ -448,8 +465,8 @@ Got {len(self._feature_df.queries['queries'])}: {self._feature_df.queries['queri
         status: FeatureViewStatus,
         feature_descs: Dict[str, str],
         refresh_freq: Optional[str],
-        database: Optional[str],
-        schema: Optional[str],
+        database: str,
+        schema: str,
         warehouse: Optional[str],
         refresh_mode: Optional[str],
         refresh_mode_reason: Optional[str],

snowflake/ml/fileset/embedded_stage_fs.py

@@ -0,0 +1,146 @@
+import re
+from collections import defaultdict
+from typing import Any, List, Optional, Tuple
+
+from snowflake import snowpark
+from snowflake.connector import connection
+from snowflake.ml._internal import telemetry
+from snowflake.ml._internal.exceptions import (
+    error_codes,
+    exceptions as snowml_exceptions,
+    fileset_errors,
+)
+from snowflake.ml._internal.utils import identifier
+from snowflake.snowpark import exceptions as snowpark_exceptions
+
+from . import stage_fs
+
+_SNOWURL_PATH_RE = re.compile(r"versions/(?P<version>[^/]+)(?:/+(?P<filepath>.*))?")
+
+
+class SFEmbeddedStageFileSystem(stage_fs.SFStageFileSystem):
+    def __init__(
+        self,
+        *,
+        domain: str,
+        name: str,
+        snowpark_session: Optional[snowpark.Session] = None,
+        sf_connection: Optional[connection.SnowflakeConnection] = None,
+        **kwargs: Any,
+    ) -> None:
+
+        (db, schema, object_name, _) = identifier.parse_schema_level_object_identifier(name)
+        self._name = name  # TODO: Require or resolve FQN
+        self._domain = domain
+
+        super().__init__(
+            db=db,
+            schema=schema,
+            stage=object_name,
+            snowpark_session=snowpark_session,
+            sf_connection=sf_connection,
+            **kwargs,
+        )
+
+    @property
+    def stage_name(self) -> str:
+        """Get the Snowflake path to this stage.
+
+        Returns:
+            A string in the format of snow://<domain>/<name>
+                Example: snow://dataset/my_dataset
+
+        # noqa: DAR203
+        """
+        return f"snow://{self._domain}/{self._name}"
+
+    def _stage_path_to_relative_path(self, stage_path: str) -> str:
+        """Convert a stage file path which comes from the LIST query to a relative file path in that stage.
+
+        The file path returned by LIST query always has the format "versions/<version>/<relative_file_path>".
+                The full "versions/<version>/<relative_file_path>" is returned
+
+        Args:
+            stage_path: A string started with the name of the stage.
+
+        Returns:
+            A string of the relative stage path.
+        """
+        return stage_path
+
+    def _fetch_presigned_urls(
+        self, files: List[str], url_lifetime: float = stage_fs._PRESIGNED_URL_LIFETIME_SEC
+    ) -> List[Tuple[str, str]]:
+        """Fetch presigned urls for the given files."""
+        # SnowURL requires full snow://<domain>/<entity>/versions/<version> as the stage path arg to get_presigned_Url
+        versions_dict = defaultdict(list)
+        for file in files:
+            match = _SNOWURL_PATH_RE.fullmatch(file)
+            assert match is not None and match.group("filepath") is not None
+            versions_dict[match.group("version")].append(match.group("filepath"))
+        presigned_urls: List[Tuple[str, str]] = []
+        try:
+            for version, version_files in versions_dict.items():
+                for file in version_files:
+                    stage_loc = f"{self.stage_name}/versions/{version}"
+                    presigned_urls.extend(
+                        self._session.sql(
+                            f"select '{version}/{file}' as name,"
+                            f" get_presigned_url('{stage_loc}', '{file}', {url_lifetime}) as url"
+                        ).collect(
+                            statement_params=telemetry.get_function_usage_statement_params(
+                                project=stage_fs._PROJECT,
+                                api_calls=[snowpark.DataFrame.collect],
+                            ),
+                        )
+                    )
+        except snowpark_exceptions.SnowparkClientException as e:
+            if e.message.startswith(fileset_errors.ERRNO_DOMAIN_NOT_EXIST) or e.message.startswith(
+                fileset_errors.ERRNO_STAGE_NOT_EXIST
+            ):
+                raise snowml_exceptions.SnowflakeMLException(
+                    error_code=error_codes.SNOWML_NOT_FOUND,
+                    original_exception=fileset_errors.StageNotFoundError(
+                        f"Stage {self.stage_name} does not exist or is not authorized."
+                    ),
+                )
+            else:
+                raise snowml_exceptions.SnowflakeMLException(
+                    error_code=error_codes.INTERNAL_SNOWML_ERROR,
+                    original_exception=fileset_errors.FileSetError(str(e)),
+                )
+        return presigned_urls
+
+    @classmethod
+    def _parent(cls, path: str) -> str:
+        """Get parent of specified path up to minimally valid root path.
+
+        For SnowURL, the minimum valid path is snow://<domain>/<entity>/versions/<version>
+
+        Args:
+            path: File or directory path
+
+        Returns:
+            Parent path
+
+        Examples:
+        ----
+        >>> fs._parent("snow://dataset/my_ds/versions/my_version/file.ext")
+        "snow://dataset/my_ds/versions/my_version/"
+        >>> fs._parent("snow://dataset/my_ds/versions/my_version/subdir/file.ext")
+        "snow://dataset/my_ds/versions/my_version/subdir/"
+        >>> fs._parent("snow://dataset/my_ds/versions/my_version/")
+        "snow://dataset/my_ds/versions/my_version/"
+        >>> fs._parent("snow://dataset/my_ds/versions/my_version")
+        "snow://dataset/my_ds/versions/my_version"
+        """
+        path_match = _SNOWURL_PATH_RE.fullmatch(path)
+        if not path_match:
+            return super()._parent(path)  # type: ignore[no-any-return]
+        filepath: str = path_match.group("filepath") or ""
+        root: str = path[: path_match.start("filepath")] if filepath else path
+        if "/" in filepath:
+            parent = filepath.rsplit("/", 1)[0]
+            return root + parent
+        else:
+            return root

snowflake/ml/fileset/sfcfs.py

@@ -60,6 +60,8 @@ class SFFileSystem(fsspec.AbstractFileSystem):
     b'2014-02-05 14:35:00.00000054,13,2014-02-05 14:35:00 UTC,-74.00688,40.73049,-74.00563,40.70676,2\n'
     """
 
+    protocol = PROTOCOL_NAME
+
     def __init__(
         self,
         sf_connection: Optional[connection.SnowflakeConnection] = None,
@@ -183,7 +185,6 @@ class SFFileSystem(fsspec.AbstractFileSystem):
         func_params_to_log=["detail"],
         conn_attr_name="_conn",
     )
-    @snowpark._internal.utils.private_preview(version="0.2.0")
     def ls(self, path: str, detail: bool = False, **kwargs: Any) -> Union[List[str], List[Dict[str, Any]]]:
         """Override fsspec `ls` method. List single "directory" with or without details.
 
@@ -204,7 +205,7 @@ class SFFileSystem(fsspec.AbstractFileSystem):
         >>> sffs.ls("@MYDB.public.FOO/nytrain/")
         ['@MYDB.public.FOO/nytrain/data_0_0_0.csv', '@MYDB.public.FOO/nytrain/data_0_0_1.csv']
         """
-        file_path = _parse_sfc_file_path(path)
+        file_path = self._parse_file_path(path)
         stage_fs = self._get_stage_fs(file_path)
         stage_path_list = stage_fs.ls(file_path.filepath, detail=True, **kwargs)
         stage_path_list = cast(List[Dict[str, Any]], stage_path_list)
@@ -214,7 +215,6 @@ class SFFileSystem(fsspec.AbstractFileSystem):
         project=_PROJECT,
         conn_attr_name="_conn",
     )
-    @snowpark._internal.utils.private_preview(version="0.2.0")
     def optimize_read(self, files: Optional[List[str]] = None) -> None:
         """Prefetch and cache the presigned urls for all the given files to speed up the file opening.
 
@@ -226,19 +226,20 @@ class SFFileSystem(fsspec.AbstractFileSystem):
         """
         if not files:
             return
-        stage_file_paths: Dict[Tuple[str, str, str], List[str]] = collections.defaultdict(list)
+        stage_fs_dict: Dict[str, stage_fs.SFStageFileSystem] = {}
+        stage_file_paths: Dict[str, List[str]] = collections.defaultdict(list)
         for file in files:
-            file_path = _parse_sfc_file_path(file)
-            stage_file_paths[(file_path.database, file_path.schema, file_path.stage)].append(file_path.filepath)
+            path_info = self._parse_file_path(file)
+            fs = self._get_stage_fs(path_info)
+            stage_fs_dict[fs.stage_name] = fs
+            stage_file_paths[fs.stage_name].append(path_info.filepath)
         for k, v in stage_file_paths.items():
-            stage_fs = self._get_stage_fs(_SFFilePath(k[0], k[1], k[2], "*"))
-            stage_fs.optimize_read(v)
+            stage_fs_dict[k].optimize_read(v)
 
     @telemetry.send_api_usage_telemetry(
         project=_PROJECT,
         conn_attr_name="_conn",
     )
-    @snowpark._internal.utils.private_preview(version="0.2.0")
     def _open(self, path: str, **kwargs: Any) -> fsspec.spec.AbstractBufferedFile:
         """Override fsspec `_open` method. Open a file for reading in 'rb' mode.
 
@@ -256,7 +257,7 @@ class SFFileSystem(fsspec.AbstractFileSystem):
         Returns:
             A fsspec AbstractBufferedFile which supports python file operations.
         """
-        file_path = _parse_sfc_file_path(path)
+        file_path = self._parse_file_path(path)
         stage_fs = self._get_stage_fs(file_path)
         return stage_fs._open(file_path.filepath, **kwargs)
 
@@ -264,10 +265,9 @@ class SFFileSystem(fsspec.AbstractFileSystem):
         project=_PROJECT,
         conn_attr_name="_conn",
     )
-    @snowpark._internal.utils.private_preview(version="0.2.0")
     def info(self, path: str, **kwargs: Any) -> Dict[str, Any]:
         """Override fsspec `info` method. Give details of entry at path."""
-        file_path = _parse_sfc_file_path(path)
+        file_path = self._parse_file_path(path)
         stage_fs = self._get_stage_fs(file_path)
         res: Dict[str, Any] = stage_fs.info(file_path.filepath, **kwargs)
         if res:
@@ -292,52 +292,54 @@ class SFFileSystem(fsspec.AbstractFileSystem):
         """Convert the relative path in a stage to an absolute path starts with the location of the stage."""
         return stage_fs.stage_name + "/" + path
 
+    @classmethod
+    def _parse_file_path(cls, path: str) -> _SFFilePath:
+        """Parse a snowflake location path.
 
-fsspec.register_implementation(PROTOCOL_NAME, SFFileSystem)
-
+        The following propertis will be extracted from the path input:
+        - database
+        - schema
+        - stage
+        - path (optional)
 
-def _parse_sfc_file_path(path: str) -> _SFFilePath:
-    """Parse a snowflake location path.
+        Args:
+            path: A string in the format of "@{database}.{schema}.{stage}/{path}".
 
-    The following propertis will be extracted from the path input:
-    - database
-    - schema
-    - stage
-    - path (optional)
+                Example:
+                    "@my_db.my_schema.my_stage/"
+                    "@my_db.my_schema.my_stage/file1"
+                    "@my_db.my_schema.my_stage/dir1/"
+                    "@my_db.my_schema.my_stage/dir1/file2"
 
-    Args:
-        path: A string in the format of "@{database}.{schema}.{stage}/{path}".
+        Returns:
+            A namedtuple consists of database name, schema name, stage name and path.
 
-            Example:
-                "@my_db.my_schema.my_stage/"
-                "@my_db.my_schema.my_stage/file1"
-                "@my_db.my_schema.my_stage/dir1/"
-                "@my_db.my_schema.my_stage/dir1/file2"
+        Raises:
+            SnowflakeMLException: An error occurred when invalid path is given.
+        """
+        sfc_prefix = f"{PROTOCOL_NAME}://"
+        if path.startswith(sfc_prefix):
+            path = path[len(sfc_prefix) :]
+        if not path.startswith("@"):
+            raise snowml_exceptions.SnowflakeMLException(
+                error_code=error_codes.SNOWML_INVALID_STAGE,
+                original_exception=ValueError(
+                    'Invalid path. Expected path to start with "@". Example: @database.schema.stage/optional_path.'
+                ),
+            )
+        try:
+            res = identifier.parse_schema_level_object_identifier(path[1:])
+            if res[1] is None or res[0] is None or (res[3] and not res[3].startswith("/")):
+                raise ValueError("Invalid path. Missing database or schema identifier.")
+            logging.debug(f"Parsed path: {res}")
+            return _SFFilePath(res[0], res[1], res[2], res[3][1:])
+        except ValueError:
+            raise snowml_exceptions.SnowflakeMLException(
+                error_code=error_codes.SNOWML_INVALID_STAGE,
+                original_exception=ValueError(
+                    f"Invalid path. Expected format: @database.schema.stage/optional_path. Getting {path}"
+                ),
+            )
 
-    Returns:
-        A namedtuple consists of database name, schema name, stage name and path.
 
-    Raises:
-        SnowflakeMLException: An error occurred when invalid path is given.
-    """
-    sfc_prefix = f"{PROTOCOL_NAME}://"
-    if path.startswith(sfc_prefix):
-        path = path[len(sfc_prefix) :]
-    if not path.startswith("@"):
-        raise snowml_exceptions.SnowflakeMLException(
-            error_code=error_codes.SNOWML_INVALID_STAGE,
-            original_exception=ValueError(
-                'Invalid path. Expected path to start with "@". Example: @database.schema.stage/optional_path.'
-            ),
-        )
-    try:
-        res = identifier.parse_schema_level_object_identifier(path[1:])
-        logging.debug(f"Parsed path: {res}")
-        return _SFFilePath(res[0], res[1], res[2], res[3][1:])
-    except ValueError:
-        raise snowml_exceptions.SnowflakeMLException(
-            error_code=error_codes.SNOWML_INVALID_STAGE,
-            original_exception=ValueError(
-                f"Invalid path. Expected format: @database.schema.stage/optional_path. Getting {path}"
-            ),
-        )
+fsspec.register_implementation(PROTOCOL_NAME, SFFileSystem)

snowflake/ml/fileset/snowfs.py

@@ -0,0 +1,159 @@
+import collections
+import logging
+import re
+from typing import Any, Dict, Optional
+
+import fsspec
+import packaging.version as pkg_version
+
+from snowflake import snowpark
+from snowflake.connector import connection
+from snowflake.ml._internal.exceptions import (
+    error_codes,
+    exceptions as snowml_exceptions,
+)
+from snowflake.ml._internal.utils import identifier, snowflake_env
+from snowflake.ml.fileset import embedded_stage_fs, sfcfs
+
+PROTOCOL_NAME = "snow"
+
+_SFFileEntityPath = collections.namedtuple(
+    "_SFFileEntityPath", ["domain", "name", "filepath", "version", "relative_path"]
+)
+_PROJECT = "FileSet"
+_SNOWURL_PATTERN = re.compile(
+    f"({PROTOCOL_NAME}://)?"
+    r"(?<!@)(?P<domain>\w+)/"
+    rf"(?P<name>(?:{identifier._SF_IDENTIFIER}\.){{,2}}{identifier._SF_IDENTIFIER})/"
+    r"(?P<path>versions/(?:(?P<version>[^/]+)(?:/(?P<relpath>.*))?)?)"
+)
+
+# FIXME(dhung): Temporary fix for bug in GS version 8.17
+_BUG_VERSION_MIN = pkg_version.Version("8.17")  # Inclusive minimum version with bugged behavior
+_BUG_VERSION_MAX = pkg_version.Version("8.18")  # Exclusive maximum version with bugged behavior
+
+
+class SnowFileSystem(sfcfs.SFFileSystem):
+    """A filesystem that allows user to access Snowflake embedded stage files with valid Snowflake locations.
+
+    The file system is is based on fsspec (https://filesystem-spec.readthedocs.io/). It is a file system wrapper
+    built on top of SFStageFileSystem. It takes Snowflake embedded stage path as the input and supports read operation.
+    A valid Snowflake location will have the form "snow://{domain}/{entity_name}/versions/{version}/{path_to_file}".
+
+    See `sfcfs.SFFileSystem` documentation for example usage patterns.
+    """
+
+    protocol = PROTOCOL_NAME
+    _IS_BUGGED_VERSION = None
+
+    def __init__(
+        self,
+        sf_connection: Optional[connection.SnowflakeConnection] = None,
+        snowpark_session: Optional[snowpark.Session] = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(sf_connection=sf_connection, snowpark_session=snowpark_session, **kwargs)
+
+        # FIXME(dhung): Temporary fix for bug in GS version 8.17
+        if SnowFileSystem._IS_BUGGED_VERSION is None:
+            try:
+                sf_version = snowflake_env.get_current_snowflake_version(self._session)
+                SnowFileSystem._IS_BUGGED_VERSION = _BUG_VERSION_MIN <= sf_version < _BUG_VERSION_MAX
+            except Exception:
+                SnowFileSystem._IS_BUGGED_VERSION = False
+
+    def info(self, path: str, **kwargs: Any) -> Dict[str, Any]:
+        # FIXME(dhung): Temporary fix for bug in GS version 8.17
+        res: Dict[str, Any] = super().info(path, **kwargs)
+        if res.get("type") == "directory" and not res["name"].endswith("/"):
+            res["name"] += "/"
+        return res
+
+    def _get_stage_fs(
+        self, sf_file_path: _SFFileEntityPath  # type: ignore[override]
+    ) -> embedded_stage_fs.SFEmbeddedStageFileSystem:
+        """Get the stage file system for the given snowflake location.
+
+        Args:
+            sf_file_path: The Snowflake path information.
+
+        Returns:
+            A SFEmbeddedStageFileSystem object which supports readonly file operations on Snowflake embedded stages.
+        """
+        stage_fs_key = (sf_file_path.domain, sf_file_path.name, sf_file_path.version)
+        if stage_fs_key not in self._stage_fs_set:
+            cnt_stage_fs = embedded_stage_fs.SFEmbeddedStageFileSystem(
+                snowpark_session=self._session,
+                domain=sf_file_path.domain,
+                name=sf_file_path.name,
+                **self._kwargs,
+            )
+            self._stage_fs_set[stage_fs_key] = cnt_stage_fs
+        return self._stage_fs_set[stage_fs_key]
+
+    def _stage_path_to_absolute_path(self, stage_fs: embedded_stage_fs.SFEmbeddedStageFileSystem, path: str) -> str:
+        """Convert the relative path in a stage to an absolute path starts with the location of the stage."""
+        # Strip protocol from absolute path, since backend needs snow:// prefix to resolve correctly
+        # but fsspec logic strips protocol when doing any searching and globbing
+        stage_name = stage_fs.stage_name
+        protocol = f"{PROTOCOL_NAME}://"
+        if stage_name.startswith(protocol):
+            stage_name = stage_name[len(protocol) :]
+        abs_path = stage_name + "/" + path
+        # FIXME(dhung): Temporary fix for bug in GS version 8.17
+        if self._IS_BUGGED_VERSION:
+            match = _SNOWURL_PATTERN.fullmatch(abs_path)
+            assert match is not None
+            abs_path = abs_path.replace(match.group("relpath"), match.group("relpath").lstrip("/"))
+        return abs_path
+
+    @classmethod
+    def _parse_file_path(cls, path: str) -> _SFFileEntityPath:  # type: ignore[override]
+        """Parse a snowflake location path.
+
+        The following properties will be extracted from the path input:
+        - embedded stage domain
+        - entity name
+        - path (in format `versions/{version}/{relative_path}`)
+        - entity version (optional)
+        - relative file path (optional)
+
+        Args:
+            path: A string in the format of "snow://{domain}/{entity_name}/versions/{version}/{path_to_file}".
+
+        Returns:
+            A namedtuple consists of domain, entity name, filepath, version, and relative path, where
+                filepath = "versions/{version}/{relative_path}"
+
+        Raises:
+            SnowflakeMLException: An error occurred when invalid path is given.
+        """
+        snowurl_match = _SNOWURL_PATTERN.fullmatch(path)
+        if not snowurl_match:
+            raise snowml_exceptions.SnowflakeMLException(
+                error_code=error_codes.SNOWML_INVALID_STAGE,
+                original_exception=ValueError(f"Invalid Snow URL: {path}"),
+            )
+
+        try:
+            domain = snowurl_match.group("domain")
+            parsed_name = identifier.parse_schema_level_object_identifier(snowurl_match.group("name"))
+            name = identifier.get_schema_level_object_identifier(*parsed_name)
+            filepath = snowurl_match.group("path")
+            version = snowurl_match.group("version")
+            relative_path = snowurl_match.group("relpath") or ""
+            logging.debug(f"Parsed snow URL: {snowurl_match.groups()}")
+            # FIXME(dhung): Temporary fix for bug in GS version 8.17
+            if cls._IS_BUGGED_VERSION:
+                filepath = filepath.replace(f"{version}/", f"{version}//")
+            return _SFFileEntityPath(
+                domain=domain, name=name, version=version, relative_path=relative_path, filepath=filepath
+            )
+        except ValueError as e:
+            raise snowml_exceptions.SnowflakeMLException(
+                error_code=error_codes.SNOWML_INVALID_STAGE,
+                original_exception=e,
+            )
+
+
+fsspec.register_implementation(PROTOCOL_NAME, SnowFileSystem)