documentation: update doc strings for feature_store (aws#500) (aws#506)

Author: icywang86rui

src/sagemaker/feature_store/feature_definition.py

@@ -10,7 +10,14 @@
 # distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
 # ANY KIND, either express or implied. See the License for the specific
 # language governing permissions and limitations under the License.
-"""The Feature Definitions for FeatureStore."""
+"""The Feature Definitions for FeatureStore.
+
+A feature is a measurable property or characteristic that encapsulates an observed phenomenon.
+In the Amazon SageMaker Feature Store API, a feature is an attribute of a record.
+You can define a name and type for every feature stored in Feature Store. Name uniquely
+identifies a feature within a feature group. Type identifies
+the datatype for the values of the Feature.
+"""
 from __future__ import absolute_import
 
 from enum import Enum
@@ -22,7 +29,10 @@
 
 
 class FeatureTypeEnum(Enum):
-    """Enum of feature types."""
+    """Enum of feature types.
+
+    The data type of a feature can be Fractional, Integral or String.
+    """
 
     FRACTIONAL = "Fractional"
     INTEGRAL = "Integral"
@@ -33,6 +43,8 @@ class FeatureTypeEnum(Enum):
 class FeatureDefinition(Config):
     """Feature definition.
 
+    This instantiates a Feature Definition object where FeatureDefinition is a subclass of Config.
+
     Attributes:
         feature_name (str): The name of the feature
         feature_type (FeatureTypeEnum): The type of the feature
@@ -42,7 +54,7 @@ class FeatureDefinition(Config):
     feature_type: FeatureTypeEnum = attr.ib()
 
     def to_dict(self) -> Dict[str, Any]:
-        """Constructs a dictionary based on the attributes"""
+        """Construct a dictionary based on each attribute."""
         return Config.construct_dict(
             FeatureName=self.feature_name, FeatureType=self.feature_type.value
         )
@@ -51,13 +63,16 @@ def to_dict(self) -> Dict[str, Any]:
 class FractionalFeatureDefinition(FeatureDefinition):
     """Fractional feature definition.
 
+    This class instantiates a FractionalFeatureDefinition object, a subclass of FeatureDefinition
+    where the data type of the feature being defined is a Fractional.
+
     Attributes:
         feature_name (str): The name of the feature
         feature_type (FeatureTypeEnum): A `FeatureTypeEnum.FRACTIONAL` type
     """
 
     def __init__(self, feature_name: str):
-        """Constructs an instance of FractionalFeatureDefinition.
+        """Construct an instance of FractionalFeatureDefinition.
 
         Args:
             feature_name (str): the name of the feature.
@@ -68,13 +83,16 @@ def __init__(self, feature_name: str):
 class IntegralFeatureDefinition(FeatureDefinition):
     """Fractional feature definition.
 
+    This class instantiates a IntegralFeatureDefinition object, a subclass of FeatureDefinition
+    where the data type of the feature being defined is a Integral.
+
     Attributes:
         feature_name (str): the name of the feature.
         feature_type (FeatureTypeEnum): a `FeatureTypeEnum.INTEGRAL` type.
     """
 
     def __init__(self, feature_name: str):
-        """Constructs an instance of IntegralFeatureDefinition.
+        """Construct an instance of IntegralFeatureDefinition.
 
         Args:
             feature_name (str): the name of the feature.
@@ -85,13 +103,16 @@ def __init__(self, feature_name: str):
 class StringFeatureDefinition(FeatureDefinition):
     """Fractional feature definition.
 
+    This class instantiates a StringFeatureDefinition object, a subclass of FeatureDefinition
+    where the data type of the feature being defined is a String.
+
     Attributes:
         feature_name (str): the name of the feature.
         feature_type (FeatureTypeEnum): a `FeatureTypeEnum.STRING` type.
     """
 
     def __init__(self, feature_name: str):
-        """Constructs an instance of StringFeatureDefinition.
+        """Construct an instance of StringFeatureDefinition.
 
         Args:
             feature_name (str): the name of the feature.

src/sagemaker/feature_store/feature_group.py

@@ -10,7 +10,15 @@
 # distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
 # ANY KIND, either express or implied. See the License for the specific
 # language governing permissions and limitations under the License.
-"""The FeatureGroup entity for FeatureStore."""
+"""The FeatureGroup entity for FeatureStore.
+
+A feature group is a logical grouping of features, defined in the Feature Store,
+to describe records. A feature group definition is composed of a list of feature definitions,
+a record identifier name, and configurations for its online and offline store.
+Create feature group, describe feature group, update feature groups, delete feature group and
+list feature groups APIs can be used to manage feature groups.
+"""
+
 from __future__ import absolute_import
 
 import logging
@@ -45,7 +53,10 @@
 
 @attr.s
 class AthenaQuery:
-    """Class to manager querying of feature store data with AWS Athena
+    """Class to manage querying of feature store data with AWS Athena.
+
+    This class instantiates a AthenaQuery object that is used to retrieve data from feature store
+    via standard SQL queries.
 
     Attributes:
         catalog (str): name of the data catalog.
@@ -63,12 +74,15 @@ class AthenaQuery:
     _result_file_prefix: str = attr.ib(init=False, default=None)
 
     def run(self, query_string: str, output_location: str, kms_key: str = None) -> str:
-        """Run athena query with the given query_string
+        """Execute a SQL query given a query string, output location and kms key.
+
+        This method executes the SQL query using Athena and outputs the results to output_location
+        and returns the execution id of the query.
 
         Args:
             query_string: SQL query string.
-            output_location: s3 uri of the query result.
-            kms_key: KMS key id, if set will be used to encrypt the query result file.
+            output_location: S3 URI of the query result.
+            kms_key: KMS key id. If set, will be used to encrypt the query result file.
 
         Returns:
             Execution id of the query.
@@ -103,7 +117,7 @@ def get_query_execution(self) -> Dict[str, Any]:
         )
 
     def as_dataframe(self) -> DataFrame:
-        """Download the result of the current query and load it into a DataFrame
+        """Download the result of the current query and load it into a DataFrame.
 
         Returns:
             A pandas DataFrame contains the query result.
@@ -132,10 +146,12 @@ def as_dataframe(self) -> DataFrame:
 class IngestionManagerPandas:
     """Class to manage the multi-threaded data ingestion process.
 
+    This class will manage the data ingestion process which is multi-threaded.
+
     Attributes:
         feature_group_name (str): name of the Feature Group.
         sagemaker_session (Session): instance of the Session class to perform boto calls.
-        data_frame (DataFrame): pandas data_frame to be ingested to the given feature group.
+        data_frame (DataFrame): pandas DataFrame to be ingested to the given feature group.
         max_works (int): number of threads to create.
     """
 
@@ -201,9 +217,8 @@ def run(self, wait=True, timeout=None):
         Args:
             wait (bool): whether to wait for the ingestion to finish or not.
             timeout (Union[int, float]): ``concurrent.futures.TimeoutError`` will be raised
-                if timeout is reached.
+            if timeout is reached.
         """
-
         executor = ThreadPoolExecutor(max_workers=self.max_workers)
         batch_size = math.ceil(self.data_frame.shape[0] / self.max_workers)
 
@@ -230,7 +245,10 @@ def run(self, wait=True, timeout=None):
 
 @attr.s
 class FeatureGroup:
-    """FeatureGroup for FeatureStore
+    """FeatureGroup definition.
+
+    This class instantiates a FeatureGroup object that comprises of a name for the FeatureGroup,
+    session instance, and a list of feature definition objects i.e., FeatureDefinition.
 
     Attributes:
         name (str): name of the FeatureGroup instance.
@@ -282,7 +300,7 @@ def create(
         description: str = None,
         tags: List[Dict[str, str]] = None,
     ) -> Dict[str, Any]:
-        """Creates a SageMaker FeatureStore FeatureGroup
+        """Create a SageMaker FeatureStore FeatureGroup.
 
         Args:
             s3_uri (str): S3 URI of the offline store.
@@ -300,7 +318,6 @@ def create(
         Returns:
             Response dict from service.
         """
-
         create_feature_store_args = dict(
             feature_group_name=self.name,
             record_identifier_name=record_identifier_name,
@@ -336,7 +353,7 @@ def create(
         return self.sagemaker_session.create_feature_group(**create_feature_store_args)
 
     def delete(self):
-        """Deletes a FeatureGroup"""
+        """Delete a FeatureGroup."""
         self.sagemaker_session.delete_feature_group(feature_group_name=self.name)
 
     def describe(self, next_token: str = None) -> Dict[str, Any]:
@@ -354,7 +371,7 @@ def load_feature_definitions(
         self,
         data_frame: DataFrame,
     ) -> Sequence[FeatureDefinition]:
-        """Loads feature definitions from a Pandas DataFrame
+        """Load feature definitions from a Pandas DataFrame.
 
         Column name is used as feature name. Feature type is inferred from the dtype
         of the column. Dtype int_, int8, int16, int32, int64, uint8, uint16, uint32
@@ -389,7 +406,7 @@ def load_feature_definitions(
         return self.feature_definitions
 
     def put_record(self, record: Sequence[FeatureValue]):
-        """Puts a single record in the FeatureGroup
+        """Put a single record in the FeatureGroup.
 
         Args:
             record (Sequence[FeatureValue]): a list contains feature values.
@@ -430,7 +447,7 @@ def ingest(
         return manager
 
     def athena_query(self) -> AthenaQuery:
-        """Creates an AthenaQuery instance
+        """Create an AthenaQuery instance.
 
         Returns:
             An instance of AthenaQuery initialized with data catalog configurations.
@@ -449,10 +466,11 @@ def athena_query(self) -> AthenaQuery:
         raise RuntimeError("No metastore is configured with this feature group.")
 
     def as_hive_ddl(self, database: str = "sagemaker_featurestore", table_name: str = None) -> str:
-        """Generate DDL can be used to create Hive table
+        """Generate Hive DDL commands that can be used to define or change structure of tables or
+        databases in Hive.
 
         Schema of the table is generated based on the feature definitions. Columns are named
-        after feature name and data-type are infered based on feature type. Integral feature
+        after feature name and data-type are inferred based on feature type. Integral feature
         type is mapped to INT data-type. Fractional feature type is mapped to FLOAT data-type.
         String feature type is mapped to STRING data-type.
 
@@ -464,7 +482,6 @@ def as_hive_ddl(self, database: str = "sagemaker_featurestore", table_name: str
         Returns:
             Generated create table DDL string.
         """
-
         if not table_name:
             table_name = self.name
 

src/sagemaker/feature_store/inputs.py

@@ -10,7 +10,22 @@
 # distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
 # ANY KIND, either express or implied. See the License for the specific
 # language governing permissions and limitations under the License.
-"""The input configs for FeatureStore."""
+"""The input configs for FeatureStore.
+
+A feature store serves as the single source of truth to store, retrieve,
+remove, track, share, discover, and control access to features.
+
+You can configure two types of feature stores, an online features store
+and an offline feature store.
+
+The online features store is a low latency, high availability cache for a
+feature group that enables real-time lookup of records. Only the latest record is stored.
+
+The offline feature store use when low (sub-second) latency reads are not needed.
+This is the case when you want to store and serve features for exploration, model training,
+and batch inference. The offline store uses your Amazon Simple Storage Service (Amazon S3)
+bucket for storage. A prefixing scheme based on event time is used to store your data in Amazon S3.
+"""
 from __future__ import absolute_import
 
 import abc
@@ -27,7 +42,7 @@ class Config(abc.ABC):
 
     @abc.abstractmethod
     def to_dict(self) -> Dict[str, Any]:
-        """Gets the dictionary from attributes.
+        """Get the dictionary from attributes.
 
         Returns:
             dict contains the attributes.
@@ -64,7 +79,7 @@ class OnlineStoreSecurityConfig(Config):
     kms_key_id: str = attr.ib(factory=str)
 
     def to_dict(self) -> Dict[str, Any]:
-        """Constructs a dictionary based on the attributes"""
+        """Construct a dictionary based on the attributes."""
         return Config.construct_dict(KmsKeyId=self.kms_key_id)
 
 
@@ -81,7 +96,7 @@ class OnlineStoreConfig(Config):
     online_store_security_config: OnlineStoreSecurityConfig = attr.ib(default=None)
 
     def to_dict(self) -> Dict[str, Any]:
-        """Constructs a dictionary based on the attributes.
+        """Construct a dictionary based on the attributes.
 
         Returns:
             dict represents the attributes.
@@ -105,7 +120,7 @@ class S3StorageConfig(Config):
     kms_key_id: str = attr.ib(default=None)
 
     def to_dict(self) -> Dict[str, Any]:
-        """Constructs a dictionary based on the attributes.
+        """Construct a dictionary based on the attributes provided.
 
         Returns:
             dict represents the attributes.
@@ -131,7 +146,7 @@ class DataCatalogConfig(Config):
     database: str = attr.ib(factory=str)
 
     def to_dict(self) -> Dict[str, Any]:
-        """Constructs a dictionary based on the attributes.
+        """Construct a dictionary based on the attributes provided.
 
         Returns:
             dict represents the attributes.
@@ -158,7 +173,7 @@ class OfflineStoreConfig(Config):
     data_catalog_config: DataCatalogConfig = attr.ib(default=None)
 
     def to_dict(self) -> Dict[str, Any]:
-        """Constructs a dictionary based on the attributes.
+        """Construct a dictionary based on the attributes.
 
         Returns:
             dict represents the attributes.
@@ -172,7 +187,7 @@ def to_dict(self) -> Dict[str, Any]:
 
 @attr.s
 class FeatureValue(Config):
-    """FeatureValue for FeatureStore
+    """FeatureValue for FeatureStore.
 
     Attributes:
         feature_name (str): name of the Feature.
@@ -183,7 +198,7 @@ class FeatureValue(Config):
     value_as_string: str = attr.ib(default=None)
 
     def to_dict(self) -> Dict[str, Any]:
-        """Constructs a dictionary based on the attributes.
+        """Construct a dictionary based on the attributes provided.
 
         Returns:
             dict represents the attributes.