DynamoDB Streams Lambda Filter Criteria for MCP Servers — Event Type Filtering, Attribute Patterns

Filter criteria structure and evaluation model

Lambda evaluates filter criteria before invoking the function. Each filter is a JSON object that specifies patterns against the DynamoDB Streams record structure. Multiple filters in the same FilterCriteria are OR-combined: a record matches if it satisfies any one filter. Within a single filter, all patterns are AND-combined: every specified pattern must match for the filter to pass.

The DynamoDB Streams record structure that filters act on:

{
  "eventName": "MODIFY",          // INSERT | MODIFY | REMOVE
  "dynamodb": {
    "Keys": {
      "PK": { "S": "SERVER#alivemcp.com" },
      "SK": { "S": "STATUS" }
    },
    "NewImage": {
      "PK": { "S": "SERVER#alivemcp.com" },
      "SK": { "S": "STATUS" },
      "status": { "S": "DEGRADED" },
      "consecutiveFailures": { "N": "5" },
      "lastCheckedAt": { "N": "1735600000" }
    },
    "OldImage": {
      "status": { "S": "HEALTHY" },
      "consecutiveFailures": { "N": "0" }
    },
    "StreamViewType": "NEW_AND_OLD_IMAGES"
  }
}

Filter patterns use the same JSON path syntax as EventBridge rules. The top-level keys (eventName, dynamodb) map directly to the DynamoDB Streams record. Attribute access uses dot notation; DynamoDB type descriptors (S, N, BOOL, L, M) are part of the path.

Filter pattern types

Lambda ESM filter criteria support a subset of the EventBridge content filtering patterns:

Numeric comparisons operate on the DynamoDB N type value as a number, not a string — so "N": [{"numeric": [">", 2]}] correctly compares the attribute value numerically even though DynamoDB stores numbers as strings. Supported operators: =, !=, <, <=, >, >=, and range ([">", 0, "<=", 100]).

Practical patterns for MCP probe state tables

An AliveMCP probe state table has a natural set of filtering use cases: alerting on status degradation, processing only new endpoint registrations, and reacting to recovery events. Each maps to a distinct filter pattern:

Pattern 1: Status degradation alerter — trigger Lambda only when a probe transitions from HEALTHY to DEGRADED or DOWN:

// AWS SDK / CloudFormation / CDK filter for degradation alerting
const degradationFilter = {
  Pattern: JSON.stringify({
    eventName: ["MODIFY"],
    dynamodb: {
      NewImage: {
        status: { S: [{ "anything-but": ["HEALTHY"] }] }
      },
      OldImage: {
        status: { S: ["HEALTHY"] }  // Only fire on transitions FROM healthy
      }
    }
  })
};

Pattern 2: New endpoint registration — trigger downstream provisioning (create monitoring schedule, initialize metrics) only on first INSERT of a server record:

const registrationFilter = {
  Pattern: JSON.stringify({
    eventName: ["INSERT"],
    dynamodb: {
      Keys: {
        PK: { S: [{ prefix: "SERVER#" }] },
        SK: { S: ["METADATA"] }  // Only the canonical metadata record, not status sub-records
      }
    }
  })
};

Pattern 3: Recovery events — log recovery metrics when a server transitions back to HEALTHY after a degraded period:

const recoveryFilter = {
  Pattern: JSON.stringify({
    eventName: ["MODIFY"],
    dynamodb: {
      NewImage: { status: { S: ["HEALTHY"] } },
      OldImage: { status: { S: [{ "anything-but": ["HEALTHY"] }] } }
    }
  })
};

These three filters can be combined into a single ESM with all three as separate filter objects (OR-combined), using up to 5 filters per ESM.

CDK DynamoEventSource with FilterCriteria

In AWS CDK (TypeScript), attach filters via the DynamoEventSource construct. Lambda ESM supports up to 5 filter patterns per event source mapping:

import * as lambda from 'aws-cdk-lib/aws-lambda';
import * as eventsources from 'aws-cdk-lib/aws-lambda-event-sources';
import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';

declare const probeTable: dynamodb.Table;
declare const alerterFn: lambda.Function;

// Alerter: only invoked on status degradation transitions
alerterFn.addEventSource(new eventsources.DynamoEventSource(probeTable, {
  startingPosition: lambda.StartingPosition.LATEST,
  batchSize: 100,
  maxBatchingWindow: cdk.Duration.seconds(5),  // Wait up to 5s to batch degradation events
  bisectBatchOnError: true,         // Isolate poison-pill records via binary split
  retryAttempts: 2,
  onFailure: new eventsources.SqsDlq(dlqQueue),
  streamViewType: dynamodb.StreamViewType.NEW_AND_OLD_IMAGES,  // Required for OldImage filtering
  filters: [
    // Filter 1: status degradation (HEALTHY → DEGRADED or DOWN)
    lambda.FilterCriteria.filter({
      eventName: lambda.FilterRule.isEqual('MODIFY'),
      dynamodb: {
        NewImage: { status: { S: lambda.FilterRule.notExists() } }
      }
    }),
    // Filter 2: status degradation (explicit DEGRADED)
    lambda.FilterCriteria.filter({
      eventName: lambda.FilterRule.isEqual('MODIFY'),
      dynamodb: {
        NewImage: { status: { S: lambda.FilterRule.isEqual('DEGRADED') } },
        OldImage: { status: { S: lambda.FilterRule.isEqual('HEALTHY') } }
      }
    }),
    // Filter 3: new server registration
    lambda.FilterCriteria.filter({
      eventName: lambda.FilterRule.isEqual('INSERT'),
      dynamodb: {
        Keys: { SK: { S: lambda.FilterRule.isEqual('METADATA') } }
      }
    })
  ]
}));

The CDK FilterRule helper maps to the underlying JSON filter pattern syntax. Note that streamViewType must be NEW_AND_OLD_IMAGES if your filters reference OldImage — if the stream is configured with NEW_IMAGE only, OldImage will be absent from all records and OldImage-based filters will never match.

Performance and cost implications

A common misconception is that filter criteria reduce the DynamoDB Streams read throughput consumed by Lambda ESM. They do not. Lambda ESM reads every record from every shard regardless of filter criteria — filtering happens in the Lambda service layer after reading, before deciding whether to invoke the function. The performance benefits are:

For a probe state table with 1,000 monitored servers and 60-second probe intervals, roughly 1,000 MODIFY events per minute are written for routine HEALTHY probe results. If only 1% of probes find degraded endpoints, filter criteria reduce Lambda alerter invocations from ~17/second to ~0.17/second — a 100× compute cost reduction. The DynamoDB Streams shard read capacity consumed remains the same.

StreamViewType requirements for filtering

Filter criteria access the record structure as written to the stream. The stream's StreamViewType determines which images are available for filtering:

For AliveMCP probe state alerting, NEW_AND_OLD_IMAGES is required because the most critical filter — detecting status transitions from HEALTHY to DEGRADED — requires comparing OldImage.status against NewImage.status. StreamViewType cannot be changed on an existing stream; you must disable and re-enable streams on the table (which resets the stream's shard sequence) or create a new table.

Complete failure mode reference