jpq  

A JSONPath command line tool to extract values from a JSON value.

Usage

jpq [--arg <name> <value>] [--argjson <name> <value>]
    [--color <auto | always | never | unless-compact>] [--compact-output]
    <JSONPath expression> [filename]

The JSONPath expression argument is a RFC 9535 JSONPath expression. The extracted result is printed on standard output.

Examples

The authors of all books in the store:

$ jpq '$.store.book[*].author' test-data/rfc9535-fig1.json
[
  "Nigel Rees",
  "Evelyn Waugh",
  "Herman Melville",
  "J. R. R. Tolkien"
]

all books cheaper than 10:

$ jpq --argjson max 10 '$..book[?@.price<var("max")]' test-data/rfc9535-fig1.json
[
  {
    "category": "reference",
    "author": "Nigel Rees",
    "title": "Sayings of the Century",
    "price": 8.95
  },
  {
    "category": "fiction",
    "author": "Herman Melville",
    "title": "Moby Dick",
    "isbn": "0-553-21311-3",
    "price": 8.99
   }
]

Overview of JSONPath Syntax

This is copied from RFC 9535 JSONPath: Query Expressions for JSON

• $: root node identifier
• @: current node identifier (valid only within filter selectors)
• [<selectors>]: child segment: selects zero or more children of a node
• .name: shorthand for ['name']
• .*: shorthand for [*]
• ..⁠[<selectors>]: descendant segment: selects zero or more descendants of a node
• ..name: shorthand for ..['name']
• ..*: shorthand for ..[*]
• 'name': name selector: selects a named child of an object
• *: wildcard selector: selects all children of a node
• 3: index selector: selects an indexed child of an array (from 0)
• 0:100:5: array slice selector: start:end:step for arrays
• ?<logical-expr>: filter selector: selects particular children using a logical expression
• length(@.foo): function extension: invokes a function in a filter expression

Installation

You need a Rust compiler, see https://www.rust-lang.org/tools/install if you do not yet have one. The minimum Rust compiler version supported is 1.80.0.

Then just run

$ cargo install jpq

This installs jpq under ~/.cargo/bin. This should be in your PATH so just typing jpq will run it; otherwise you'll need to type its whole path: ~/.cargo/bin/jpq.

Changes

0.1.4

• Support standard function extensions match and search.

0.1.3

• Colorize output,
• Add --color <when> argument to force color on or off,
• Add --arg <name> <value> and --argjson <name> <value> options, and var(...) function extension to access it,
• Add --compact-output option,
• support reading the JSON value from standard input.

0.1.2

• use miette for user friendly error messages.

0.1.1

• Change underlying JSONPath library to serde_json_xpath for better support of RFC 9535,