Batch write and uncover data in Amazon SageMaker Characteristic Retailer

Amazon SageMaker Characteristic Retailer is a totally 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 operating high-throughput characteristic pipelines should name PutRecord (which writes a single characteristic file to the web retailer) in a loop. This implies one API name per file, 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 strategy to browse or enumerate data saved within the on-line retailer. If file identifiers are misplaced by way of a bug or pipeline failure, these data turn into completely unrecoverable. There isn’t any offline retailer for the In-Reminiscence tier to fall again on, no Amazon Athena question to run, and no API to find what exists.

As we speak, we’re saying two new APIs for Amazon SageMaker Characteristic Retailer:

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.
ListRecords — Enumerate file identifiers inside a characteristic group utilizing pagination. Works with each Normal (Amazon DynamoDB-backed) and In-Reminiscence (Redis-backed) storage tiers.

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

Stipulations

To comply with 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 present PutRecord API in Characteristic Retailer writes one file to 1 characteristic group per name. Every name performs a conditional write: the file is continued because the “newest” model provided that its EventTime, included within the request, is newer than the present file. If the situation fails, the file remains 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, focusing on a number of characteristic teams concurrently. Every file succeeds or fails independently. It is a partial-success API, which means particular person file failures don’t fail your complete request.

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

If the incoming file’s EventTime is newer than the present file, it turns into the newest model within the on-line retailer.
If not, the file is written as a historic model to the offline retailer (for characteristic teams with offline storage).
Information that fail for different causes (authentication/validation errors, service throttling) are returned within the response with error particulars and the unique file.
The requests which are unprocessed will probably be returned in response as UnprocessedEntries which will 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
            }
        }
    ]
}

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

Code instance: Batch ingestion with Boto3

import boto3

featurestore_runtime = boto3.consumer("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 possibly can goal a number of characteristic teams in a single request. Information are grouped by characteristic group and processed independently:

featurestore_runtime = boto3.consumer("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-Stay) assist

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

Report-level TTL — Set with TtlDuration on particular person entries. Takes highest precedence.
Request-level TTL — A default TtlDuration on the prime degree of the request, utilized to entries and not using a record-level TTL.
Characteristic-group-level TTL — The TTL configured on the characteristic group itself, utilized when neither record-level nor request-level TTL is about.

Key concerns

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

Partial-success semantics: Not like 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 will need to 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 file can’t 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), providing you with fine-grained management over the place every file lands.

ListRecords

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

The problem with file discovery

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

For the Normal tier, the workaround is querying the offline retailer through the use of Amazon Athena. This requires offline retailer configuration, provides value, and isn’t real-time.

For the In-Reminiscence tier, the state of affairs is crucial. There isn’t any corresponding offline retailer by default. If file identifiers are misplaced, these data are fully unrecoverable. You can’t uncover them, and you can not delete them. This results in phantom knowledge, wasted storage prices, and potential compliance dangers when knowledge topics request deletion.

How ListRecords works

ListRecords enumerates file 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:

Normal tier (Amazon DynamoDB): Scans the web retailer, returning identifier of the newest model of every file. Comfortable-deleted and expired data are robotically excluded.
In-Reminiscence tier (Redis): Scans keys and filters out soft-deleted data and inner system keys. Returns file identifiers extracted from key names.

Request and response construction

POST /FeatureGroup/{FeatureGroupName}/ListRecords

Request physique:

Preliminary name

{
    "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.consumer("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.prolong(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 typical use case is figuring out and deleting data which are now not wanted. That is crucial for In-Reminiscence tier characteristic teams, the place orphaned data persist indefinitely:

import boto3

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

# Step 1: Enumerate all file 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.prolong(response["RecordIdentifiers"])
    next_token = response.get("NextToken")
    if not next_token:
        break

# Step 2: Examine towards your software's energetic session checklist
active_sessions = get_active_sessions()  # Your software 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 measurement: Configurable by way of MaxResults (default 10, most 100).
Token format: Opaque, encrypted string. Don’t parse or assemble tokens. Move them by way of unchanged.
Ordering: Outcomes are usually not assured to be in any specific order.
Concurrent writes: If data are written or deleted throughout pagination, chances are 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 file identifiers with out characteristic values. Use GetRecord or BatchGetRecord to retrieve full data for the identifiers you want.

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

IAM permission. The caller will need to 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 Normal or In-Reminiscence storage.

Placing it collectively

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

import boto3

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

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

# Step 1: Discover and delete the person 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.prolong(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 costs, 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 hold your on-line retailer appropriate. ListRecords unlocks file discovery and lifecycle administration. That is crucial for In-Reminiscence tier prospects who beforehand had no strategy to enumerate or clear up their knowledge.

Collectively, these APIs assist patterns that have been beforehand tough or unimaginable: 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 data, 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: