# Select Query Reference

[](/en/reference/querying/json-query-language.html.md "View as Markdown") 

This document describes what the `select` parameter is and gives a few examples on how to use it. Refer to the [Query API](../../querying/query-api.html) for how to execute queries with POST.

The query has JSON syntax, and can be used with queries that are executed with HTTP POST. The `select` parameter is equivalent with YQL, and can be used instead of, but not together with YQL. Nor can it be used together with the `query` parameter.

## Structure

```
"select" : {
  "where" : {...},
  "grouping" : {...},
  "fields" : [...]
}
```

Example query searching for the term 'country' in the field 'title':

```
{
  "select": {
    "where": {
      "contains": ["title", "country"]
    }
  }
}
```

This query can be executed with `curl`:

```
curl -H "Content-Type: application/json" \
    --data "{ 'select': { 'where': { 'contains': ['default', 'country'] } } }" \
    http://localhost:8080/search/
```

### Where

Unlike the sql-like syntax in [YQL](../../querying/query-language.html), the _where_ queries are written in a tree syntax. By combining YQLs functions and arguments, queries equivalent with YQL can be written in JSON.

#### Formal structure

Functions are nested like this:

```
FUNCTION : {
  "children" : [argument, argument,..],
  "attributes" : {annotations}
{
```

or like this, by moving the `children`-key up, if attributes are not in use with the function:

```
FUNCTION : [
  argument,
  argument,
  ...
]
```

YQL is a regular language and is parsed into a query tree when parsed in Vespa. That tree can also be built with the `where` parameter in JSON.

Let's take a look at this yql: `select * from sources * where default contains foo and rank(a contains "A", b contains "B")`, which will create the following query tree:

![Example query tree](/assets/img/querytree.svg)

The tree above can be written with the 'where' parameter, like this:

```
{
  "and" : [
    { "contains" : ["default", "foo"] },
    { "rank" : [
      { "contains" : ["a", "A"] },
      { "contains" : ["b", "B"] }
    ]}
  ]
}
```

which is equivalent with the YQL.

### Fields

Available since Vespa 8.680.18 .

The `fields` parameter restricts which [summary fields](../../querying/document-summaries.html#selecting-summary-fields-in-yql) are included in each hit. It is a JSON array of field names, and is equivalent to the field list in a YQL `select` clause.

YQL: `select id, title from sources * where title contains 'madonna'`.

Equivalent JSON:

```
{
  "select": {
    "fields": ["id", "title"],
    "where": {
      "contains": ["title", "madonna"]
    }
  }
}
```

If `fields` is omitted or empty, all fields of the chosen [document summary class](../../querying/document-summaries.html) are returned.

### Grouping

One or more [grouping statements](../../querying/grouping.html) can be set as a JSON array in the `grouping` field. Each array item is a grouping statement represented as JSON where

- Each grouping function is represented by a JSON object where the name of the function is the field name and the value is the function content.
- Lists of arguments are represented as JSON arrays.
- A direct `label` field on an `all` operation with a direct `each` labels the group list produced by that `each`, equivalent to `each(...) as(label)` in the [grouping language](grouping-language.html#labels).
- Output expression labels use grouping language syntax inside `output`, for example `"output": "count() as(total)"`.

Examples:

Grouping statement:

```
| all(group(time.year(a)) each(output(count())
    all(group(time.monthofyear(a)) each(output(count())))
```

equivalent JSON `grouping`-argument:

```
"grouping" : [
  {
    "all" : {
      "group" : "time.year(a)",
      "each" : { "output" : "count()" },
      "all" : {
        "group" : "time.monthofyear(a)",
        "each" : { "output" : "count()" },
      }
    }
  }
]
```

Grouping statement:

```
all(
  group(year)
  each(output(count())) as(by_year)
)
```

equivalent JSON `grouping`-argument:

```
"grouping": [
  {
    "all": {
      "group": "year",
      "label": "by_year",
      "each": {
        "output": "count()"
      }
    }
  }
]
```

Grouping statement:

```
all(
  group(author)
  output(count() as(authors_cardinality))
)
```

equivalent JSON `grouping`-argument:

```
"grouping": [
  {
    "all": {
      "group": "author",
      "output": "count() as(authors_cardinality)"
    }
  }
]
```

Grouping statement:

```
all(group(predefined(foo, bucket[1, 2>, bucket[3, 4>)))
```

equivalent JSON `grouping`-argument:

```
"grouping" : [ 
  { 
    "all" : { 
      "group" : { 
        "predefined" : ["foo", { "bucket": [1,2]}, { "bucket": [3,4]} ] 
      } 
    } 
  } 
]
```

### Other query parameters

[Query parameters](../api/query.html) not specific to the Select or YQL syntax will work as well. For example, to search for everything (`"where": true`) in the `music` document type:

```
{
  "select": {
    "where": true
  },
  "model": {
    "restrict": "judgment"
  }
}
```

### Complete examples

Create one bucket for all documents (`"group": "\"all\""`) and output overall price statistics (`"avg(price)"` and `"sum(price)"`):

```
{
  "select": {
    "where": true,
    "grouping": [
      {
        "all": {
          "group": "\"all\"",
          "each": {
            "output": [
              "avg(price)",
              "sum(price)"
            ]
          }
        }
      }
    ]
  }
}
```

A more complex example:

```
{
  "select" : {
    "where" : {
      "and" : {
        "children" : [
          {"title" : "music"},
          {"default" : "festival"}
        ]
      }
     },
    "grouping" : [ {
      "all" : {
        "group" : "time.year(a)",
          "each" : { "output" : "count()" }
      }		
    } ]
  },
  "offset" : 5,
  "presentation" : {
    "bolding" : false,
    "format" : "json"
  }
}
```

* * *

### Examples with the different functions

##### CONTAINS

YQL: `where title contains 'a'`.

Format of this in JSON:

```
"where" : {
  "contains" : ["title", "a"]
}
```

##### CONTAINS with text()

YQL: `where title contains ({language:'en'}text('hello world'))`.

Format of this [text() operator with annotations](yql.html#text) in JSON:

```
"where" : {
  "contains" : [
    "title",
    { 
      "text" : { 
        "query" : "hello world",
        "attributes" : {
          "language" : "en"
        }
      }
    }
  ]
}
```

##### Numeric Operators

YQL: `where date >= 10`.

Format of this in JSON:

_Introducing the range parameter:_

```
"range" : [
  "date",
  { ">=" : 10}
]
```

The range query accepts the following parameters:

| **Operator** | **Description** |
| ≥ | Greater-than or equal to |
| \> | Greater-than |
| \< | Less-than |
| ≤ | Less-than or equal to |

YQL: `where range(field, 0, 500)`.

Format of this in JSON:

```
"where" : {
  "range" : [
    "field",
    { ">=" : 0, "<=" : 500}
  ]
}
```

##### OR

YQL: `where title contains 'a' or title contains 'b'`.

Format of this in JSON:

```
"where" : {
  "or" : [
    { "contains" : ["title", "a"] },
    { "contains" : ["title", "b"] }
  ]
}
```

##### AND

YQL: `where title contains 'a' and title contains 'b'`.

Format of this in JSON:

```
"where" : {
  "and" : [
    {"contains" : ["title", "a"] },
  {"contains" : ["title", "b"] }
  ]
}
```

##### AND NOT

YQL: `where title contains 'a' and !(title contains 'b')`.

Format of this in JSON:

```
"where" : {
  "and_not" : [
    {"contains" : ["title", "a"] },
    {"contains" : ["title", "b"] }
  ]
}
```

Formal structure:

```
"where" : {
  "and_not" : [
    <Statement>,
    <!Statement>,
    ..
  ]
}
```

##### Regular expressions

YQL: `where title matches "madonna"`.

Format of this in JSON:

```
"where" : {
  "matches" : [
    "title",
    "madonna"
  ]
}
```

Another example:

YQL: `where title matches "mado[n]+a"`

```
"where" : {
  "matches" : [
    "title",
    "mado[n]+a"
  ]
}
```

##### Phrase

YQL: `where text contains phrase("st", "louis", "blues")`.

Format of this in JSON:

```
"where" : {
  "contains" : ["text", { "phrase" : ["st", "louis", "blues"] } ]
}
```

##### Near and Ordered Near

YQL: `where description contains ([{"distance": 100}]onear("a", "b"))`.

Format of this in JSON:

```
"where" : {
  "contains" : [ 
    "description",
    { "onear" : {
      "children" : ["a", "b"],
      "attributes" : {"distance" : 100} 
      }
    }
  ]
}
```

##### Equals

YQL: `where my_number = 42`.

Format of this in JSON:

```
"where" : {
  "equals" : { "field": "my_number", "value": 42 }
}
```

This can also be expressed using the following shorthand form:

```
"where" : {
  "equals" : ["my_number", 42]
}
```

The `equals` operator supports boolean and integer values.

To match at a specific element index in an array field, add the `index` parameter. Only a single index is supported:

YQL: `where my_numbers[2] = 42`.

```
"where" : {
  "equals" : { "field": "my_numbers", "index": 2, "value": 42 }
}
```

##### Search within same struct element

YQL: `where persons contains sameElement(first_name contains 'Joe', last_name contains 'Smith', year_of_birth < 1940)`.

Format of this in JSON:

```
"where" : {
  "contains" : [
    "persons",
    { "sameElement" : [
      {"first_name" : "Joe",
      "last_name" : "Smith",
      "range" : [
        "year_of_birth",
        { "<" : 1940}
      ]
      }
    ]
    }
  ]
}
```

##### Term Equivalence

YQL: `where fieldName contains equiv("A","B")`.

Format of this in JSON:

```
"where" : {
  "contains" : [
    "fieldName",
    { "equiv" : ["A", "B"] }
  ]
}
```

##### Rank

YQL: `where rank(a contains "A", b contains "B")`.

Format of this in JSON:

```
"where" : {
  "rank" : [
    { "contains" : ["a", "A"] },
    { "contains" : ["b", "B"] }
  ]
}
```

##### Advanced functions

###### Wand

YQL: `where wand(description, {"a":1, "b":2}`.

Format of this in JSON:

```
"where" : {
  "wand" : ["description", {"a" : 1, "b":2}]
}
```

Another example:

YQL: `where [{"scoreThreshold": 13, "totalTargetHits": 7}]wand(description, {"a":1, "b":2})`.

Format of this in JSON:

```
"where" : {
  "wand" : {
    "children" : ["description", {"a" : 1, "b":2}],
    "attributes" : {"scoreThreshold": 13, "totalTargetHits": 7}
  }
}
```

###### dotProduct

YQL: `where dotProduct(description, {"a":1, "b":2})`.

Format of this in JSON:

```
"where" : {
  "dotProduct" : ["description", {"a" : 1, "b":2}]
}
```

###### weightedSet

YQL: `where weightedSet(description, {"a":1, "b":2})`.

Format of this in JSON:

```
"where" : {
  "weightedSet" : ["description", {"a" : 1, "b":2}]
}
```

###### weakAnd

YQL: `where {scoreThreshold: 41, "totalTargetHits": 7}weakAnd(a contains "A", b contains "B")`.

Format of this in JSON:

```
"where" : {
  "weakAnd" : {
    "children" : [{ "contains" : ["a", "A"] }, { "contains" : ["b", "B"] } ],
    "attributes" : {"scoreThreshold": 41, "totalTargetHits": 7}
	}
}
```

##### Predicate

YQL: `where predicate(predicate_field,{"gender":"Female"},{"age":20L})`.

Format of this in JSON:

```
"where" : {
  "predicate" : [
    "predicate_field",
    {"gender" : "Female"},
    {"age" : 20L}
  ]
}
```

 Copyright © 2026 - [Cookie Preferences](#)

### On this page:

- [Select Query Reference](#page-title)
- [Structure](#structure)
- [Where](#where)
- [Fields](#fields)
- [Grouping](#grouping)
- [Other query parameters](#other-query-parameters)
- [Complete examples](#complete-examples)
- [Examples with the different functions](#examples-with-the-different-functions)