matchbehavior

Matches input records against a behavior profile using the key fields defined in the profile, and appends the value fields from matched behavior profile records to the output 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

matchbehavior guid=STR [invert=BOOL] [verify=BOOL]

Options

guid=STR: Behavior profile GUID.
invert=BOOL: Inverts the match result. When set to t, outputs records that are not included in the behavior profile. (Default: f)
verify=BOOL: Whether to validate the behavior profile object. When set to f, skips validation of the behavior profile at parse time. (Default: t)

Output fields

On match success (invert=f):

Field	Type	Description
`behavior_guid`	string	GUID of the matched behavior profile
`behavior_invert`	boolean	Whether inversion is enabled
Behavior profile value fields	-	All value fields from the matched behavior profile record are appended to the output record.

On match failure (invert=t):

Field	Type	Description
`behavior_guid`	string	Behavior profile GUID
`behavior_invert`	boolean	Whether inversion is enabled

Error codes

Parse errors

Error code	Message	Description
300030	Specify the guid option for the matchbehavior command.	The `guid` option was not specified.
300031	The guid option value for the matchbehavior command must be in GUID format.	The `guid` option value is not a valid GUID.
300032	The specified behavior profile does not exist.	No behavior profile exists for the specified GUID.
300033	Failed to load the behavior profile.	An error occurred while reading the behavior profile data.

Runtime errors

None

Description

The matchbehavior command compares input records against behavior profile data using the key field values defined in the behavior profile. If the key field value of an input record exists in the behavior profile, all value fields from the matched behavior profile record are merged into the input record and output.

When invert=t is specified, only records not found in the behavior profile are output. In this case, the value fields of the behavior profile are not appended.

When verify=f is specified, the behavior profile is not validated at parse time. The profile is loaded at execution time, which is useful when the profile is still being built.

Examples

Match records against a behavior profile
```
json "[{'src_ip': '192.0.2.1'}, {'src_ip': '198.51.100.5'}]"
| matchbehavior guid=550e8400-e29b-41d4-a716-446655440000
```
Matches input records against the behavior profile with the specified GUID using its key fields, and appends the profile's value fields to matched records.

Filter out matched records

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

Outputs only records not included in the behavior profile.

Match without validation
```
json "[{'src_ip': '192.0.2.1'}]"
| matchbehavior guid=550e8400-e29b-41d4-a716-446655440000 verify=f
```
Skips validation of the behavior profile's existence and performs matching. Useful when the profile is still being built.