Skip to main content

Dot Expander

Transform Elastic Compatible

Synopsis​

Expands fields containing dots in their names into nested objects.

Schema​

dot_expander:
  - field: <ident>
  - path: <string>
  - description: <text>
  - if: <script>
  - ignore_failure: <boolean>
  - on_failure: <processor[]>
  - on_success: <processor[]>
  - tag: <string>

Configuration​

FieldRequiredDefaultDescription
fieldY-Field containing dot-separated names to expand
pathN-Target location for expanded structure
descriptionN-Explanatory note
ifN-Conditional expression
ignore_failureNfalseContinue processing on errors
on_failureN-Processors to run on failure
on_successN-Processors to run on success
tagN-Identifier for logging

Details​

Functionality​

The Dot Expander processor converts flat field names with dot notation into nested object structures. This is particularly useful for:

  • Transforming flattened data into hierarchical formats
  • Preparing data for nested processing
  • Standardizing field structures across different data sources

Key Behaviors​

  • Automatically creates intermediate objects as needed
  • Preserves original field values
  • Removes the original dot-separated field
  • Supports custom target paths for expanded structures

Use Cases​

  • Normalizing log data
  • Preparing data for specific processing pipelines
  • Converting flat configurations to nested formats
  • Improving data readability and structure

Examples​

Basic Field Expansion​

Expand a dotted field into nested objects...

{
  "foo.bar.baz": 123
}
dot_expander:
  - field: foo.bar.baz

creates a nested structure:

{
  "foo": {
    "bar": {
      "baz": 123
    }
  }
}

Custom Path Expansion​

Place expanded structure at specific path...

{
  "source.field.value": 123
}
dot_expander:
  - field: source.field.value
  - path: target

creates structure at specified location:

{
  "target": {
    "source": {
      "field": {
        "value": 123
      }
    }
  }
}

Conditional Expansion​

Expand only when condition is met...

{
  "foo.bar.baz": 123,
  "condition": true
}
dot_expander:
  - field: foo.bar.baz
  - if: ctx.condition == true

expands when condition is true:

{
  "condition": true,
  "foo": {
    "bar": {
      "baz": 123
    }
  }
}

Error Handling​

When field doesn't contain dots...

{
  "foo": 123
}
dot_expander:
  - field: foo
  - ignore_failure: true
  - on_failure:
      - set:
          field: error
          value: "No dots in field name"

handles error gracefully:

{
  "foo": 123,
  "error": "No dots in field name"
}
note
  • The processor maintains the original data types during expansion
  • Intermediate objects are created automatically
  • The original dot-separated field is removed
warning
  • The field must contain at least one dot
  • Nested expansions create complex object structures
  • Be cautious with deeply nested fields to avoid performance issues