json-query 0,1,0,0 npm

Retrieves values from JSON objects for data binding


Retrieves values from JSON objects for data binding. Offers params, nested queries, deep queries, custom reduce/filter functions and simple boolean logic.

Install via npm

$ npm install json-query


var jsonQuery = require('json-query')

jsonQuery(query, options)

Specify a query and what to query. Returns an object that describes the result of the query.

var data = {
  people: [
    {name: 'Matt', country: 'NZ'},
    {name: 'Pete', country: 'AU'},
    {name: 'Mikey', country: 'NZ'}

jsonQuery('people[country=NZ].name', {
  data: data
}) //=> {value: 'Matt', parents: [...], key: 0} ... etc


  • data or rootContext: The main object to query.
  • source or context (optional): The current object we’re interested in. Accessed in query with ..
  • parent (optional): An additional context for looking further up the tree. Accessed by ...
  • locals: Specify an object containing helper functions. Accessed by ':filterName'. Expects function(input, args...) with this set to original passed in options.
  • globals: Falls back to globals when no local function found.
  • force (optional): Specify an object to be returned from the query if the query fails. It will be saved into the place the query expected the object to be.
  • allowRegexp (optional): Enable the ~ operator. Before enabling regexp match to anyone, consider the user defined regular expression security concerns.


Queries are strings that describe an object or value to pluck out, or manipulate from the context object. The syntax is a little bit CSS, a little bit JS, but pretty powerful.

Accessing properties (dot notation)


Array accessors


Array pluck

people.name => return all the names of people

Get all values of a lookup


Array filter

By default only the first matching item will be returned:


But if you add an asterisk (*), all matching items will be returned:


You can use comparative operators:


Or use boolean logic:

people[* rating >= 3 & starred = true]

If options.enableRegexp is enabled, you can use the ~ operator to match RegExp:


You can also negate any of the above examples by adding a ! before the = or ~:


Or syntax


Deep queries

Search through multiple levels of Objects/Arrays using [**]:

var data = {
  grouped_people: {
    'friends': [
      {name: 'Steve', country: 'NZ'},
      {name: 'Jane', country: 'US'},
      {name: 'Mike', country: 'AU'},
      {name: 'Mary', country: 'NZ'},
    'enemies': [
      {name: 'Evil Steve', country: 'AU'}
      {name: 'Betty', country: 'NZ'},

var result = jsonQuery('grouped_people[**][*country=NZ]', {data: data}).value

The result will be:

  {name: 'Steve', country: 'NZ'},
  {name: 'Mary', country: 'NZ'},
  {name: 'Betty', country: 'NZ'}

Inner queries

var data = {
  page: {
    id: 'page_1',
    title: 'Test'
  comments_lookup: {
    'page_1': [
      {id: 'comment_1', parent_id: 'page_1', content: "I am a comment"}

// get the comments that match page's id
jsonQuery('comments_lookup[{page.id}]', {data: data})

Local functions (helpers)

Allows you to hack the query system to do just about anything.

Some nicely contrived examples:

var helpers = {
  greetingName: function(input){
    if (input.known_as){
      return input.known_as
    } else {
      return input.name
  and: function(inputA, inputB){
    return inputA && inputB
  text: function(input, text){
    return text
  then: function(input, thenValue, elseValue){
    if (input){
      return thenValue
    } else {
      return elseValue

var data = {
  is_fullscreen: true,
  is_playing: false,
  user: {
    name: "Matthew McKegg",
    known_as: "Matt"

jsonQuery('user:greetingName', {
  data: data, locals: helpers
}).value //=> "Matt"

jsonQuery(['is_fullscreen:and({is_playing}):then(?, ?)', "Playing big!", "Not so much"], {
  data: data, locals: helpers
}).value //=> "Not so much"

jsonQuery(':text(This displays text cos we made it so)', {
  locals: helpers
}).value //=> "This displays text cos we made it so"

Or you could add a select helper:

jsonQuery('people:select(name, country)', {
  data: data,
  locals: {
    select: function (input) {
      if (Array.isArray(input)) {
        var keys = [].slice.call(arguments, 1)
        return input.map(function (item) {
          return Object.keys(item).reduce(function (result, key) {
            if (~keys.indexOf(key)) {
              result[key] = item[key]
            return result
          }, {})

You can also use helper functions inside array filtering:

jsonQuery('people[*:recentlyUpdated]', {
  data: data,
  locals: {
    recentlyUpdated: function (item) {
      return item.updatedAt < Date.now() - (30 * 24 * 60 * 60 * 1000)


Specifying context (data, source, and parent options) is good for databinding and working on a specific object and still keeping the big picture available.

var data = {
  styles: {
    bold: 'font-weight:strong',
    red: 'color: red'
  paragraphs: [
    {content: "I am a red paragraph", style: 'red'},
    {content: "I am a bold paragraph", style: 'bold'},

var pageHtml = ''
  var style = jsonQuery('styles[{.style}]', {data: data, source: paragraph}).value
  var content = jsonQuery('.content', data: data, source: paragraph) // pretty pointless :)
  pageHtml += "<p style='" + style "'>" + content + "</p>"

Query Params

Params can be specified by passing in an array with the first param the query (with ? params) and subsequent params.

jsonQuery(['people[country=?]', 'NZ'])



Related Repositories



Prettify/Minify/Query/Goto/Validate/Lint JSON plugin for Sublime Text 2 & 3 ...



Retrieves values from JSON objects for data binding ...



A library to query and update JSON data in Scala. ...



JsQuery – json query language with GIN indexing support ...



JSON query and transformation language ...

Top Contributors

mmckegg reggi aurium jevakallio Zearin


package version
dev ava ^0.14.0
es5-shim ~2.1.0
tape *


-   v2.2.0 zip tar
-   v2.1.1 zip tar
-   v2.1.0 zip tar
-   v2.0.2 zip tar
-   v2.0.1 zip tar
-   v2.0.0 zip tar
-   v1.8.0 zip tar
-   v1.7.0 zip tar
-   v1.6.0 zip tar
-   v1.5.0 zip tar
-   v1.4.0 zip tar
-   v1.3.1 zip tar
-   v1.3.0 zip tar
-   v1.2.0 zip tar
-   v1.1.0 zip tar
-   v1.0.0 zip tar
-   v0.6.0 zip tar
-   v0.5.0 zip tar
-   v0.4.0 zip tar
-   v0.3.3 zip tar
-   v0.3.2 zip tar
-   v0.3.1 zip tar
-   v0.3.0 zip tar
-   v0.2.1 zip tar
-   v0.2.0 zip tar
-   v0.1.2 zip tar