Expand Range

Mutate Array Processing

Synopsis

Expands range expressions into arrays of individual values.

Schema

- expand_range:
    field: <ident>
    target_field: <string>
    range_type: <string>
    separator: <string>
    range_separator: <string>
    step_separator: <string>
    output_format: <string>
    output_separator: <string>
    sort: <boolean>
    unique: <boolean>
    reverse: <boolean>
    max_values: <integer>
    pad_zeros: <integer>
    prefix: <string>
    suffix: <string>
    validate_range: <boolean>
    description: <text>
    if: <script>
    ignore_failure: <boolean>
    ignore_missing: <boolean>
    on_failure: <processor[]>
    on_success: <processor[]>
    tag: <string>

Configuration

The following fields are used to define the processor:

Field	Required	Default	Description
field	Y	-	Source field containing range expression to expand
target_field	N	Same as field	Target field to store expanded values
range_type	N	numeric	Range type (numeric, port, ip, ipv6, cidr, letter, alphanumeric, custom)
separator	N	,	Separator for multiple ranges
range_separator	N	-	Separator for range bounds (start-end)
step_separator	N	:	Separator for step values (1-10:2)
output_format	N	array	Output format (array, string, count, min_max, json)
output_separator	N	,	Separator for string output format
sort	N	false	Sort the expanded values
unique	N	false	Remove duplicate values
reverse	N	false	Reverse the order of values
max_values	N	1048576	Maximum number of values to expand. A hard ceiling of 1,048,576 applies regardless: leaving this unset, or setting it higher, still stops at that number. A range that would exceed the effective limit fails the processor rather than truncating
pad_zeros	N	-	Pad numbers with leading zeros
prefix	N	-	Add prefix to each expanded value
suffix	N	-	Add suffix to each expanded value
validate_range	N	false	Validate range bounds (e.g., ports 1-65535)
description	N	-	Explanatory note
if	N	-	Condition to run
ignore_failure	N	false	Continue processing if expansion fails
ignore_missing	N	false	Skip processing if referenced field doesn't exist
on_failure	N	-	See Handling Failures
on_success	N	-	See Handling Success
tag	N	-	Identifier
disabled	N	false	When true, the processor is skipped and the event continues to the next one. Lets you take a processor out of the path without removing its configuration

Details

Expands range expressions into individual values supporting various data types including numbers, IP addresses, ports, letters, and custom patterns. The processor handles multiple range formats with step values and extensive output customization.

The processor supports different range types with intelligent expansion logic. Numeric ranges support step values (1-10:2 = 1,3,5,7,9), IP ranges handle both full addresses and subnet expansions, and alphanumeric ranges can expand patterns like "host001-host010".

note

Range expansion can generate large numbers of values. The processor stops with an error the moment the limit is reached — it does not return a truncated list, so a partial expansion can never be mistaken for a complete one.

There is no unlimited setting. max_values lowers the ceiling; it cannot raise it past 1,048,576. That bound exists so a range such as 0.0.0.0/0 fails cleanly instead of exhausting memory.

The processor offers multiple output formats including arrays, formatted strings, counts, and JSON objects with metadata. Post-processing options include sorting, deduplication, and value transformation with prefixes/suffixes.

warning

CIDR expansion can generate thousands of IP addresses. A /24 network produces 256 IPs and a /16 network 65,536 — both well inside the ceiling. A /12 produces 1,048,576 and a /11 exceeds it and fails.

Examples

Basic Numeric Range

Expanding simple numeric range...	{ "range": "1-5" } - expand_range: field: range range_type: numeric target_field: numbers
creates array of values:	{ "range": "1-5", "numbers": ["1", "2", "3", "4", "5"] }

Port Range with Validation

Expanding port ranges with validation...	{ "ports": "80,443,8080-8090" } - expand_range: field: ports range_type: port validate_range: true sort: true target_field: port_list
expands and validates port numbers:	{ "ports": "80,443,8080-8090", "port_list": ["80", "443", "8080", "8081", "8082", "8083", "8084", "8085", "8086", "8087", "8088", "8089", "8090"] }

IP Address Range

Expanding IP address ranges...	{ "ip_range": "192.168.1.10-15" } - expand_range: field: ip_range range_type: ip output_format: json target_field: ip_details
generates IP addresses with metadata:	{ "ip_range": "192.168.1.10-15", "ip_details": { "values": ["192.168.1.10", "192.168.1.11", "192.168.1.12", "192.168.1.13", "192.168.1.14", "192.168.1.15"], "count": 6, "first": "192.168.1.10", "last": "192.168.1.15" } }

Step-based Numeric Range

Using step values for numeric expansion...	{ "sequence": "10-50:5" } - expand_range: field: sequence range_type: numeric output_format: string output_separator: ", " target_field: step_sequence
creates stepped sequence:	{ "sequence": "10-50:5", "step_sequence": "10, 15, 20, 25, 30, 35, 40, 45, 50" }

Alphanumeric Pattern Expansion

Expanding alphanumeric host patterns...	{ "hosts": "server001-server005" } - expand_range: field: hosts range_type: alphanumeric prefix: "prod-" suffix: ".example.com" target_field: hostnames
generates formatted hostnames:	{ "hosts": "server001-server005", "hostnames": [ "prod-server001.example.com", "prod-server002.example.com", "prod-server003.example.com", "prod-server004.example.com", "prod-server005.example.com" ] }

CIDR Network Expansion

Expanding CIDR network notation...	{ "subnet": "10.0.1.0/28" } - expand_range: field: subnet range_type: cidr max_values: 20 output_format: count target_field: subnet_info
returns network size information:	{ "subnet": "10.0.1.0/28", "subnet_info": 16 }

Letter Range with Formatting

Expanding letter ranges with case formatting...	{ "columns": "a-f" } - expand_range: field: columns range_type: letter prefix: "Column_" sort: true reverse: true target_field: column_headers
creates formatted column names:	{ "columns": "a-f", "column_headers": ["Column_f", "Column_e", "Column_d", "Column_c", "Column_b", "Column_a"] }