Keep First

Text Processing Data Analysis

Synopsis

Keeps first N characters of strings or N elements of arrays.

Schema

- keep_first:
    field: <ident>
    count: <integer>
    target_field: <string>
    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 string or array to process
count	Y	-	Number of characters/elements to keep from the beginning
target_field	N	Same as field	Target field to store result
description	N	-	Explanatory note
if	N	-	Condition to run
ignore_failure	N	false	Continue processing if operation 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

Extracts the first N characters from string values or the first N elements from array values. This processor is useful for truncating data, creating prefixes, or limiting the size of fields for analysis or display purposes.

The processor handles both string and array data types automatically, applying the appropriate logic based on the input type. For strings, it counts Unicode characters properly, and for arrays, it preserves the original data types of the elements.

note

When processing strings, the processor counts Unicode characters correctly, not bytes. This ensures proper handling of international characters and emojis.

If the specified count is greater than the length of the string or array, the processor returns the entire original value without modification.

warning

Non-string and non-array values will cause the processor to fail unless ignore_failure is set to true. The processor cannot determine what "first N" means for other data types.

Examples

String Truncation

Keeping first 10 characters of a string...	{ "long_message": "This is a very long message that needs truncation" } - keep_first: field: long_message count: 10 target_field: preview
creates truncated preview:	{ "long_message": "This is a very long message that needs truncation", "preview": "This is a " }

Array Limitation

Keeping first 3 elements from an array...	{ "ip_addresses": [ "192.168.1.1", "192.168.1.2", "192.168.1.3", "192.168.1.4", "192.168.1.5" ] } - keep_first: field: ip_addresses count: 3 target_field: top_ips
keeps only first 3 elements:	{ "ip_addresses": [...], "top_ips": [ "192.168.1.1", "192.168.1.2", "192.168.1.3" ] }

In-Place Truncation

Truncating field value in place...	{ "user_id": "user_1234567890_extended_identifier" } - keep_first: field: user_id count: 12
overwrites original field:	{ "user_id": "user_1234567" }

Unicode String Handling

Properly handling Unicode characters...	{ "international_text": "Héllo Wörld 😀 Unicode Text" } - keep_first: field: international_text count: 8 target_field: prefix
counts Unicode characters correctly:	{ "international_text": "Héllo Wörld 😀 Unicode Text", "prefix": "Héllo Wö" }

Conditional Processing

Applying truncation based on conditions...	{ "error_message": "Database connection failed after multiple retry attempts", "truncate_errors": true } - keep_first: field: error_message count: 20 if: "logEntry.truncate_errors == true"
truncates when condition matches:	{ "error_message": "Database connection ", "truncate_errors": true }