Skip to contents

JSONpath, JMESpath, or JSONpointer query of JSON / NDJSON documents

Source: R/paths_and_pointer.R
paths_and_pointer.Rd

jsonpath() executes a query against a JSON string or vector NDJSON entries using the 'JSONpath' specification.

jmespath() executes a query against a JSON string using the 'JMESpath' specification.

jsonpointer() extracts an element from a JSON string using the 'JSON pointer' specification.

Usage

jsonpath(data, path, object_names = "asis", as = "string", ...)

jmespath(data, path, object_names = "asis", as = "string", ...)

jsonpointer(data, path, object_names = "asis", as = "string", ...)

Arguments

data

a character() JSON string or NDJSON records, or the name of a file or URL containing JSON or NDJSON, or an R object parsed to a JSON string using jsonlite::toJSON().

path

character(1) JSONpointer, JSONpath or JMESpath query string.

object_names

character(1) order data object elements "asis" (default) or "sort" before filtering on path.

as

character(1) return type. "string" returns a single JSON string; "R" returns an R object following the rules outlined for as_r().

...

arguments for parsing NDJSON, or passed to jsonlite::toJSON when data is not character-valued. For NDJSON,

  • Use n_records = 2 to parse just the first two records of the NDJSON document.

  • Use verbose = TRUE to obtain a progress bar when reading from a connection (file or URL). Requires the cli package.

As an example for use with jsonlite::toJSON()

  • use auto_unbox = TRUE to automatically 'unbox' vectors of length 1 to JSON scalar values.

Value

jsonpath(), jmespath() and jsonpointer() return a character(1) JSON string (as = "string", default) or R

object (as = "R") representing the result of the query.

Examples

json <- '{
  "locations": [
    {"name": "Seattle", "state": "WA"},
    {"name": "New York", "state": "NY"},
    {"name": "Bellevue", "state": "WA"},
    {"name": "Olympia", "state": "WA"}
  ]
 }'

## return a JSON string
jsonpath(json, "$..name") |>
    cat("\n")
#> ["Seattle","New York","Bellevue","Olympia"] 

## return an R object
jsonpath(json, "$..name", as = "R")
#> [1] "Seattle"  "New York" "Bellevue" "Olympia" 

## create a list with state and name as scalar vectors
lst <- jsonlite::fromJSON(json, simplifyVector = FALSE)

## objects other than scalar character vectors are automatically
## coerced to JSON; use `auto_unbox = TRUE` to represent R scalar
## vectors in the object as JSON scalar vectors
jsonpath(lst, "$..name", auto_unbox = TRUE) |>
    cat("\n")
#> ["Seattle","New York","Bellevue","Olympia"] 

## a scalar character vector like "Seattle" is not valid JSON...
try(jsonpath("Seattle", "$"))
#> Error : JSON syntax_error at line 1 and column 1
## ...but a double-quoted string is
jsonpath('"Seattle"', "$")
#> [1] "[\"Seattle\"]"

## use I("Seattle") to coerce to a JSON object ["Seattle"]
jsonpath(I("Seattle"), "$[0]")      |> cat("\n")
#> ["Seattle"] 

## different ordering of object names -- 'asis' (default) or 'sort'
json_obj <- '{"b": "1", "a": "2"}'
jsonpath(json_obj, "$")           |> cat("\n")
#> [{"b":"1","a":"2"}] 
jsonpath(json_obj, "$.*")         |> cat("\n")
#> ["1","2"] 
jsonpath(json_obj, "$", "sort")   |> cat("\n")
#> [{"a":"2","b":"1"}] 
jsonpath(json_obj, "$.*", "sort") |> cat("\n")
#> ["2","1"] 

path <- "locations[?state == 'WA'].name | sort(@)"
jmespath(json, path) |>
    cat("\n")
#> ["Bellevue","Olympia","Seattle"] 

## original filter always fails, e.g., '["WA"] != 'WA'
jmespath(lst, path)  # empty result set, '[]'
#> [1] "[]"

## filter with unboxed state, and return unboxed name
jmespath(lst, "locations[?state[0] == 'WA'].name[0] | sort(@)") |>
    cat("\n")
#> ["Bellevue","Olympia","Seattle"] 

## automatically unbox scalar values when creating the JSON string
jmespath(lst, path, auto_unbox = TRUE) |>
    cat("\n")
#> ["Bellevue","Olympia","Seattle"] 

## jsonpointer 0-based arrays
jsonpointer(json, "/locations/0/name")
#> [1] "Seattle"

## document root "", sort selected element keys
jsonpointer('{"b": 0, "a": 1}', "", "sort", as = "R") |>
    str()
#> List of 2
#>  $ a: int 1
#>  $ b: int 0

## 'Key not found' -- path '/' searches for a 0-length key
try(jsonpointer('{"b": 0, "a": 1}', "/"))
#> Error : Key not found