Programmable Push Filters

You can use push-down filters in Redpanda Cloud to search through large Kafka topics that may contain millions of records. Filters are JavaScript functions executed on the backend, evaluating each record individually. Your function must return a boolean:

  • true: record is included in the frontend results.

  • false: record is skipped.

Multiple filters combine logically with AND conditions.

Add a JavaScript filter

To add a JavaScript filter:

  1. Navigate to the topic’s Messages page.

  2. Click Add filter > JavaScript Filter.

  3. Define your JavaScript filtering logic in the provided input area.

Resource usage and performance

JavaScript filters are executed on the backend, consuming CPU and network resources. The performance of your filter depends on the complexity of your JavaScript code and the volume of data being processed. Complex JavaScript logic or large data volumes may increase CPU load and network usage.

Available JavaScript properties

Redpanda Cloud injects these properties into your JavaScript context:

Property Description Type

headers

Record headers as key-value pairs (ArrayBuffers)

Object

key

Decoded record key

String

keySchemaID

Schema Registry ID for key (if present)

Number

partitionId

Partition ID of the record

Number

offset

Record offset within partition

Number

timestamp

Timestamp as JavaScript Date object

Date

value

Decoded record value

Object/String

valueSchemaID

Schema Registry ID for value (if present)

Number
Values, keys, and headers are deserialized before being injected into your script.

JavaScript filter examples

Filter by header value

Scenario: Records tagged with headers specifying customer plan type.

Sample header data (string value)
headers: {
  "plan_type": "premium"
}
json
JavaScript filter
let headerValue = headers["plan_type"];
if (headerValue) {
  let stringValue = String.fromCharCode(...new Uint8Array(headerValue));
  return stringValue === "premium";
}
return false;
javascript

Scenario: Records include a header with JSON-encoded customer metadata.

Sample header data (JSON value)
headers: {
"customer": "{"orgID":"123-abc","name":"ACME Inc."}"
}
json
JavaScript filter
let headerValue = headers["customer"];
if (headerValue) {
  let stringValue = String.fromCharCode(headerValue);
  let valueObj = JSON.parse(stringValue);
  return valueObj["orgID"] === "123-abc";
}
return false;
javascript

Filter by timestamp

Scenario: Retrieve records from a promotional event.

JavaScript filter
return timestamp.getMonth() === 10 && timestamp.getDate() === 24;
javascript

Filter by schema ID

Scenario: Filter customer activity records based on Avro schema version.

JavaScript filter
return valueSchemaID === 204;
javascript

Filter JSON record values

Scenario: Filter transactions by customer ID.

Sample JSON record
{
  "transaction_id": "abc123",
  "customer_id": "cust789",
  "amount": 59.99
}
json
JavaScript filter (top-level property)
return value.customer_id === "cust789";
javascript

Scenario: Filter orders by item availability.

Sample JSON record
{
  "order_id": "ord456",
  "inventory": {
    "item_id": "itm001",
    "status": "in_stock"
  }
}
json
JavaScript filter (nested property)
return value.inventory.status === "in_stock";
javascript

Scenario: Filter products missing price information.

JavaScript filter (property absence)
return !value.hasOwnProperty("price");
javascript

Filter string keys

Scenario: Filter sensor data records by IoT device ID.

JavaScript filter
return key === "sensor-device-1234";
javascript