JSONPath

https://hexdocs.pm/json_path/
Admin
JSONPath is an RFC-9535 compliant JSON Path evaluator for Elixir that parses and evaluates query...
Tokens:6,583
Snippets:57
Trust Score:9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example for paths!/2

Source: https://hexdocs.pm/json_path

An iex example showing paths!/2 returning the list of normalized paths directly.

```elixir
iex> JSONPath.paths!(["aba", "bbab", "bab"], "$[?match(@, 'b.b')]")
["$[2]"]
```

--------------------------------

### Example for value_paths/2

Source: https://hexdocs.pm/json_path

An iex example showing value_paths/2 returning a tuple with the node value and normalized path.

```elixir
iex> JSONPath.value_paths(["aba", "bbab", "bab"], "$[?match(@, 'b.b')]")
{:ok, [{"bab", "$[2]"}]}
```

--------------------------------

### Example for value_paths!/2

Source: https://hexdocs.pm/json_path

An iex example showing value_paths!/2 returning the list of {node_value, normalized_path} tuples directly.

```elixir
iex> JSONPath.value_paths!(["aba", "bbab", "bab"], "$[?match(@, 'b.b')]")
[{"bab", "$[2]"}]
```

--------------------------------

### Examples for paths/2

Source: https://hexdocs.pm/json_path

Two iex examples showing how paths/2 returns normalized paths for a match filter and a reverse slice.

```elixir
iex> JSONPath.paths(["aba", "bbab", "bab"], "$[?match(@, 'b.b')]")
{:ok, ["$[2]"]}
```

```elixir
iex> JSONPath.paths(%{"foo" => ["a", "b", "c", "d"]}, "$.foo[::-1]")
{:ok, ["$['foo'][3]", "$['foo'][2]", "$['foo'][1]", "$['foo'][0]"]}
```

--------------------------------

### values!/2 usage example

Source: https://hexdocs.pm/json_path

An example showing the direct return of values using the values!/2 function.

```elixir
iex> JSONPath.values!(%{"foo" => [1,2,3,4]}, "$.foo[?@ > 2]")
[3, 4]
```

--------------------------------

### values/2 usage examples

Source: https://hexdocs.pm/json_path

Examples demonstrating how to use values/2 with various JSON structures and query patterns, including successful matches and error handling.

```elixir
iex> JSONPath.values(["aba", "bbab", "bab"], "$[?match(@, 'b.b')]")
{:ok, ["bab"]}

iex> JSONPath.values(%{"foo" => ["a", "b", "c", "d"]}, "$.foo[::-1]")
{:ok, ["d", "c", "b", "a"]}

iex> JSONPath.values(%{"foo" => [1,2,3,4]}, "$.foo[?@ > 2]")
{:ok, [3, 4]}

iex> JSONPath.values(%{"foo" => %{"bar" => "baz"}}, "$[?length(@)]")
{:error, %JSONPath.Error{
  type: :invalid_expression,
  expression: "length(@)",
  message: "comparison operator expected"
  }
}
```

--------------------------------

### build!(query)

Source: https://hexdocs.pm/json_path

Same as build/1 but raises an exception in case of error.

```APIDOC
## build!(query)

### Description
Same as build/1 but raises an exception in case of error.

### Signature
@spec build!(String.t()) :: JSONPath.AST.t()

### Parameters
- **query** (String.t()) - Required - The JSONPath query string.

### Returns
- JSONPath.AST.t() on success
- Raises on error
```

--------------------------------

### build!(query)

Source: https://hexdocs.pm/json_path

Same as build/1 but raises in case of error.

```APIDOC
## build!(query)

### Description
Same as build/1 but raises in case of error.

### Parameters
- query (string) - Required - The JSON Path query string.

### Returns
- The built AST, or raises an error.

```

--------------------------------

### Build JSONPath query with build!/1

Source: https://hexdocs.pm/json_path

Same as build/1 but raises an error on failure.

```elixir
@spec build!(String.t()) :: JSONPath.AST.t()
```

--------------------------------

### build(query)

Source: https://hexdocs.pm/json_path

Builds a JSON Path query AST. Returns {:ok, ast} or {:error, JSONPath.Error.t()}.

```APIDOC
## build(query)

### Description
Builds a JSON Path query AST. Returns {:ok, ast} or {:error, JSONPath.Error.t()}.

### Parameters
- query (string) - Required - The JSON Path query string.

### Returns
- {:ok, ast} on success
- {:error, JSONPath.Error.t()} on failure

```

--------------------------------

### Build JSONPath query with build/1

Source: https://hexdocs.pm/json_path

Builds a JSON Path query AST. Prefer this for repeated queries to avoid redundant semantic checks.

```elixir
@spec build(String.t()) :: {:ok, JSONPath.AST.t()} | {:error, JSONPath.Error.t()}
```

--------------------------------

### build(query)

Source: https://hexdocs.pm/json_path

Builds a JSONPath query AST from a query string. Returns {:ok, ast} on success or {:error, error} on failure. Prefer this when running the same query multiple times to avoid repeated semantic checks.

```APIDOC
## build(query)

### Description
Builds a JSONPath query AST from a query string. Returns {:ok, ast} on success or {:error, error} on failure. Prefer this when running the same query multiple times to avoid repeated semantic checks.

### Signature
@spec build(String.t()) :: {:ok, JSONPath.AST.t()} | {:error, JSONPath.Error.t()}

### Parameters
- **query** (String.t()) - Required - The JSONPath query string.

### Returns
- {:ok, JSONPath.AST.t()} on success
- {:error, JSONPath.Error.t()} on failure
```

--------------------------------

### paths!(document, query)

Source: https://hexdocs.pm/json_path

Same as paths/2 but returns the list of normalized paths or raises an error.

```APIDOC
## paths!(document, query)

### Description
Same as paths/2 but returns the list of normalized paths or raises an error.

### Parameters
- document (JSON value) - Required - The JSON value to evaluate.
- query (string or AST) - Required - The query string or parsed AST.

### Returns
- The list of normalized paths, or raises an error.

```

--------------------------------

### paths!/2

Source: https://hexdocs.pm/json_path

Same as paths/2 but returns the list of normalized paths or raises an error.

```APIDOC
## paths!/2

### Description
Same as `paths/2` but returns the list of normalized paths or raises an error.

### Function Signature
```elixir
@spec paths!(json(), String.t() | JSONPath.AST.t()) :: [String.t()]
```

### Parameters
- **document** (json()) - Required - The JSON value to evaluate.
- **query** (String.t() | JSONPath.AST.t()) - Required - The query string or parsed AST.

### Returns
- **[String.t()]** - A list of normalized paths.

### Examples
```elixir
iex> JSONPath.paths!(["aba", "bbab", "bab"], "$[?match(@, 'b.b')]")
["$[2]"]
```
```

--------------------------------

### value_paths!/2

Source: https://hexdocs.pm/json_path

Same as value_paths/2 but returns the list of two-element tuples or raises an error.

```APIDOC
## value_paths!/2

### Description
Same as `value_paths/2` but returns the list of two-element tuple `{node_value, normalized_path}` or raises an error.

### Function Signature
```elixir
@spec value_paths!(json(), String.t() | JSONPath.AST.t()) :: [{json(), String.t()}]
```

### Parameters
- **document** (json()) - Required - The JSON value to evaluate.
- **query** (String.t() | JSONPath.AST.t()) - Required - The query string or parsed AST.

### Returns
- **[{json(), String.t()}]** - A list of two-element tuples containing the node value and normalized path.

### Examples
```elixir
iex> JSONPath.value_paths!(["aba", "bbab", "bab"], "$[?match(@, 'b.b')]")
[{"bab", "$[2]"}]
```
```

--------------------------------

### evaluate!(document, query, returning \ :values)

Source: https://hexdocs.pm/json_path

Same as evaluate/2 but raises in case of error. Deprecated: use JSONPath.values!/2, JSONPath.paths!/2, or JSONPath.value_paths!/2.

```APIDOC
## evaluate!(document, query, returning \ :values)

### Description
Same as evaluate/2 but raises in case of error. Deprecated: use JSONPath.values!/2, JSONPath.paths!/2, or JSONPath.value_paths!/2.

### Signature
@spec evaluate!(json(), String.t() | JSONPath.AST.t(), returning()) :: [json()]

### Parameters
- **document** (json()) - Required - The JSON value to evaluate.
- **query** (String.t() | JSONPath.AST.t()) - Required - The JSONPath query string or parsed AST.
- **returning** (returning()) - Optional - Controls the results type. Defaults to :values. Possible values: :values, :paths, :values_and_paths.

### Returns
- [json()] on success, where the results type depends on returning:
  - :values - List of node values
  - :paths - List of normalized paths
  - :values_and_paths - List of tuples {value, normalized_path}
- Raises on error
```

--------------------------------

### values!(document, query)

Source: https://hexdocs.pm/json_path

Same as values/2 but returns the list of node values or raises an error.

```APIDOC
## values!(document, query)

### Description
Same as values/2 but returns the list of node values or raises an error.

### Function Signature
```elixir
@spec values!(json(), String.t() | JSONPath.AST.t()) :: [json()]
```

### Parameters
- **document** (json()) - Required - The JSON value to evaluate.
- **query** (String.t() | JSONPath.AST.t()) - Required - The JSONPath query string or parsed AST.

### Return Value
- `[json()]` - The list of matching node values.

### Examples
```elixir
iex> JSONPath.values!(%{"foo" => [1,2,3,4]}, "$.foo[?@ > 2]")
[3, 4]
```
```

--------------------------------

### values!(document, query)

Source: https://hexdocs.pm/json_path

Same as values/2 but returns the list of nodes values or raises an error.

```APIDOC
## values!(document, query)

### Description
Same as values/2 but returns the list of nodes values or raises an error.

### Parameters
- document (JSON value) - Required - The JSON value to evaluate.
- query (string or AST) - Required - The query string or parsed AST.

### Returns
- The list of nodes values, or raises an error.

```

--------------------------------

### Define returning() type

Source: https://hexdocs.pm/json_path

Specifies the return format for query results.

```elixir
@type returning() :: :values | :paths | :values_and_paths
```

--------------------------------

### evaluate!(document, query, returning \ :values)

Source: https://hexdocs.pm/json_path

Same as evaluate/2 but raises in case of error. Deprecated.

```APIDOC
## evaluate!(document, query, returning \ :values)

### Description
Same as evaluate/2 but raises in case of error. Deprecated.

### Parameters
- document (JSON value) - Required - The JSON value to evaluate.
- query (string or AST) - Required - The query string or parsed AST.
- returning (atom) - Optional - Defaults to :values.

### Returns
- The results, or raises an error.

```

--------------------------------

### value_paths!(document, query)

Source: https://hexdocs.pm/json_path

Same as value_paths/2 but returns the list of two-element tuple {node_value, normalized_path} or raises an error.

```APIDOC
## value_paths!(document, query)

### Description
Same as value_paths/2 but returns the list of two-element tuple {node_value, normalized_path} or raises an error.

### Parameters
- document (JSON value) - Required - The JSON value to evaluate.
- query (string or AST) - Required - The query string or parsed AST.

### Returns
- The list of two-element tuple {node_value, normalized_path}, or raises an error.

```

--------------------------------

### Evaluate JSONPath with evaluate!/3

Source: https://hexdocs.pm/json_path

Same as evaluate/3 but raises an error on failure. This function is deprecated.

```elixir
@spec evaluate!(json(), String.t() | JSONPath.AST.t(), returning()) :: [json()]
```

--------------------------------

### Spec for paths!/2

Source: https://hexdocs.pm/json_path

Specification for the paths!/2 function, which returns a list of normalized paths or raises an error.

```elixir
@spec paths!(json(), String.t() | JSONPath.AST.t()) :: [String.t()]
```

--------------------------------

### paths(document, query)

Source: https://hexdocs.pm/json_path

Evaluates a JSON value against the given query string or parsed AST. Returns a result tuple containing the list of normalized paths.

```APIDOC
## paths(document, query)

### Description
Evaluates a JSON value against the given query string or parsed AST. Returns a result tuple containing the list of normalized paths.

### Parameters
- document (JSON value) - Required - The JSON value to evaluate.
- query (string or AST) - Required - The query string or parsed AST.

### Returns
- A result tuple containing the list of normalized paths.

```

--------------------------------

### paths/2

Source: https://hexdocs.pm/json_path

Evaluates a JSON value against a query string or parsed AST and returns a tuple with a list of normalized paths or an error.

```APIDOC
## paths/2

### Description
Evaluates a JSON value against the given query string or parsed AST. Returns a result tuple containing the list of normalized paths.

### Function Signature
```elixir
@spec paths(json(), String.t() | JSONPath.AST.t()) ::
  {:ok, [String.t()]} | {:error, JSONPath.Error.t()}
```

### Parameters
- **document** (json()) - Required - The JSON value to evaluate.
- **query** (String.t() | JSONPath.AST.t()) - Required - The query string or parsed AST.

### Returns
- **{:ok, [String.t()]}** - A tuple with an :ok atom and a list of normalized paths.
- **{:error, JSONPath.Error.t()}** - A tuple with an :error atom and an error struct.

### Examples
```elixir
iex> JSONPath.paths(["aba", "bbab", "bab"], "$[?match(@, 'b.b')]")
{:ok, ["$[2]"]}

iex> JSONPath.paths(%{"foo" => ["a", "b", "c", "d"]}, "$.foo[::-1]")
{:ok, ["$['foo'][3]", "$['foo'][2]", "$['foo'][1]", "$['foo'][0]"]}
```
```

--------------------------------

### Spec for value_paths!/2

Source: https://hexdocs.pm/json_path

Specification for the value_paths!/2 function, which returns a list of {node_value, normalized_path} tuples or raises an error.

```elixir
@spec value_paths!(json(), String.t() | JSONPath.AST.t()) :: [{json(), String.t()}]
```

--------------------------------

### Spec for paths/2

Source: https://hexdocs.pm/json_path

Specification for the paths/2 function, which takes a JSON value and a query string or parsed AST, returning a tuple with a list of normalized paths or an error.

```elixir
@spec paths(json(), String.t() | JSONPath.AST.t()) ::
  {:ok, [String.t()]} | {:error, JSONPath.Error.t()}
```

--------------------------------

### Define json() type

Source: https://hexdocs.pm/json_path

Represents the structure of valid JSON data.

```elixir
@type json() ::
  nil
  | number()
  | String.t()
  | boolean()
  | [json()]
  | %{required(String.t()) => json()}
```

--------------------------------

### Spec for value_paths/2

Source: https://hexdocs.pm/json_path

Specification for the value_paths/2 function, which returns a tuple with a list of {node_value, normalized_path} tuples or an error.

```elixir
@spec value_paths(json(), String.t() | JSONPath.AST.t()) ::
  {:ok, [{json(), String.t()}]} | {:error, JSONPath.Error.t()}
```

--------------------------------

### values/2 function specification

Source: https://hexdocs.pm/json_path

The specification for the values/2 function, which accepts a JSON document and a query string or AST, returning a tuple.

```elixir
@spec values(json(), String.t() | JSONPath.AST.t()) ::
  {:ok, [json()]} | {:error, JSONPath.Error.t()}
```

--------------------------------

### values(document, query)

Source: https://hexdocs.pm/json_path

Evaluates a JSON value against the given query string or parsed AST. Returns a result tuple containing the list of matching node values.

```APIDOC
## values(document, query)

### Description
Evaluates a JSON value against the given query string or parsed AST. Returns a result tuple containing the list of matching node values.

### Parameters
- document (JSON value) - Required - The JSON value to evaluate.
- query (string or AST) - Required - The query string or parsed AST.

### Returns
- A result tuple containing the list of matching node values.

```

--------------------------------

### value_paths/2

Source: https://hexdocs.pm/json_path

Evaluates a JSON value against a query string or parsed AST and returns a tuple with a list of {node_value, normalized_path} tuples or an error.

```APIDOC
## value_paths/2

### Description
Evaluates a JSON value against the given query string or parsed AST. Returns a result tuple containing two-element tuples of `{node_value, normalized_path}`.

### Function Signature
```elixir
@spec value_paths(json(), String.t() | JSONPath.AST.t()) ::
  {:ok, [{json(), String.t()}]} | {:error, JSONPath.Error.t()}
```

### Parameters
- **document** (json()) - Required - The JSON value to evaluate.
- **query** (String.t() | JSONPath.AST.t()) - Required - The query string or parsed AST.

### Returns
- **{:ok, [{json(), String.t()}]}** - A tuple with an :ok atom and a list of two-element tuples containing the node value and normalized path.
- **{:error, JSONPath.Error.t()}** - A tuple with an :error atom and an error struct.

### Examples
```elixir
iex> JSONPath.value_paths(["aba", "bbab", "bab"], "$[?match(@, 'b.b')]")
{:ok, [{"bab", "$[2]"}]}
```
```

--------------------------------

### evaluate(document, query, returning \ :values)

Source: https://hexdocs.pm/json_path

Evaluates a JSON value against a query string or parsed AST. Returns {:ok, results} or {:error, error}. The results type is controlled by the returning argument. Deprecated: use JSONPath.values/2, JSONPath.paths/2, or JSONPath.value_paths/2.

```APIDOC
## evaluate(document, query, returning \ :values)

### Description
Evaluates a JSON value against a query string or parsed AST. Returns {:ok, results} or {:error, error}. The results type is controlled by the returning argument. Deprecated: use JSONPath.values/2, JSONPath.paths/2, or JSONPath.value_paths/2.

### Signature
@spec evaluate(json(), String.t() | JSONPath.AST.t(), returning()) :: {:ok, [json()]} | {:error, JSONPath.Error.t()}

### Parameters
- **document** (json()) - Required - The JSON value to evaluate.
- **query** (String.t() | JSONPath.AST.t()) - Required - The JSONPath query string or parsed AST.
- **returning** (returning()) - Optional - Controls the results type. Defaults to :values. Possible values: :values, :paths, :values_and_paths.

### Returns
- {:ok, [json()]} on success, where the results type depends on returning:
  - :values - List of node values
  - :paths - List of normalized paths
  - :values_and_paths - List of tuples {value, normalized_path}
- {:error, JSONPath.Error.t()} on failure
```

--------------------------------

### values(document, query)

Source: https://hexdocs.pm/json_path

Evaluates a JSON value against the given query string or parsed AST. Returns a result tuple containing the list of matching node values or an error.

```APIDOC
## values(document, query)

### Description
Evaluates a JSON value against the given query string or parsed AST. Returns a result tuple containing the list of matching node values or an error.

### Function Signature
```elixir
@spec values(json(), String.t() | JSONPath.AST.t()) ::
  {:ok, [json()]} | {:error, JSONPath.Error.t()}
```

### Parameters
- **document** (json()) - Required - The JSON value to evaluate.
- **query** (String.t() | JSONPath.AST.t()) - Required - The JSONPath query string or parsed AST.

### Return Value
- `{:ok, [json()]}` - A tuple with `:ok` and the list of matching node values.
- `{:error, JSONPath.Error.t()}` - A tuple with `:error` and an error struct.

### Examples
```elixir
iex> JSONPath.values(["aba", "bbab", "bab"], "$[?match(@, 'b.b')]")
{:ok, ["bab"]}

iex> JSONPath.values(%{"foo" => ["a", "b", "c", "d"]}, "$.foo[::-1]")
{:ok, ["d", "c", "b", "a"]}

iex> JSONPath.values(%{"foo" => [1,2,3,4]}, "$.foo[?@ > 2]")
{:ok, [3, 4]}

iex> JSONPath.values(%{"foo" => %{"bar" => "baz"}}, "$[?length(@)]")
{:error, %JSONPath.Error{
  type: :invalid_expression,
  expression: "length(@)",
  message: "comparison operator expected"
  }
}
```
```

--------------------------------

### values!/2 function specification

Source: https://hexdocs.pm/json_path

The specification for the values!/2 function, which returns the list of node values or raises an error.

```elixir
@spec values!(json(), String.t() | JSONPath.AST.t()) :: [json()]
```

--------------------------------

### Evaluate JSONPath with evaluate/3

Source: https://hexdocs.pm/json_path

Evaluates a JSON document against a query. This function is deprecated in favor of specific value/path functions.

```elixir
@spec evaluate(json(), String.t() | JSONPath.AST.t(), returning()) ::
  {:ok, [json()]} | {:error, JSONPath.Error.t()}
```

--------------------------------

### evaluate(document, query, returning \ :values)

Source: https://hexdocs.pm/json_path

Evaluates a JSON value against the given query string or parsed AST. Returns an {:ok, results} or {:error, JSONPath.Error.t()} tuple. Deprecated.

```APIDOC
## evaluate(document, query, returning \ :values)

### Description
Evaluates a JSON value against the given query string or parsed AST. Returns an {:ok, results} or {:error, JSONPath.Error.t()} tuple. Deprecated.

### Parameters
- document (JSON value) - Required - The JSON value to evaluate.
- query (string or AST) - Required - The query string or parsed AST.
- returning (atom) - Optional - Defaults to :values.

### Returns
- {:ok, results} on success
- {:error, JSONPath.Error.t()} on failure

```

--------------------------------

### value_paths(document, query)

Source: https://hexdocs.pm/json_path

Evaluates a JSON value against the given query string or parsed AST. Returns a result tuple containing two-element tuples of {node_value, normalized_path}.

```APIDOC
## value_paths(document, query)

### Description
Evaluates a JSON value against the given query string or parsed AST. Returns a result tuple containing two-element tuples of {node_value, normalized_path}.

### Parameters
- document (JSON value) - Required - The JSON value to evaluate.
- query (string or AST) - Required - The query string or parsed AST.

### Returns
- A result tuple containing two-element tuples of {node_value, normalized_path}.

```
Tokens:
Raw