field-path-notation.md.erb

---
title: Field Path Notation
description: "Vector's field path notation allows you to reference field values with a simple string syntax."
---

Throughout Vector's configuration you'll notice that certain options take field
paths as values, such as the
[`rename_fields` transform][docs.transforms.rename_fields]. In order to
referenxe nested, or array, values you can use Vector's field path notation.
This notation is not anything special, it simply uses `.` and `[<index>]` to
access nested and array values, respectively.

## Example

For this example let's use the following `log` event:

```json
{
  "timestamp": "2020-02-14T01:22:23.223Z",
  "application_id": 1,
  "message": "Hello world",
  "field.with.dot": "value",
  "ec2": {
    "instance_id": "abcd1234",
    "tags": ["tag1: value1", "tag2: value1"]
  }
}
```

We can access the values like so:

* `"application_id"` - Accesses the root level `application_id` field.
* `"ec2.instance_id"` - Accesses the child `instance_id` field.
* `"ec2.tags[0]"` - Accesses the first value in the child `tags` field.

## Syntax

### Root-level Values

Root-level values can be access by simply supplying the name of the field as
shown in the example above.

```text
field_name
```

### Nested Values

Nested values can be accessed by separating ancestor fields with the `.`
character:

```text
grandparent.parent.child
```

### Array Values

Array values can be access with the `[<index>]` syntax:

```text
field_name[0]
```

Accesses the _first_ value since it has an index of 0.

```text
parent.child[0]
```

Accesses the _first_ value of the nested `child` field.

### Escaping

The special characters `.`, `[`, and `]` can be escaped with a `\`:

```text
field\.with\.dots
```

The above name will be treated literally.

The `\` character, if used literally, must be escaped with a `\` as well.