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	-	Maximum number of values to expand
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

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. Use max_values to prevent excessive memory usage or processing time. The processor checks this limit during expansion and fails safely if exceeded.

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, while a /16 network generates 65,536 IPs. Always set appropriate max_values limits for network expansions.

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"] }