snowflake-ml-python 1.5.4__py3-none-any.whl → 1.6.1__py3-none-any.whl

snowflake/ml/feature_store/feature_store.py

@@ -52,6 +52,7 @@ from snowflake.ml.feature_store.feature_view import (
     FeatureViewVersion,
     _FeatureViewMetadata,
 )
+from snowflake.ml.utils import sql_client
 from snowflake.snowpark import DataFrame, Row, Session, functions as F
 from snowflake.snowpark.exceptions import SnowparkSQLException
 from snowflake.snowpark.types import (
@@ -94,13 +95,12 @@ class _FeatureStoreObjInfo:
         return cls(**state_dict)  # type: ignore[arg-type]
 
 
-# TODO: remove "" after dataset is updated
 class _FeatureStoreObjTypes(Enum):
     UNKNOWN = "UNKNOWN"  # for forward compatibility
     MANAGED_FEATURE_VIEW = "MANAGED_FEATURE_VIEW"
     EXTERNAL_FEATURE_VIEW = "EXTERNAL_FEATURE_VIEW"
     FEATURE_VIEW_REFRESH_TASK = "FEATURE_VIEW_REFRESH_TASK"
-    TRAINING_DATA = ""
+    TRAINING_DATA = "TRAINING_DATA"
 
     @classmethod
     def parse(cls, val: str) -> _FeatureStoreObjTypes:
@@ -135,13 +135,13 @@ _LIST_FEATURE_VIEW_SCHEMA = StructType(
         StructField("refresh_freq", StringType()),
         StructField("refresh_mode", StringType()),
         StructField("scheduling_state", StringType()),
+        StructField("warehouse", StringType()),
     ]
 )
 
 
-class CreationMode(Enum):
-    FAIL_IF_NOT_EXIST = 1
-    CREATE_IF_NOT_EXIST = 2
+CreationMode = sql_client.CreationOption
+CreationMode.__module__ = __name__
 
 
 @dataclass(frozen=True)
@@ -205,6 +205,7 @@ class FeatureStore:
         database: str,
         name: str,
         default_warehouse: str,
+        *,
         creation_mode: CreationMode = CreationMode.FAIL_IF_NOT_EXIST,
     ) -> None:
         """
@@ -224,6 +225,32 @@ class FeatureStore:
             SnowflakeMLException: [ValueError] Required resources not exist when mode is FAIL_IF_NOT_EXIST.
             SnowflakeMLException: [RuntimeError] Failed to find resources.
             SnowflakeMLException: [RuntimeError] Failed to create feature store.
+
+        Example::
+
+            >>> from snowflake.ml.feature_store import (
+            ...     FeatureStore,
+            ...     CreationMode,
+            ... )
+            <BLANKLINE>
+            >>> # Create a new Feature Store:
+            >>> fs = FeatureStore(
+            ...     session=session,
+            ...     database="MYDB",
+            ...     name="MYSCHEMA",
+            ...     default_warehouse="MYWH",
+            ...     creation_mode=CreationMode.CREATE_IF_NOT_EXIST
+            ... )
+            <BLANKLINE>
+            >>> # Connect to an existing Feature Store:
+            >>> fs = FeatureStore(
+            ...     session=session,
+            ...     database="MYDB",
+            ...     name="MYSCHEMA",
+            ...     default_warehouse="MYWH",
+            ...     creation_mode=CreationMode.FAIL_IF_NOT_EXIST
+            ... )
+
         """
 
         database = SqlIdentifier(database)
@@ -284,6 +311,16 @@ class FeatureStore:
 
         Raises:
             SnowflakeMLException: If warehouse does not exists.
+
+        Example::
+
+            >>> fs = FeatureStore(...)
+            >>> fs.update_default_warehouse("MYWH_2")
+            >>> draft_fv = FeatureView("my_fv", ...)
+            >>> registered_fv = fs.register_feature_view(draft_fv, '2.0')
+            >>> print(registered_fv.warehouse)
+            MYWH_2
+
         """
         warehouse = SqlIdentifier(warehouse_name)
         warehouse_result = self._find_object("WAREHOUSES", warehouse)
@@ -301,15 +338,27 @@ class FeatureStore:
         Register Entity in the FeatureStore.
 
         Args:
-            entity: Entity object to register.
+            entity: Entity object to be registered.
 
         Returns:
             A registered entity object.
 
         Raises:
             SnowflakeMLException: [RuntimeError] Failed to find resources.
-        """
 
+        Example::
+
+            >>> fs = FeatureStore(...)
+            >>> e = Entity('BAR', ['A'], desc='entity bar')
+            >>> fs.register_entity(e)
+            >>> fs.list_entities().show()
+            --------------------------------------------------
+            |"NAME"  |"JOIN_KEYS"  |"DESC"      |"OWNER"     |
+            --------------------------------------------------
+            |BAR     |["A"]        |entity bar  |REGTEST_RL  |
+            --------------------------------------------------
+
+        """
         tag_name = self._get_entity_name(entity.name)
         found_rows = self._find_object("TAGS", tag_name)
         if len(found_rows) > 0:
@@ -341,12 +390,76 @@ class FeatureStore:
 
         return self.get_entity(entity.name)
 
+    def update_entity(self, name: str, *, desc: Optional[str] = None) -> Optional[Entity]:
+        """Update a registered entity with provided information.
+
+        Args:
+            name: Name of entity to update.
+            desc: Optional new description to apply. Default to None.
+
+        Raises:
+            SnowflakeMLException: Error happen when updating.
+
+        Returns:
+            A new entity with updated information or None if the entity doesn't exist.
+
+        Example::
+
+            >>> fs = FeatureStore(...)
+            <BLANKLINE>
+            >>> e = Entity(name='foo', join_keys=['COL_1'], desc='old desc')
+            >>> fs.list_entities().show()
+            ------------------------------------------------
+            |"NAME"  |"JOIN_KEYS"  |"DESC"    |"OWNER"     |
+            ------------------------------------------------
+            |FOO     |["COL_1"]    |old desc  |REGTEST_RL  |
+            ------------------------------------------------
+            <BLANKLINE>
+            >>> fs.update_entity('foo', desc='NEW DESC')
+            >>> fs.list_entities().show()
+            ------------------------------------------------
+            |"NAME"  |"JOIN_KEYS"  |"DESC"    |"OWNER"     |
+            ------------------------------------------------
+            |FOO     |["COL_1"]    |NEW DESC  |REGTEST_RL  |
+            ------------------------------------------------
+
+        """
+        name = SqlIdentifier(name)
+        found_rows = (
+            self.list_entities().filter(F.col("NAME") == name.resolved()).collect(statement_params=self._telemetry_stmp)
+        )
+
+        if len(found_rows) == 0:
+            warnings.warn(
+                f"Entity {name} does not exist.",
+                stacklevel=2,
+                category=UserWarning,
+            )
+            return None
+
+        new_desc = desc if desc is not None else found_rows[0]["DESC"]
+
+        try:
+            full_name = f"{self._config.full_schema_path}.{self._get_entity_name(name)}"
+            self._session.sql(f"ALTER TAG {full_name} SET COMMENT = '{new_desc}'").collect(
+                statement_params=self._telemetry_stmp
+            )
+        except Exception as e:
+            raise snowml_exceptions.SnowflakeMLException(
+                error_code=error_codes.INTERNAL_SNOWPARK_ERROR,
+                original_exception=RuntimeError(f"Failed to update entity `{name}`: {e}."),
+            ) from e
+
+        logger.info(f"Successfully updated Entity {name}.")
+        return self.get_entity(name)
+
     # TODO: add support to update column desc once SNOW-894249 is fixed
     @dispatch_decorator()
     def register_feature_view(
         self,
         feature_view: FeatureView,
         version: str,
+        *,
         block: bool = True,
         overwrite: bool = False,
     ) -> FeatureView:
@@ -356,12 +469,6 @@ class FeatureStore:
         NOTE: Each new materialization will trigger a full FeatureView history refresh for the data included in the
               FeatureView.
 
-        Examples:
-            ...
-            draft_fv = FeatureView(name="my_fv", entities=[entities], feature_df)
-            registered_fv = fs.register_feature_view(feature_view=draft_fv, version="v1")
-            ...
-
         Args:
             feature_view: FeatureView instance to materialize.
             version: version of the registered FeatureView.
@@ -380,6 +487,35 @@ class FeatureStore:
             SnowflakeMLException: [ValueError] Warehouse or default warehouse is not specified.
             SnowflakeMLException: [RuntimeError] Failed to create dynamic table, task, or view.
             SnowflakeMLException: [RuntimeError] Failed to find resources.
+
+        Example::
+
+            >>> fs = FeatureStore(...)
+            >>> # draft_fv is a local object that hasn't materiaized to Snowflake backend yet.
+            >>> feature_df = session.sql("select f_1, f_2 from source_table")
+            >>> draft_fv = FeatureView("my_fv", [entities], feature_df)
+            >>> print(draft_fv.status)
+            FeatureViewStatus.DRAFT
+            <BLANKLINE>
+            >>> fs.list_feature_views().select("NAME", "VERSION", "SCHEDULING_STATE").show()
+            -------------------------------------------
+            |"NAME"  |"VERSION"  |"SCHEDULING_STATE"  |
+            -------------------------------------------
+            |        |           |                    |
+            -------------------------------------------
+            <BLANKLINE>
+            >>> # registered_fv is a local object that maps to a Snowflake backend object.
+            >>> registered_fv = fs.register_feature_view(draft_fv, "v1")
+            >>> print(registered_fv.status)
+            FeatureViewStatus.ACTIVE
+            <BLANKLINE>
+            >>> fs.list_feature_views().select("NAME", "VERSION", "SCHEDULING_STATE").show()
+            -------------------------------------------
+            |"NAME"  |"VERSION"  |"SCHEDULING_STATE"  |
+            -------------------------------------------
+            |MY_FV   |v1         |ACTIVE              |
+            -------------------------------------------
+
         """
         version = FeatureViewVersion(version)
 
@@ -444,7 +580,7 @@ class FeatureStore:
                 column_descs,
                 tagging_clause_str,
                 schedule_task,
-                self._default_warehouse,
+                feature_view.warehouse if feature_view.warehouse is not None else self._default_warehouse,
                 block,
                 overwrite,
             )
@@ -473,6 +609,7 @@ class FeatureStore:
         self,
         name: str,
         version: str,
+        *,
         refresh_freq: Optional[str] = None,
         warehouse: Optional[str] = None,
         desc: Optional[str] = None,
@@ -492,27 +629,33 @@ class FeatureStore:
 
         Example::
 
-            >>> fs = FeatureStore(
-            ...     ...,
-            ...     default_warehouse='ORIGINAL_WH',
-            ... )
+            >>> fs = FeatureStore(...)
             >>> fv = FeatureView(
             ...     name='foo',
             ...     entities=[e1, e2],
             ...     feature_df=session.sql('...'),
-            ...     timestamp_col='timestamp',
-            ...     refresh_freq='1d',
-            ...     desc='this is old description'
+            ...     desc='this is old description',
             ... )
             >>> fv = fs.register_feature_view(feature_view=fv, version='v1')
+            >>> fs.list_feature_views().select("name", "version", "desc").show()
+            ------------------------------------------------
+            |"NAME"  |"VERSION"  |"DESC"                   |
+            ------------------------------------------------
+            |FOO     |v1         |this is old description  |
+            ------------------------------------------------
+            <BLANKLINE>
             >>> # update_feature_view will apply new arguments to the registered feature view.
             >>> new_fv = fs.update_feature_view(
             ...     name='foo',
             ...     version='v1',
-            ...     refresh_freq='2d',
-            ...     warehouse='MY_NEW_WH',
             ...     desc='that is new descption',
             ... )
+            >>> fs.list_feature_views().select("name", "version", "desc").show()
+            ------------------------------------------------
+            |"NAME"  |"VERSION"  |"DESC"                   |
+            ------------------------------------------------
+            |FOO     |v1         |THAT IS NEW DESCRIPTION  |
+            ------------------------------------------------
 
         Raises:
             SnowflakeMLException: [RuntimeError] If FeatureView is not managed and refresh_freq is defined.
@@ -555,20 +698,56 @@ class FeatureStore:
             ) from e
         return self.get_feature_view(name=name, version=version)
 
-    @dispatch_decorator()
+    @overload
+    def read_feature_view(self, feature_view: str, version: str) -> DataFrame:
+        ...
+
+    @overload
     def read_feature_view(self, feature_view: FeatureView) -> DataFrame:
+        ...
+
+    @dispatch_decorator()  # type: ignore[misc]
+    def read_feature_view(self, feature_view: Union[FeatureView, str], version: Optional[str] = None) -> DataFrame:
         """
-        Read FeatureView data.
+        Read values from a FeatureView.
 
         Args:
-            feature_view: FeatureView to retrieve data from.
+            feature_view: A FeatureView object to read from, or the name of feature view.
+                If name is provided then version also must be provided.
+            version: Optional version of feature view. Must set when argument feature_view is a str.
 
         Returns:
             Snowpark DataFrame(lazy mode) containing the FeatureView data.
 
         Raises:
+            SnowflakeMLException: [ValueError] version argument is missing when argument feature_view is a str.
             SnowflakeMLException: [ValueError] FeatureView is not registered.
+
+        Example::
+
+            >>> fs = FeatureStore(...)
+            >>> # Read from feature view name and version.
+            >>> fs.read_feature_view('foo', 'v1').show()
+            ------------------------------------------
+            |"NAME"  |"ID"  |"TITLE"  |"AGE"  |"TS"  |
+            ------------------------------------------
+            |jonh    |1     |boss     |20     |100   |
+            |porter  |2     |manager  |30     |200   |
+            ------------------------------------------
+            <BLANKLINE>
+            >>> # Read from feature view object.
+            >>> fv = fs.get_feature_view('foo', 'v1')
+            >>> fs.read_feature_view(fv).show()
+            ------------------------------------------
+            |"NAME"  |"ID"  |"TITLE"  |"AGE"  |"TS"  |
+            ------------------------------------------
+            |jonh    |1     |boss     |20     |100   |
+            |porter  |2     |manager  |30     |200   |
+            ------------------------------------------
+
         """
+        feature_view = self._validate_feature_view_name_and_version_input(feature_view, version)
+
         if feature_view.status == FeatureViewStatus.DRAFT or feature_view.version is None:
             raise snowml_exceptions.SnowflakeMLException(
                 error_code=error_codes.NOT_FOUND,
@@ -580,6 +759,7 @@ class FeatureStore:
     @dispatch_decorator()
     def list_feature_views(
         self,
+        *,
         entity_name: Optional[str] = None,
         feature_view_name: Optional[str] = None,
     ) -> DataFrame:
@@ -594,6 +774,24 @@ class FeatureStore:
 
         Returns:
             FeatureViews information as a Snowpark DataFrame.
+
+        Example::
+
+            >>> fs = FeatureStore(...)
+            >>> draft_fv = FeatureView(
+            ...     name='foo',
+            ...     entities=[e1, e2],
+            ...     feature_df=session.sql('...'),
+            ...     desc='this is description',
+            ... )
+            >>> fs.register_feature_view(feature_view=draft_fv, version='v1')
+            >>> fs.list_feature_views().select("name", "version", "desc").show()
+            --------------------------------------------
+            |"NAME"  |"VERSION"  |"DESC"               |
+            --------------------------------------------
+            |FOO     |v1         |this is description  |
+            --------------------------------------------
+
         """
         if feature_view_name is not None:
             feature_view_name = SqlIdentifier(feature_view_name)
@@ -622,6 +820,28 @@ class FeatureStore:
         Raises:
             SnowflakeMLException: [ValueError] FeatureView with name and version is not found,
                 or incurred exception when reconstructing the FeatureView object.
+
+        Example::
+
+            >>> fs = FeatureStore(...)
+            >>> # draft_fv is a local object that hasn't materiaized to Snowflake backend yet.
+            >>> draft_fv = FeatureView(
+            ...     name='foo',
+            ...     entities=[e1],
+            ...     feature_df=session.sql('...'),
+            ...     desc='this is description',
+            ... )
+            >>> fs.register_feature_view(feature_view=draft_fv, version='v1')
+            <BLANKLINE>
+            >>> # fv is a local object that maps to a Snowflake backend object.
+            >>> fv = fs.get_feature_view('foo', 'v1')
+            >>> print(f"name: {fv.name}")
+            >>> print(f"version:{fv.version}")
+            >>> print(f"desc:{fv.desc}")
+            name: FOO
+            version:v1
+            desc:this is description
+
         """
         name = SqlIdentifier(name)
         version = FeatureViewVersion(version)
@@ -634,27 +854,53 @@ class FeatureStore:
                 original_exception=ValueError(f"Failed to find FeatureView {name}/{version}: {results}"),
             )
 
-        return self._compose_feature_view(results[0][0], results[0][1], self.list_entities().collect())
+        return self._compose_feature_view(
+            results[0][0], results[0][1], self.list_entities().collect(statement_params=self._telemetry_stmp)
+        )
 
-    @dispatch_decorator()
+    @overload
     def refresh_feature_view(self, feature_view: FeatureView) -> None:
+        ...
+
+    @overload
+    def refresh_feature_view(self, feature_view: str, version: str) -> None:
+        ...
+
+    @dispatch_decorator()  # type: ignore[misc]
+    def refresh_feature_view(self, feature_view: Union[FeatureView, str], version: Optional[str] = None) -> None:
         """Manually refresh a feature view.
 
         Args:
-            feature_view: A registered feature view.
+            feature_view: A registered feature view object, or the name of feature view.
+            version: Optional version of feature view. Must set when argument feature_view is a str.
 
         Example::
 
-        >>> fs = FeatureStore(...)
-        >>> fv = fs.get_feature_view(name='MY_FV', version='v1')
-        >>> fs.refresh_feature_view(fv)
-        >>> fs.get_refresh_history(fv).show()
-        ---------------------------------------------------------------------------------------------------------------
-        |"NAME"    |"STATE"    |"REFRESH_START_TIME"             |"REFRESH_END_TIME"               |"REFRESH_ACTION"  |
-        ---------------------------------------------------------------------------------------------------------------
-        |MY_FV$v1  |SUCCEEDED  |2024-07-02 13:45:01.11300-07:00  |2024-07-02 13:45:01.82700-07:00  |INCREMENTAL       |
-        ---------------------------------------------------------------------------------------------------------------
+            >>> fs = FeatureStore(...)
+            >>> fv = fs.get_feature_view(name='MY_FV', version='v1')
+            <BLANKLINE>
+            >>> # refresh with name and version
+            >>> fs.refresh_feature_view('MY_FV', 'v1')
+            >>> fs.get_refresh_history('MY_FV', 'v1').show()
+            -----------------------------------------------------------------------------------------------------
+            |"NAME"    |"STATE"    |"REFRESH_START_TIME"        |"REFRESH_END_TIME"          |"REFRESH_ACTION"  |
+            -----------------------------------------------------------------------------------------------------
+            |MY_FV$v1  |SUCCEEDED  |2024-07-10 14:53:58.504000  |2024-07-10 14:53:59.088000  |INCREMENTAL       |
+            -----------------------------------------------------------------------------------------------------
+            <BLANKLINE>
+            >>> # refresh with feature view object
+            >>> fs.refresh_feature_view(fv)
+            >>> fs.get_refresh_history(fv).show()
+            -----------------------------------------------------------------------------------------------------
+            |"NAME"    |"STATE"    |"REFRESH_START_TIME"        |"REFRESH_END_TIME"          |"REFRESH_ACTION"  |
+            -----------------------------------------------------------------------------------------------------
+            |MY_FV$v1  |SUCCEEDED  |2024-07-10 14:54:06.680000  |2024-07-10 14:54:07.226000  |INCREMENTAL       |
+            |MY_FV$v1  |SUCCEEDED  |2024-07-10 14:53:58.504000  |2024-07-10 14:53:59.088000  |INCREMENTAL       |
+            -----------------------------------------------------------------------------------------------------
+
         """
+        feature_view = self._validate_feature_view_name_and_version_input(feature_view, version)
+
         if feature_view.status == FeatureViewStatus.STATIC:
             warnings.warn(
                 "Static feature view can't be refreshed. You must set refresh_freq when register_feature_view().",
@@ -664,11 +910,24 @@ class FeatureStore:
             return
         self._update_feature_view_status(feature_view, "REFRESH")
 
-    def get_refresh_history(self, feature_view: FeatureView, verbose: bool = False) -> DataFrame:
+    @overload
+    def get_refresh_history(
+        self, feature_view: FeatureView, version: Optional[str] = None, *, verbose: bool = False
+    ) -> DataFrame:
+        ...
+
+    @overload
+    def get_refresh_history(self, feature_view: str, version: str, *, verbose: bool = False) -> DataFrame:
+        ...
+
+    def get_refresh_history(
+        self, feature_view: Union[FeatureView, str], version: Optional[str] = None, *, verbose: bool = False
+    ) -> DataFrame:
         """Get refresh hisotry statistics about a feature view.
 
         Args:
-            feature_view: A registered feature view.
+            feature_view: A registered feature view object, or the name of feature view.
+            version: Optional version of feature view. Must set when argument feature_view is a str.
             verbose: Return more detailed history when set true.
 
         Returns:
@@ -676,16 +935,30 @@ class FeatureStore:
 
         Example::
 
-        >>> fs = FeatureStore(...)
-        >>> fv = fs.get_feature_view(name='MY_FV', version='v1')
-        >>> fs.refresh_feature_view(fv)
-        >>> fs.get_refresh_history(fv).show()
-        ---------------------------------------------------------------------------------------------------------------
-        |"NAME"    |"STATE"    |"REFRESH_START_TIME"             |"REFRESH_END_TIME"               |"REFRESH_ACTION"  |
-        ---------------------------------------------------------------------------------------------------------------
-        |MY_FV$v1  |SUCCEEDED  |2024-07-02 13:45:01.11300-07:00  |2024-07-02 13:45:01.82700-07:00  |INCREMENTAL       |
-        ---------------------------------------------------------------------------------------------------------------
+            >>> fs = FeatureStore(...)
+            >>> fv = fs.get_feature_view(name='MY_FV', version='v1')
+            >>> # refresh with name and version
+            >>> fs.refresh_feature_view('MY_FV', 'v1')
+            >>> fs.get_refresh_history('MY_FV', 'v1').show()
+            -----------------------------------------------------------------------------------------------------
+            |"NAME"    |"STATE"    |"REFRESH_START_TIME"        |"REFRESH_END_TIME"          |"REFRESH_ACTION"  |
+            -----------------------------------------------------------------------------------------------------
+            |MY_FV$v1  |SUCCEEDED  |2024-07-10 14:53:58.504000  |2024-07-10 14:53:59.088000  |INCREMENTAL       |
+            -----------------------------------------------------------------------------------------------------
+            <BLANKLINE>
+            >>> # refresh with feature view object
+            >>> fs.refresh_feature_view(fv)
+            >>> fs.get_refresh_history(fv).show()
+            -----------------------------------------------------------------------------------------------------
+            |"NAME"    |"STATE"    |"REFRESH_START_TIME"        |"REFRESH_END_TIME"          |"REFRESH_ACTION"  |
+            -----------------------------------------------------------------------------------------------------
+            |MY_FV$v1  |SUCCEEDED  |2024-07-10 14:54:06.680000  |2024-07-10 14:54:07.226000  |INCREMENTAL       |
+            |MY_FV$v1  |SUCCEEDED  |2024-07-10 14:53:58.504000  |2024-07-10 14:53:59.088000  |INCREMENTAL       |
+            -----------------------------------------------------------------------------------------------------
+
         """
+        feature_view = self._validate_feature_view_name_and_version_input(feature_view, version)
+
         if feature_view.status == FeatureViewStatus.STATIC:
             warnings.warn(
                 "Static feature view never refreshes.",
@@ -719,43 +992,151 @@ class FeatureStore:
             """
         )
 
-    @dispatch_decorator()
+    @overload
     def resume_feature_view(self, feature_view: FeatureView) -> FeatureView:
+        ...
+
+    @overload
+    def resume_feature_view(self, feature_view: str, version: str) -> FeatureView:
+        ...
+
+    @dispatch_decorator()  # type: ignore[misc]
+    def resume_feature_view(self, feature_view: Union[FeatureView, str], version: Optional[str] = None) -> FeatureView:
         """
         Resume a previously suspended FeatureView.
 
         Args:
-            feature_view: FeatureView to resume.
+            feature_view: FeatureView object or name to resume.
+            version: Optional version of feature view. Must set when argument feature_view is a str.
 
         Returns:
             A new feature view with updated status.
+
+        Example::
+
+            >>> fs = FeatureStore(...)
+            >>> # you must already have feature views registered
+            >>> fv = fs.get_feature_view(name='MY_FV', version='v1')
+            >>> fs.suspend_feature_view('MY_FV', 'v1')
+            >>> fs.list_feature_views().select("NAME", "VERSION", "SCHEDULING_STATE").show()
+            -------------------------------------------
+            |"NAME"  |"VERSION"  |"SCHEDULING_STATE"  |
+            -------------------------------------------
+            |MY_FV   |v1         |SUSPENDED           |
+            -------------------------------------------
+            <BLANKLINE>
+            >>> fs.resume_feature_view('MY_FV', 'v1')
+            >>> fs.list_feature_views().select("NAME", "VERSION", "SCHEDULING_STATE").show()
+            -------------------------------------------
+            |"NAME"  |"VERSION"  |"SCHEDULING_STATE"  |
+            -------------------------------------------
+            |MY_FV   |v1         |ACTIVE              |
+            -------------------------------------------
+
         """
+        feature_view = self._validate_feature_view_name_and_version_input(feature_view, version)
         return self._update_feature_view_status(feature_view, "RESUME")
 
-    @dispatch_decorator()
+    @overload
     def suspend_feature_view(self, feature_view: FeatureView) -> FeatureView:
+        ...
+
+    @overload
+    def suspend_feature_view(self, feature_view: str, version: str) -> FeatureView:
+        ...
+
+    @dispatch_decorator()  # type: ignore[misc]
+    def suspend_feature_view(self, feature_view: Union[FeatureView, str], version: Optional[str] = None) -> FeatureView:
         """
         Suspend an active FeatureView.
 
         Args:
-            feature_view: FeatureView to suspend.
+            feature_view: FeatureView object or name to suspend.
+            version: Optional version of feature view. Must set when argument feature_view is a str.
 
         Returns:
             A new feature view with updated status.
+
+        Example::
+
+            >>> fs = FeatureStore(...)
+            >>> # assume you already have feature views registered
+            >>> fv = fs.get_feature_view(name='MY_FV', version='v1')
+            >>> fs.suspend_feature_view('MY_FV', 'v1')
+            >>> fs.list_feature_views().select("NAME", "VERSION", "SCHEDULING_STATE").show()
+            -------------------------------------------
+            |"NAME"  |"VERSION"  |"SCHEDULING_STATE"  |
+            -------------------------------------------
+            |MY_FV   |v1         |SUSPENDED           |
+            -------------------------------------------
+            <BLANKLINE>
+            >>> fs.resume_feature_view('MY_FV', 'v1')
+            >>> fs.list_feature_views().select("NAME", "VERSION", "SCHEDULING_STATE").show()
+            -------------------------------------------
+            |"NAME"  |"VERSION"  |"SCHEDULING_STATE"  |
+            -------------------------------------------
+            |MY_FV   |v1         |ACTIVE              |
+            -------------------------------------------
+
         """
+        feature_view = self._validate_feature_view_name_and_version_input(feature_view, version)
         return self._update_feature_view_status(feature_view, "SUSPEND")
 
-    @dispatch_decorator()
+    @overload
     def delete_feature_view(self, feature_view: FeatureView) -> None:
+        ...
+
+    @overload
+    def delete_feature_view(self, feature_view: str, version: str) -> None:
+        ...
+
+    @dispatch_decorator()  # type: ignore[misc]
+    def delete_feature_view(self, feature_view: Union[FeatureView, str], version: Optional[str] = None) -> None:
         """
         Delete a FeatureView.
 
         Args:
-            feature_view: FeatureView to delete.
+            feature_view: FeatureView object or name to delete.
+            version: Optional version of feature view. Must set when argument feature_view is a str.
 
         Raises:
             SnowflakeMLException: [ValueError] FeatureView is not registered.
+
+        Example::
+
+            >>> fs = FeatureStore(...)
+            >>> fv = FeatureView('FV0', ...)
+            >>> fv1 = fs.register_feature_view(fv, 'FIRST')
+            >>> fv2 = fs.register_feature_view(fv, 'SECOND')
+            >>> fs.list_feature_views().select('NAME', 'VERSION').show()
+            ----------------------
+            |"NAME"  |"VERSION"  |
+            ----------------------
+            |FV0     |SECOND     |
+            |FV0     |FIRST      |
+            ----------------------
+            <BLANKLINE>
+            >>> # delete with name and version
+            >>> fs.delete_feature_view('FV0', 'FIRST')
+            >>> fs.list_feature_views().select('NAME', 'VERSION').show()
+            ----------------------
+            |"NAME"  |"VERSION"  |
+            ----------------------
+            |FV0     |SECOND     |
+            ----------------------
+            <BLANKLINE>
+            >>> # delete with feature view object
+            >>> fs.delete_feature_view(fv2)
+            >>> fs.list_feature_views().select('NAME', 'VERSION').show()
+            ----------------------
+            |"NAME"  |"VERSION"  |
+            ----------------------
+            |        |           |
+            ----------------------
+
         """
+        feature_view = self._validate_feature_view_name_and_version_input(feature_view, version)
+
         # TODO: we should leverage lineage graph to check downstream deps, and block the deletion
         # if there're other FVs depending on this
         if feature_view.status == FeatureViewStatus.DRAFT or feature_view.version is None:
@@ -787,6 +1168,19 @@ class FeatureStore:
 
         Returns:
             Snowpark DataFrame containing the results.
+
+        Example::
+
+            >>> fs = FeatureStore(...)
+            >>> e_1 = Entity("my_entity", ['col_1'], desc='My first entity.')
+            >>> fs.register_entity(e_1)
+            >>> fs.list_entities().show()
+            -----------------------------------------------------------
+            |"NAME"     |"JOIN_KEYS"  |"DESC"            |"OWNER"     |
+            -----------------------------------------------------------
+            |MY_ENTITY  |["COL_1"]    |My first entity.  |REGTEST_RL  |
+            -----------------------------------------------------------
+
         """
         prefix_len = len(_ENTITY_TAG_PREFIX) + 1
         return cast(
@@ -816,10 +1210,27 @@ class FeatureStore:
             SnowflakeMLException: [ValueError] Entity is not found.
             SnowflakeMLException: [RuntimeError] Failed to retrieve tag reference information.
             SnowflakeMLException: [RuntimeError] Failed to find resources.
+
+        Example::
+
+            >>> fs = FeatureStore(...)
+            >>> # e_1 is a local object that hasn't registered to Snowflake backend yet.
+            >>> e_1 = Entity("my_entity", ['col_1'], desc='My first entity.')
+            >>> fs.register_entity(e_1)
+            <BLANKLINE>
+            >>> # e_2 is a local object that points a backend object in Snowflake.
+            >>> e_2 = fs.get_entity("my_entity")
+            >>> print(e_2)
+            Entity(name=MY_ENTITY, join_keys=['COL_1'], owner=REGTEST_RL, desc=My first entity.)
+
         """
         name = SqlIdentifier(name)
         try:
-            result = self.list_entities().filter(F.col("NAME") == name.resolved()).collect()
+            result = (
+                self.list_entities()
+                .filter(F.col("NAME") == name.resolved())
+                .collect(statement_params=self._telemetry_stmp)
+            )
         except Exception as e:
             raise snowml_exceptions.SnowflakeMLException(
                 error_code=error_codes.INTERNAL_SNOWPARK_ERROR,
@@ -846,12 +1257,33 @@ class FeatureStore:
         Delete a previously registered Entity.
 
         Args:
-            name: Entity name.
+            name: Name of entity to be deleted.
 
         Raises:
             SnowflakeMLException: [ValueError] Entity with given name not exists.
             SnowflakeMLException: [RuntimeError] Failed to alter schema or drop tag.
             SnowflakeMLException: [RuntimeError] Failed to find resources.
+
+        Example::
+
+            >>> fs = FeatureStore(...)
+            >>> e_1 = Entity("my_entity", ['col_1'], desc='My first entity.')
+            >>> fs.register_entity(e_1)
+            >>> fs.list_entities().show()
+            -----------------------------------------------------------
+            |"NAME"     |"JOIN_KEYS"  |"DESC"            |"OWNER"     |
+            -----------------------------------------------------------
+            |MY_ENTITY  |["COL_1"]    |My first entity.  |REGTEST_RL  |
+            -----------------------------------------------------------
+            <BLANKLINE>
+            >>> fs.delete_entity("my_entity")
+            >>> fs.list_entities().show()
+            -------------------------------------------
+            |"NAME"  |"JOIN_KEYS"  |"DESC"  |"OWNER"  |
+            -------------------------------------------
+            |        |             |        |         |
+            -------------------------------------------
+
         """
         name = SqlIdentifier(name)
 
@@ -885,6 +1317,7 @@ class FeatureStore:
         self,
         spine_df: DataFrame,
         features: Union[List[Union[FeatureView, FeatureViewSlice]], List[str]],
+        *,
         spine_timestamp_col: Optional[str] = None,
         exclude_columns: Optional[List[str]] = None,
         include_feature_view_timestamp_col: bool = False,
@@ -907,6 +1340,23 @@ class FeatureStore:
 
         Raises:
             ValueError: if features is empty.
+
+        Example::
+
+            >>> fs = FeatureStore(...)
+            >>> # Assume you already have feature view registered.
+            >>> fv = fs.get_feature_view('my_fv', 'v1')
+            >>> # Spine dataframe has same join keys as the entity of fv.
+            >>> spine_df = session.create_dataframe(["1", "2"], schema=["id"])
+            >>> fs.retrieve_feature_values(spine_df, [fv]).show()
+            --------------------
+            |"END_STATION_ID"  |
+            --------------------
+            |505               |
+            |347               |
+            |466               |
+            --------------------
+
         """
         if spine_timestamp_col is not None:
             spine_timestamp_col = SqlIdentifier(spine_timestamp_col)
@@ -914,7 +1364,7 @@ class FeatureStore:
         if len(features) == 0:
             raise ValueError("features cannot be empty")
         if isinstance(features[0], str):
-            features = self._load_serialized_feature_objects(cast(List[str], features))
+            features = self._load_serialized_feature_views(cast(List[str], features))
 
         df, _ = self._join_features(
             spine_df,
@@ -933,6 +1383,7 @@ class FeatureStore:
         self,
         spine_df: DataFrame,
         features: List[Union[FeatureView, FeatureViewSlice]],
+        *,
         save_as: Optional[str] = None,
         spine_timestamp_col: Optional[str] = None,
         spine_label_cols: Optional[List[str]] = None,
@@ -966,8 +1417,10 @@ class FeatureStore:
         Example::
 
             >>> fs = FeatureStore(session, ...)
+            >>> # Assume you already have feature view registered.
             >>> fv = fs.get_feature_view("MY_FV", "1")
-            >>> spine_df = session.create_dataframe(["id_1", "id_2"], schema=["id"])
+            >>> # Spine dataframe has same join keys as the entity of fv.
+            >>> spine_df = session.create_dataframe(["1", "2"], schema=["id"])
             >>> training_set = fs.generate_training_set(
             ...     spine_df,
             ...     [fv],
@@ -975,6 +1428,7 @@ class FeatureStore:
             ... )
             >>> print(type(training_set))
             <class 'snowflake.snowpark.table.Table'>
+            <BLANKLINE>
             >>> print(training_set.queries)
             {'queries': ['SELECT  *  FROM (my_training_set)'], 'post_actions': []}
 
@@ -994,8 +1448,19 @@ class FeatureStore:
         if save_as is not None:
             try:
                 save_as = self._get_fully_qualified_name(save_as)
-                result_df.write.mode("errorifexists").save_as_table(save_as)
+                result_df.write.mode("errorifexists").save_as_table(save_as, statement_params=self._telemetry_stmp)
+
+                # Add tag
+                task_obj_info = _FeatureStoreObjInfo(_FeatureStoreObjTypes.TRAINING_DATA, snowml_version.VERSION)
+                self._session.sql(
+                    f"""
+                    ALTER TABLE {save_as}
+                    SET TAG {self._get_fully_qualified_name(_FEATURE_STORE_OBJECT_TAG)}='{task_obj_info.to_json()}'
+                    """
+                ).collect(statement_params=self._telemetry_stmp)
+
                 return self._session.table(save_as)
+
             except SnowparkSQLException as e:
                 if e.sql_error_code == sql_error_codes.OBJECT_ALREADY_EXISTS:
                     raise snowml_exceptions.SnowflakeMLException(
@@ -1014,6 +1479,7 @@ class FeatureStore:
         name: str,
         spine_df: DataFrame,
         features: List[Union[FeatureView, FeatureViewSlice]],
+        *,
         version: Optional[str] = None,
         spine_timestamp_col: Optional[str] = None,
         spine_label_cols: Optional[List[str]] = None,
@@ -1030,6 +1496,7 @@ class FeatureStore:
         name: str,
         spine_df: DataFrame,
         features: List[Union[FeatureView, FeatureViewSlice]],
+        *,
         output_type: Literal["table"],
         version: Optional[str] = None,
         spine_timestamp_col: Optional[str] = None,
@@ -1046,6 +1513,7 @@ class FeatureStore:
         name: str,
         spine_df: DataFrame,
         features: List[Union[FeatureView, FeatureViewSlice]],
+        *,
         version: Optional[str] = None,
         spine_timestamp_col: Optional[str] = None,
         spine_label_cols: Optional[List[str]] = None,
@@ -1082,6 +1550,33 @@ class FeatureStore:
             SnowflakeMLException: [ValueError] Invalid output_type specified.
             SnowflakeMLException: [RuntimeError] Dataset name/version already exists.
             SnowflakeMLException: [RuntimeError] Failed to find resources.
+
+        Example::
+
+            >>> fs = FeatureStore(session, ...)
+            >>> # Assume you already have feature view registered.
+            >>> fv = fs.get_feature_view("MY_FV", "1")
+            >>> # Spine dataframe has same join keys as the entity of fv.
+            >>> spine_df = session.create_dataframe(["1", "2"], schema=["id"])
+            >>> my_dataset = fs.generate_dataset(
+            ...     "my_dataset"
+            ...     spine_df,
+            ...     [fv],
+            ... )
+            >>> # Current timestamp will be used as default version name.
+            >>> # You can explicitly overwrite by setting a version.
+            >>> my_dataset.list_versions()
+            ['2024_07_12_11_26_22']
+            <BLANKLINE>
+            >>> my_dataset.read.to_snowpark_dataframe().show(n=3)
+            -------------------------------------------------------
+            |"QUALITY"  |"FIXED_ACIDITY"     |"VOLATILE_ACIDITY"  |
+            -------------------------------------------------------
+            |3          |11.600000381469727  |0.5799999833106995  |
+            |3          |8.300000190734863   |1.0199999809265137  |
+            |3          |7.400000095367432   |1.184999942779541   |
+            -------------------------------------------------------
+
         """
         if output_type not in {"table", "dataset"}:
             raise snowml_exceptions.SnowflakeMLException(
@@ -1095,7 +1590,7 @@ class FeatureStore:
 
         fs_meta = FeatureStoreMetadata(
             spine_query=spine_df.queries["queries"][-1],
-            serialized_feature_views=[fv.to_json() for fv in features],
+            compact_feature_views=[fv._get_compact_repr().to_json() for fv in features],
             spine_timestamp_col=spine_timestamp_col,
         )
 
@@ -1130,6 +1625,7 @@ class FeatureStore:
                         " to generate the data as a Snowflake Table."
                     ),
                 )
+            # TODO: Add feature store tag once Dataset (version) supports tags
             ds: dataset.Dataset = dataset.create_from_dataframe(
                 self._session,
                 name,
@@ -1166,17 +1662,50 @@ class FeatureStore:
 
         Raises:
             ValueError: if dataset object is not generated from feature store.
+
+        Example::
+
+            >>> fs = FeatureStore(session, ...)
+            >>> # Assume you already have feature view registered.
+            >>> fv = fs.get_feature_view("MY_FV", "1.0")
+            >>> # Spine dataframe has same join keys as the entity of fv.
+            >>> spine_df = session.create_dataframe(["1", "2"], schema=["id"])
+            >>> my_dataset = fs.generate_dataset(
+            ...     "my_dataset"
+            ...     spine_df,
+            ...     [fv],
+            ... )
+            >>> fvs = fs.load_feature_views_from_dataset(my_dataset)
+            >>> print(len(fvs))
+            1
+            <BLANKLINE>
+            >>> print(type(fvs[0]))
+            <class 'snowflake.ml.feature_store.feature_view.FeatureView'>
+            <BLANKLINE>
+            >>> print(fvs[0].name)
+            MY_FV
+            <BLANKLINE>
+            >>> print(fvs[0].version)
+            1.0
+
         """
         assert ds.selected_version is not None
         source_meta = ds.selected_version._get_metadata()
         if (
             source_meta is None
             or not isinstance(source_meta.properties, FeatureStoreMetadata)
-            or source_meta.properties.serialized_feature_views is None
+            or (
+                source_meta.properties.serialized_feature_views is None
+                and source_meta.properties.compact_feature_views is None
+            )
         ):
             raise ValueError(f"Dataset {ds} does not contain valid feature view information.")
 
-        return self._load_serialized_feature_objects(source_meta.properties.serialized_feature_views)
+        properties = source_meta.properties
+        if properties.serialized_feature_views:
+            return self._load_serialized_feature_views(properties.serialized_feature_views)
+        else:
+            return self._load_compact_feature_views(properties.compact_feature_views)  # type: ignore[arg-type]
 
     @dispatch_decorator()
     def _clear(self, dryrun: bool = True) -> None:
@@ -1197,17 +1726,17 @@ class FeatureStore:
 
         all_fvs_df = self.list_feature_views()
         all_entities_df = self.list_entities()
-        all_fvs_rows = all_fvs_df.collect()
-        all_entities_rows = all_entities_df.collect()
+        all_fvs_rows = all_fvs_df.collect(statement_params=self._telemetry_stmp)
+        all_entities_rows = all_entities_df.collect(statement_params=self._telemetry_stmp)
 
         if dryrun:
             logger.info(
                 "Following feature views and entities will be deleted."
-                + " Set 'dryrun=False' to perform the actual deletion."
+                + " Set 'dryrun=False' to perform the actual deletion.",
             )
             logger.info(f"Total {len(all_fvs_rows)} Feature views to be deleted:")
             all_fvs_df.show(n=len(all_fvs_rows))
-            logger.info(f"\nTotal {len(all_entities_rows)} entities to be deleted:")
+            logger.info(f"\nTotal {len(all_entities_rows)} Entities to be deleted:")
             all_entities_df.show(n=len(all_entities_rows))
             return
 
@@ -1265,6 +1794,7 @@ class FeatureStore:
                     {tagging_clause}
                 )
                 WAREHOUSE = {warehouse}
+                REFRESH_MODE = {feature_view.refresh_mode}
                 AS {feature_view.query}
             """
             self._session.sql(query).collect(block=block, statement_params=self._telemetry_stmp)
@@ -1482,7 +2012,7 @@ class FeatureStore:
                 MATCH_CONDITION ( spine.ts >= feature.ts )
                 ON spine.id = feature.id;
             """
-            ).collect()
+            ).collect(statement_params=self._telemetry_stmp)
         except SnowparkSQLException:
             return False
         return result is not None and len(result) == 1
@@ -1686,6 +2216,7 @@ class FeatureStore:
         values.append(row["target_lag"] if "target_lag" in row else None)
         values.append(row["refresh_mode"] if "refresh_mode" in row else None)
         values.append(row["scheduling_state"] if "scheduling_state" in row else None)
+        values.append(row["warehouse"] if "warehouse" in row else None)
         output_values.append(values)
 
     def _lookup_feature_view_metadata(self, row: Row, fv_name: str) -> Tuple[_FeatureViewMetadata, str]:
@@ -1862,11 +2393,11 @@ class FeatureStore:
                 result.append(row)
         return result
 
-    def _load_serialized_feature_objects(
-        self, serialized_feature_objs: List[str]
+    def _load_serialized_feature_views(
+        self, serialized_feature_views: List[str]
     ) -> List[Union[FeatureView, FeatureViewSlice]]:
         results: List[Union[FeatureView, FeatureViewSlice]] = []
-        for obj in serialized_feature_objs:
+        for obj in serialized_feature_views:
             try:
                 obj_type = json.loads(obj)[_FEATURE_OBJ_TYPE]
             except Exception as e:
@@ -1880,6 +2411,14 @@ class FeatureStore:
                 raise ValueError(f"Unsupported feature object type: {obj_type}")
         return results
 
+    def _load_compact_feature_views(
+        self, compact_feature_views: List[str]
+    ) -> List[Union[FeatureView, FeatureViewSlice]]:
+        results: List[Union[FeatureView, FeatureViewSlice]] = []
+        for obj in compact_feature_views:
+            results.append(FeatureView._load_from_compact_repr(self._session, obj))
+        return results
+
     def _exclude_columns(self, df: DataFrame, exclude_columns: List[str]) -> DataFrame:
         exclude_columns = to_sql_identifiers(exclude_columns)  # type: ignore[assignment]
         df_cols = to_sql_identifiers(df.columns)
@@ -1895,12 +2434,12 @@ class FeatureStore:
 
     def _is_dataset_enabled(self) -> bool:
         try:
-            self._session.sql(f"SHOW DATASETS IN SCHEMA {self._config.full_schema_path}").collect()
+            self._session.sql(f"SHOW DATASETS IN SCHEMA {self._config.full_schema_path}").collect(
+                statement_params=self._telemetry_stmp
+            )
             return True
-        except SnowparkSQLException as e:
-            if "'DATASETS' does not exist" in e.message:
-                return False
-            raise
+        except SnowparkSQLException:
+            return False
 
     def _check_feature_store_object_versions(self) -> None:
         versions = self._collapse_object_versions()
@@ -1942,6 +2481,7 @@ class FeatureStore:
             SnowflakeMLException: [RuntimeError] Failed to lookup tags.
 
         Example::
+
             self._lookup_tags("TABLE", "MY_FV", [lambda d: d["tagName"] == "TARGET_TAG_NAME"])
 
         """
@@ -1979,6 +2519,7 @@ class FeatureStore:
             SnowflakeMLException: [RuntimeError] Failed to lookup tagged objects.
 
         Example::
+
             self._lookup_tagged_objects("TARGET_TAG_NAME", [lambda d: d["entityName"] == "MY_FV"])
 
         """
@@ -2024,3 +2565,23 @@ class FeatureStore:
                 ),
             )
         return sorted_versions
+
+    def _validate_feature_view_name_and_version_input(
+        self, feature_view: Union[FeatureView, str], version: Optional[str] = None
+    ) -> FeatureView:
+        if isinstance(feature_view, str):
+            if version is None:
+                raise snowml_exceptions.SnowflakeMLException(
+                    error_code=error_codes.INVALID_ARGUMENT,
+                    original_exception=ValueError("Version must be provided when argument feature_view is a str."),
+                )
+            feature_view = self.get_feature_view(feature_view, version)
+        elif not isinstance(feature_view, FeatureView):
+            raise snowml_exceptions.SnowflakeMLException(
+                error_code=error_codes.INVALID_ARGUMENT,
+                original_exception=ValueError(
+                    "Invalid type of argument feature_view. It must be either str or FeatureView type."
+                ),
+            )
+
+        return feature_view