Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Add features and records to a feature group

You can use the Amazon SageMaker Feature Store API or the console to update and describe your feature group as well as add features and records to your feature group. A feature group is an object that contains your data and a feature describes a column in the table. When you add a feature to the feature group you are effectively adding a column to the table. When you add a new record to the feature group you are filling in values for features associated with a specific record identifier. For more information on Feature Store concepts, see Feature Store concepts.

After you successfully add features to a feature group, you cannot remove those features. The features that you have added do not add any data to your records. You can add new records to the feature group or overwrite them using the PutRecord or BatchWriteRecord API operations. For examples on updating, describing, and putting records into a feature group, see Example code.

You can use the console to add features to a feature group. For more information on how to update your feature groups using the console, see Update a feature group from the console.

The following sections provide an overview of using Feature Store APIs to add features to a feature group followed by examples. With the API, you can also add or overwrite records after you have updated the feature group.

API

Use the UpdateFeatureGroup operation to add features to a feature group.

You can use the DescribeFeatureGroup operation to see if you have added the features successfully.

To add or overwrite records, use the PutRecord operation. To write up to 25 records in a single request, use the BatchWriteRecord operation.

To see the updates that you have made to a record, use the GetRecord operation. To see the updates that you have made to multiple records, use the BatchGetRecord operation. It can take up to five minutes for the updates to appear.

You can use the example code in the following section to walk through adding features and records using the Amazon SDK for Python (Boto3).

Example code

The example code walks you through the following process:

Step 1: Add features to a feature group

The following code uses the UpdateFeatureGroup operation to add new features to the feature group. It assumes that you have set up Feature Store and created a feature group. For more information about getting started, see Introduction to Feature Store example notebook.

import boto3

sagemaker_client = boto3.client("sagemaker")

sagemaker_client.update_feature_group(
    FeatureGroupName=feature_group_name,
    FeatureAdditions=[
        {"FeatureName": "new-feature-1", "FeatureType": "Integral"},
        {"FeatureName": "new-feature-2", "FeatureType": "Fractional"},
        {"FeatureName": "new-feature-3", "FeatureType": "String"}
    ]
)              
          

The following code uses the DescribeFeatureGroup operation to check the status of the update. If the LastUpdateStatus field is Successful, you have added the features successfully.

sagemaker_client.describe_feature_group(
    FeatureGroupName=feature_group_name
)
          

Step 2: Add a new record to the feature group

The following code uses the PutRecord operation to add records to the feature group that you have created.

record_identifier_value = 'new_record'

sagemaker_featurestore_runtime_client = boto3.client("sagemaker-featurestore-runtime")

sagemaker_runtime_client.put_record(
    FeatureGroupName=feature_group_name,
    Record=[
        {
            'FeatureName': "record-identifier-feature-name",
            'ValueAsString': record_identifier_value
        },
        {
            'FeatureName': "event-time-feature",
            'ValueAsString': "timestamp-that-feature-store-returns"
        },
        {
            'FeatureName': "new-feature-1", 
            'ValueAsString': "value-as-string"
        },
        {
            'FeatureName': "new-feature-2", 
            'ValueAsString': "value-as-string"
        },
        {
            'FeatureName': "new-feature-3", 
            'ValueAsString': "value-as-string"
        },
    ]
)              
          

Use the GetRecord operation to see which records in your feature group do not have data for the features that you have added. You can use the PutRecord operation to overwrite the records that do not have data for the features that you have added.

Step 3: Add multiple records in bulk using BatchWriteRecord

To add or overwrite multiple records, use the BatchWriteRecord operation. To automatically expire records, specify a TtlDuration:

response = sagemaker_featurestore_runtime_client.batch_write_record(
    Entries=[
        {
            'FeatureGroupName': feature_group_name,
            'Record': [
                {'FeatureName': "record-identifier-feature-name", 'ValueAsString': 'record_1'},
                {'FeatureName': "event-time-feature", 'ValueAsString': "2024-01-01T00:00:00Z"},
                {'FeatureName': "new-feature-1", 'ValueAsString': "value-1"},
            ],
            'TtlDuration': {'Unit': 'Hours', 'Value': 24}
        },
        {
            'FeatureGroupName': feature_group_name,
            'Record': [
                {'FeatureName': "record-identifier-feature-name", 'ValueAsString': 'record_2'},
                {'FeatureName': "event-time-feature", 'ValueAsString': "2024-01-01T00:00:00Z"},
                {'FeatureName': "new-feature-1", 'ValueAsString': "value-2"},
            ]
        }
    ]
)

# Check for failed records.
if response['Errors']:
    for error in response['Errors']:
        print(f"Error: {error['ErrorCode']} - {error['ErrorMessage']}")

# Retry unprocessed entries.
unprocessed = response.get('UnprocessedEntries', [])
while unprocessed:
    response = sagemaker_featurestore_runtime_client.batch_write_record(Entries=unprocessed)
    unprocessed = response.get('UnprocessedEntries', [])
          

The response includes an Errors list for records that failed and an UnprocessedEntries list for records that can be retried.