Batch write and uncover data in Amazon SageMaker Characteristic Retailer

Amazon SageMaker Characteristic Retailer is a completely managed, purpose-built repository to retailer, share, and handle options for machine studying (ML) fashions. It offers low-latency on-line serving for real-time inference, an offline retailer for historic retention and coaching characteristic knowledge, and helps each streaming and batch ingestion patterns.

As ML platforms mature, two operational gaps floor repeatedly. First, groups working high-throughput characteristic pipelines should name PutRecord (which writes a single characteristic report to the web retailer) in a loop. This implies one API name per report, per characteristic group, which creates connection overhead and poor throughput. A fraud-detection pipeline ingesting 10,000 data per second throughout 5 characteristic teams should maintain 50,000 particular person API calls per second solely to maintain options present. A second problem is that groups utilizing the In-Reminiscence storage tier haven’t any technique to browse or enumerate data saved within the on-line retailer. If report identifiers are misplaced via a bug or pipeline failure, these data change into completely unrecoverable. There isn’t a offline retailer for the In-Reminiscence tier to fall again on, no Amazon Athena question to run, and no API to find what exists.

At the moment, we’re asserting two new APIs for Amazon SageMaker Characteristic Retailer:

1. BatchWriteRecord — Write as much as 25 data throughout a number of characteristic teams in a single API name, with partial-success semantics, per-record time-to-live (TTL) management, and the identical EventTime-based ordering ensures as PutRecord.
2. ListRecords — Enumerate report identifiers inside a characteristic group utilizing pagination. Works with each Commonplace (Amazon DynamoDB-backed) and In-Reminiscence (Redis-backed) storage tiers.

On this put up, we stroll via every API with code examples you should utilize to get began.

Stipulations

To observe together with the examples on this put up, you want:

BatchWriteRecord

The BatchWriteRecord API tackles the throughput limits of single-record ingestion. The next sections clarify the issue it solves and the way it works.

The problem with single-record ingestion

The prevailing PutRecord API in Characteristic Retailer writes one report to at least one characteristic group per name. Every name performs a conditional write: the report is continued because the “newest” model provided that its EventTime, included within the request, is newer than the prevailing report. If the situation fails, the report continues to be written as a historic model for the offline retailer.

This design offers robust ordering ensures, however at scale it forces an N×M calling sample (N data × M characteristic teams), creating connection overhead and tail latency that restrict throughput.

How BatchWriteRecord works

BatchWriteRecord accepts as much as 25 entries in a single request, concentrating on a number of characteristic teams concurrently. Every report succeeds or fails independently. It is a partial-success API, which means particular person report failures don’t fail the whole request.

The API preserves the identical EventTime-based ordering as PutRecord:

• If the incoming report’s EventTime is newer than the prevailing report, it turns into the most recent model within the on-line retailer.
• If not, the report is written as a historic model to the offline retailer (for characteristic teams with offline storage).
• Data that fail for different causes (authentication/validation errors, service throttling) are returned within the response with error particulars and the unique report.
• The requests which are unprocessed shall be returned in response as UnprocessedEntries which might be retried.

Request construction

{
    "Entries": [
        {
            "FeatureGroupName": "click-features",
            "Record": [
                {"FeatureName": "user_id", "ValueAsString": "user-123"},
                {"FeatureName": "event_time", "ValueAsString": "2026-06-05T12:00:00Z"},
                {"FeatureName": "click_count", "ValueAsString": "42"}
            ],
            "TargetStores": ["OnlineStore", "OfflineStore"],
            "TtlDuration": {"Unit": "Days", "Worth": 7}
        },
        {
            "FeatureGroupName": "login-features",
            "Report": [
                {"FeatureName": "user_id", "ValueAsString": "user-456"},
                {"FeatureName": "event_time", "ValueAsString": "2026-06-05T12:00:01Z"},
                {"FeatureName": "login_count", "ValueAsString": "18"}
            ],
            "TargetStores": ["OnlineStore", "OfflineStore"]
        }
    ]
}

The response returns solely the data that failed:

{
    "Errors": [
        {
            "Entry": {
                "FeatureGroupName": "string",
                "Record": [
                    {
                        "FeatureName": "string",
                        "ValueAsString": "string",
                        "ValueAsStringList": ["string"]
                    }
                ],
                "TargetStores": ["string"],
                "TtlDuration": {
                    "Unit": "string",
                    "Worth": quantity
                }
            },
            "ErrorCode": "string",
            "ErrorMessage": "string"
        }
    ],
    "UnprocessedEntries": [
        {
            "FeatureGroupName": "string",
            "Record": [
                {
                    "FeatureName": "string",
                    "ValueAsString": "string",
                    "ValueAsStringList": ["string"]
                }
            ],
            "TargetStores": ["string"],
            "TtlDuration": {
                "Unit": "string",
                "Worth": quantity
            }
        }
    ]
}

Data not listed in Errors or UnprocessedEntries succeeded. Your utility ought to retry solely the failed data utilizing exponential backoff for retriable errors.

Code instance: Batch ingestion with Boto3

import boto3

featurestore_runtime = boto3.shopper("sagemaker-featurestore-runtime")

response = featurestore_runtime.batch_write_record(
    Entries=[
        {
            "FeatureGroupName": "click-features",
            "Record": [
                {"FeatureName": "user_id", "ValueAsString": "user-123"},
                {"FeatureName": "event_time", "ValueAsString": "2026-06-05T12:00:00Z"},
                {"FeatureName": "click_count", "ValueAsString": "42"},
            ],
            "TargetStores": ["OnlineStore", "OfflineStore"],
        },
        {
            "FeatureGroupName": "login-features",
            "Report": [
                {"FeatureName": "user_id", "ValueAsString": "user-456"},
                {"FeatureName": "event_time", "ValueAsString": "2026-06-05T12:00:01Z"},
                {"FeatureName": "login_count", "ValueAsString": "18"},
            ],
            "TargetStores": ["OnlineStore", "OfflineStore"],
        },
    ]
)

if response["Errors"]:
    for error in response["Errors"]:
        print(f"Report {error['Entry']}, ErrorCode: {error['ErrorCode']} Failed: {error['ErrorMessage']}")

if response["UnprocessedEntries"]:
    for unprocessed in response["UnprocessedEntries"]:
        print(f"Unprocessed: {unprocessed['FeatureGroupName']}")

if not response["Errors"] and never response["UnprocessedEntries"]:
    print("All data written efficiently.")

Code instance: Writing throughout a number of characteristic teams

You’ll be able to goal a number of characteristic teams in a single request. Data are grouped by characteristic group and processed independently:

featurestore_runtime = boto3.shopper("sagemaker-featurestore-runtime")

response = featurestore_runtime.batch_write_record(
    Entries=[
        {
            "FeatureGroupName": "user-profile-features",
            "Record": [
                {"FeatureName": "user_id", "ValueAsString": "user-123"},
                {"FeatureName": "event_time", "ValueAsString": "2026-06-05T12:00:00Z"},
                {"FeatureName": "age", "ValueAsString": "34"},
                {"FeatureName": "region", "ValueAsString": "us-west-2"},
            ],
            "TargetStores": ["OnlineStore"],
        },
        {
            "FeatureGroupName": "click-features",
            "Report": [
                {"FeatureName": "user_id", "ValueAsString": "user-123"},
                {"FeatureName": "event_time", "ValueAsString": "2026-06-05T12:00:00Z"},
                {"FeatureName": "click_count", "ValueAsString": "42"},
            ],
            "TargetStores": ["OnlineStore", "OfflineStore"],
        },
    ]
)

A failure in a single characteristic group doesn’t have an effect on data destined for different characteristic teams.

TTL (Time-to-Reside) help

BatchWriteRecord helps TTL at three ranges of priority, proven within the following precedence order:

1. Report-level TTL — Set with TtlDuration on particular person entries. Takes highest precedence.
2. Request-level TTL — A default TtlDuration on the prime degree of the request, utilized to entries with no record-level TTL.
3. Characteristic-group-level TTL — The TTL configured on the characteristic group itself, utilized when neither record-level nor request-level TTL is ready.

Key concerns

Most 25 entries per request. This restrict applies to the overall variety of entries throughout all characteristic teams in a single request.

Partial-success semantics: In contrast to transactional APIs, BatchWriteRecord doesn’t roll again profitable writes if some data fail. Design your retry logic to re-submit solely the data returned in Errors.

Comparable IAM mannequin as PutRecord: The caller should have sagemaker:BatchWriteRecord and sagemaker:PutRecord permission on the Amazon Useful resource Identify (ARN) of every goal characteristic group. Per-feature-group authorization is checked earlier than processing.

EventTime ordering is preserved: BatchWriteRecord makes use of conditional writes to keep up the identical latest-record-wins semantics as PutRecord. A stale report can not overwrite a more moderen one within the on-line retailer.

TargetStores flexibility: Every entry can independently goal OnlineStore, OfflineStore, or each (defaults to the characteristic group’s enabled shops), supplying you with fine-grained management over the place every report lands.

ListRecords

The ListRecords API closes the hole in report discovery for each storage tiers. The next sections clarify the issue it solves and the way it works.

The problem with report discovery

Characteristic Retailer helps PutRecord, GetRecord, and DeleteRecord, however all require the caller to know the precise report identifier. There isn’t a API to browse or enumerate data inside a characteristic group.

For the Commonplace tier, the workaround is querying the offline retailer by utilizing Amazon Athena. This requires offline retailer configuration, provides value, and isn’t real-time.

For the In-Reminiscence tier, the scenario is important. There isn’t a corresponding offline retailer by default. If report identifiers are misplaced, these data are utterly unrecoverable. You can’t uncover them, and you can’t delete them. This results in phantom knowledge, wasted storage prices, and potential compliance dangers when knowledge topics request deletion.

How ListRecords works

ListRecords enumerates report identifiers inside a characteristic group utilizing pagination. It returns solely energetic, non-deleted, non-expired data which are prepared for use with GetRecord or DeleteRecord.

The API works with each storage tiers:

• Commonplace tier (Amazon DynamoDB): Scans the web retailer, returning identifier of the most recent model of every report. Smooth-deleted and expired data are mechanically excluded.
• In-Reminiscence tier (Redis): Scans keys and filters out soft-deleted data and inside system keys. Returns report identifiers extracted from key names.

Request and response construction

POST /FeatureGroup/{FeatureGroupName}/ListRecords

Request physique:

Preliminary name

Or

{
    "MaxResults": 50,
    "NextToken": "eyJjdXJzb3IiOi4uLn0="
}

Response:

{
    "RecordIdentifiers": [
        "user-001",
        "user-002",
        "user-003"
    ],
    "NextToken": "eyJuZXh0IjoiLi4ufQ=="
}

When NextToken is absent within the response, pagination is full.

Code instance: Enumerate all data in a characteristic group

import boto3

featurestore_runtime = boto3.shopper("sagemaker-featurestore-runtime")

all_identifiers = []
next_token = None

whereas True:
    params = {
        "FeatureGroupName": "user-profile-features",
        "MaxResults": 100,
    }
    if next_token:
        params["NextToken"] = next_token

    response = featurestore_runtime.list_records(**params)
    all_identifiers.lengthen(response["RecordIdentifiers"])

    next_token = response.get("NextToken")
    if not next_token:
        break

print(f"Discovered {len(all_identifiers)} energetic data.")

Code instance: Clear up orphaned data

A standard use case is figuring out and deleting data which are now not wanted. That is important for In-Reminiscence tier characteristic teams, the place orphaned data persist indefinitely:

import boto3

featurestore_runtime = boto3.shopper("sagemaker-featurestore-runtime")

# Step 1: Enumerate all report identifiers
all_ids = []
next_token = None
whereas True:
    params = {"FeatureGroupName": "session-features", "MaxResults": 100}
    if next_token:
        params["NextToken"] = next_token
    response = featurestore_runtime.list_records(**params)
    all_ids.lengthen(response["RecordIdentifiers"])
    next_token = response.get("NextToken")
    if not next_token:
        break

# Step 2: Evaluate towards your utility's energetic session listing
active_sessions = get_active_sessions()  # Your utility logic
orphaned = [rid for rid in all_ids if rid not in active_sessions]

# Step 3: Delete orphaned data
for record_id in orphaned:
    featurestore_runtime.delete_record(
        FeatureGroupName="session-features",
        RecordIdentifierValueAsString=record_id,
        EventTime="2026-06-05T12:00:00Z",
    )

print(f"Deleted {len(orphaned)} orphaned data.")

• Web page dimension: Configurable via MaxResults (default 10, most 100).
• Token format: Opaque, encrypted string. Don’t parse or assemble tokens. Move them via unchanged.
• Ordering: Outcomes should not assured to be in any explicit order.
• Concurrent writes: If data are written or deleted throughout pagination, it’s possible you’ll observe duplicates or gaps. That is documented conduct.
• Token scope: Tokens are tied to a selected characteristic group and account and can’t be reused throughout both.

Key concerns

Report identifiers solely. The present launch returns report identifiers with out characteristic values. Use GetRecord or BatchGetRecord to retrieve full data for the identifiers you want.

Computerized filtering. The API excludes soft-deleted data, expired data (Commonplace tier TTL), and inside system keys (In-Reminiscence tier). You see solely energetic, retrievable data.

IAM permission. The caller should have sagemaker:ListRecords permission on the characteristic group ARN.

Each tiers supported. ListRecords works identically from the caller’s perspective no matter whether or not the characteristic group makes use of Commonplace or In-Reminiscence storage.

Placing it collectively

These two APIs complement one another naturally. Contemplate a compliance workflow that verifies full knowledge deletion for a consumer throughout a number of characteristic teams:

import boto3

featurestore_runtime = boto3.shopper("sagemaker-featurestore-runtime")

feature_groups = ["user-profiles", "click-history", "purchase-signals"]
user_to_delete = "user-789"

# Step 1: Discover and delete the consumer throughout all characteristic teams
for fg_name in feature_groups:
    all_ids = []
    next_token = None
    whereas True:
        params = {"FeatureGroupName": fg_name, "MaxResults": 100}
        if next_token:
            params["NextToken"] = next_token
        response = featurestore_runtime.list_records(**params)
        all_ids.lengthen(response["RecordIdentifiers"])
        next_token = response.get("NextToken")
        if not next_token:
            break

    if user_to_delete in all_ids:
        featurestore_runtime.delete_record(
            FeatureGroupName=fg_name,
            RecordIdentifierValueAsString=user_to_delete,
            EventTime="2026-06-05T23:59:59Z",
        )
        print(f"Deleted '{user_to_delete}' from {fg_name}")

# Step 2: Log the deletion occasion utilizing BatchWriteRecord
featurestore_runtime.batch_write_record(
    Entries=[
        {
            "FeatureGroupName": "deletion-audit-log",
            "Record": [
                {"FeatureName": "request_id", "ValueAsString": "del-001"},
                {"FeatureName": "event_time", "ValueAsString": "2026-06-05T23:59:59Z"},
                {"FeatureName": "user_id", "ValueAsString": user_to_delete},
                {"FeatureName": "status", "ValueAsString": "completed"},
                {"FeatureName": "feature_groups_cleaned", "ValueAsString": "3"},
            ],
            "TargetStores": ["OnlineStore", "OfflineStore"],
        }
    ]
)

Cleanup

To keep away from ongoing expenses, delete characteristic teams you created whereas following this walkthrough. For In-Reminiscence tier characteristic teams, use ListRecords to enumerate data and DeleteRecord to take away them earlier than deleting the characteristic group.

Conclusion

BatchWriteRecord and ListRecords present key enhancements within the knowledge aircraft of Amazon SageMaker Characteristic Retailer. BatchWriteRecord reduces the API name quantity for high-throughput ingestion by as much as 25x whereas preserving the EventTime-based ordering ensures that preserve your on-line retailer right. ListRecords unlocks report discovery and lifecycle administration. That is important for In-Reminiscence tier prospects who beforehand had no technique to enumerate or clear up their knowledge.

Collectively, these APIs help patterns that have been beforehand tough or not possible: bulk ingestion pipelines with fewer connections and decrease latency, compliance workflows that may confirm full knowledge deletion, and operational tooling that may browse characteristic group contents in actual time.

For extra info, see the Characteristic Retailer documentation, the Characteristic Retailer API reference, the offline retailer configuration documentation, and the What’s New announcement.

For background on Characteristic Retailer capabilities, discover these associated posts:

In regards to the authors