matchnet

Checks whether the IP address field value of input records is included in the specified subnet group, and filters matching records.

Command properties

Property	Description
Command type	Transforming
Required permission	None
License usage	N/A
Parallel execution	Supported
Distributed execution	Runs on Data Node (mapper)

Syntax

matchnet guid=STR field=FIELD [invert=BOOL] [verify=BOOL] [tag=BOOL]

Options

guid=STR: GUID of the subnet group to match against.
field=FIELD: Name of the IP address field to match.
invert=BOOL: Whether to invert the match result. (Default: f)

t: Outputs records not included in the subnet group.
f: Outputs records included in the subnet group.

verify=BOOL: Whether to verify that the subnet group exists. (Default: t)

t: Verifies that the subnet group exists at parse time.
f: Skips subnet group validation.

tag=BOOL: Whether to output matched subnet information. (Default: f)

t: Assigns matched subnet information as a map to the _matchnet_result field.
f: Does not output subnet information.

Input fields

Field	Type	Required	Description
Field specified by `field`	string, IP address, or integer	Required	IPv4 address to match. Must be a string, `Inet4Address`, or integer type. Null values or IPv6 addresses are treated as non-matching.

Output fields

When tag=t is specified, the following field is added to matching records.

Field	Type	Description
`_matchnet_result`	object	Matched subnet information. Contains `id`, `start_ip`, `end_ip`, `cidr`, and `description` keys.

Keys in the _matchnet_result map:

Key	Type	Description
`id`	integer	Subnet entry ID
`start_ip`	string	Start IP address of the subnet
`end_ip`	string	End IP address of the subnet
`cidr`	integer	CIDR prefix length
`description`	string	Subnet description (only when configured)

Error codes

Parse errors

Error code	Message	Description
300025	Specify the guid option for the matchnet command.	The `guid` option was not specified.
300026	Specify the field option for the matchnet command.	The `field` option was not specified.
300027	The guid option for the matchnet command must be in GUID format.	The `guid` option value is not a valid GUID format.
300028	No subnet group found for the specified guid.	No subnet group exists for the specified `guid`.
300029	Failed to load the subnet group data.	An error occurred while loading subnet group data.

Runtime errors

None

Description

The matchnet command checks whether the IP address value of the field specified by the field option is included in the subnets defined in the subnet group. Only IPv4 addresses are supported. If the field value is null, an IPv6 address, or an unsupported type, the record is treated as non-matching.

When tag=t is specified, detailed information about the matched subnet (start IP, end IP, CIDR, description) is assigned as a map to the _matchnet_result field.

When invert=t is specified, only records not included in the subnet group are output.

When verify=f is specified, the existence of the subnet group is not verified at parse time. Use this when the subnet group is synchronized later in a real-time stream query.

If the subnet group is updated during execution, the new subnet information is automatically reflected. In a distributed environment, filtering runs on the Data Node.

Examples

Filter records included in a subnet group

json "[{'src_ip': '192.0.2.1'}, {'src_ip': '198.51.100.5'}, {'src_ip': '203.0.113.10'}]"
| matchnet guid=550e8400-e29b-41d4-a716-446655440000 field=src_ip

Outputs only records where the src_ip field value is included in the specified subnet group.

Filter records not included in a subnet group

json "[{'src_ip': '192.0.2.1'}, {'src_ip': '198.51.100.5'}]"
| matchnet guid=550e8400-e29b-41d4-a716-446655440000 field=src_ip invert=t

Outputs only records where the src_ip field value is not included in the subnet group.

Include matched subnet information
```
json "[{'src_ip': '192.0.2.1'}, {'src_ip': '198.51.100.5'}]"
| matchnet guid=550e8400-e29b-41d4-a716-446655440000 field=src_ip tag=t
```
Adds a _matchnet_result field to matching records, outputting the start IP, end IP, CIDR, and description of the matched subnet as a map.

Skip subnet group validation

json "[{'src_ip': '192.0.2.1'}]"
| matchnet guid=550e8400-e29b-41d4-a716-446655440000 field=src_ip verify=f

Runs without verifying the existence of the subnet group at parse time.