Arguments

Arguments are a way to filter elements inside an array. They are defined by a pair of parentheses () after the field name and can contain one or more conditions separated by commas ,.

Basic examples

As an example, consider this simple JSON:

input.json

{
  "customers": [
    {
      "name": "Alice",
      "age": 16
    },
    {
      "name": "Bob",
      "age": 24
    },
    {
      "name": "Charlie",
      "age": 35
    }
  ]
}

If we want to filter the customer array to only get the people who are at least 18 years old, we can use the following query:

query.gq

{
  customers(age>=18)
}

output.json

{
  "customers": [
    {
      "name": "Alice",
      "age": 25
    },
    {
      "name": "Bob",
      "age": 30
    }
  ]
}

Or if we have a log export like this:

input.json

{
  "logs": [
    {
      "ts": "2022-01-01T10:00:00Z",
      "message": "[INFO] Message 1"
    },
    {
      "ts": "2022-01-01T11:00:00Z",
      "message": "[ERROR] Message 2"
    },
    {
      "ts": "2022-01-01T12:00:00Z",
      "message": "[INFO] Message 3"
    }
  ]
}

And we want to filter the logs to only get the ones with level ERROR, we can use the following query:

query.gq

{
  logs(message~"^\\[ERROR\\].*")
}

output.json

{
  "logs": [
    {
      "ts": "2022-01-01T11:00:00Z",
      "message": "[ERROR] Message 2"
    }
  ]
}

Conjunctive conditions

Right now, the conditions inside the arguments are combined using a logical AND. This means that all the conditions must be met in order to obtain the element. Let’s see an example with a product list:

input.json

{
  "products": [
    {
      "name": "Product 1",
      "type": "A",
      "price": 100
    },
    {
      "name": "Product 2",
      "type": "B",
      "price": 200
    },
    {
      "name": "Product 3",
      "type": "C",
      "price": 300
    }
  ]
}

We can use the following query if we want the products with a price lower than 300 and of type B:

query.gq

products(price<300, type="B")

output.json

[
  {
    "name": "Product 2",
    "type": "B",
    "price": 200
  }
]

Note

The logical OR operator is not supported yet as it increases the complexity of the query language.
For the moment, you can divide your conditions into multiple queries and use the aliasing to avoid key conflicts.

Supported operations

The follwing table shows all the operations that can be used inside the arguments:

Operation	Description	Suppoted types
=	Equals	any
!=	Not equals	any
~	Matches regex	string
!~	Does not match regex	string
>	Greater than	number
<	Less than	number
>=	Greater than or equals	number
<=	Less than or equals	number