Module vector_lookup::path

This module contains all of the logic for paths.

Paths can be thought of as similar to file paths (in an operating system) pointing to specific files inside of a directory. A Value is a data structure that can contain recursively nested fields. Paths allow referring to a specific field inside of a Value.

Example

Below is a sample Value. Different fields can be accessed with paths.

{
  "foo": {
      "bar": 1
   },
   "baz": ["a", "b", "c"]
}

path	value it points to
.foo.bar	1
.foo	{ "bar": 1 }
.	{ "foo" : { "bar" : 1 }, "baz" : ["a", "b", "c"] }
.baz[0]	"a"
.baz	["a", "b", "c"]

Traits

There are 2 main traits that define a path. Most functions that use a path for querying will require one of these traits, rather than a concrete type.

• ValuePath is a path that points to a field inside of a Value.
• TargetPath is a path that points to a field inside of a target. A target in VRL refers to the external data being processed by a VRL script. A target has two main sections that can be pointed to, event and metadata. TargetPath::prefix identifies the section, and TargetPath::value_path is a ValuePath pointing into that section.

Note that for performance reasons, since ValuePath and TargetPath require Clone, these traits are only implemented on types that are cheap to clone (usually references). That means when passing in a value (e.g. OwnedValuePath) into a function that requires impl ValuePath, it will generally need to be passed in as a reference.

Owned Paths

OwnedValuePath and OwnedTargetPath are pre-parsed paths. That means that accessing fields using an owned path is very fast. There is an upfront cost however, since owned paths are parsed when they are created, and the segments are heap allocated. Owned paths should be preferred if they can be created when performance isn’t as much of a concern (e.g. startup time) and they can be stored for re-use. Owned paths tend to be easier to work with since you can directly access / manipulate the segments that make up the path.

If a path is being created and will only be used once, it may make sense to use other types. For example here are two different ways to append a segment to a OwnedValuePath before querying a Value:

• Use OwnedValuePath::with_field_appended to create a new OwnedValuePath and use that. This method is preferred if the new path will be used multiple times and the path adjustment can be done in a non performance-critical part of the code (e.g. at startup).
• Use ValuePath::concat which con concatenate two ValuePath’s very efficiently without allocating on the heap.

To convert a string into an owned path, use either parse_value_path or parse_target_path.

String Paths

ValuePath and TargetPath are implemented for &str. That means a raw / unparsed string can be used as a path. This use is discouraged, and may be removed in the future. It mostly exists for backwards compatibility in places where String paths are used instead of owned paths. Using string paths is slightly slower than using an owned path. It’s still very fast but it is easy to introduce bugs since some compile-time type information is missing - such as whether it is a target vs value path, or if the entire string is meant to be treated as a single segment vs being parsed as a path.

Macros

Several macros exist to make creating paths easier. These are used if the structure of the path being created is already known. The macros do not parse paths. Use parse_value_path or parse_target_path instead if the path needs to be parsed.

You need to pass in each segment into the macro as separate arguments. A single argument is treated as a single segment. This is true for all of the path macros.

For example, owned_value_path! can be used to easily created owned paths.

• owned_value_path!("foo.bar", "x") will create a path with two segments. Equivalent to ."foo.bar".x

Structs

• BorrowedTargetPath
• BorrowedValuePath
• OwnedTargetPath
  An owned path that contains a target (pointing to either an Event or Metadata)
• OwnedValuePath
  A lookup path.
• PathConcat

Enums

• BorrowedSegment
• OwnedSegment
• PathParseError
• PathPrefix

Traits

• TargetPath
• ValuePath
  A path is simply the data describing how to look up a field from a value. This should only be implemented for types that are very cheap to clone, such as references.

Functions

• parse_target_path
  Used to pre-parse a path. The return value (when borrowed) implements Path so it can be used directly. This parses a target path, which is a path that contains a target prefix.
• parse_value_path
  Used to pre-parse a path. The return value (when borrowed) implements Path so it can be used directly. This parses a value path, which is a path without a target prefix.