query-language.html

---
# Copyright Vespa.ai. All rights reserved.
title: "Vespa Query Language - YQL"
---

<p>
  Vespa accepts unstructured human input and structured queries for application logic separately,
  then combines them into a single data structure for executing.
  Human input is parsed heuristically, see <a href="query-api.html#input">Query API input</a>.
  Application logic is expressed in YQL, use this guide for examples -
  also see the <a href="reference/query-language-reference.html">YQL reference</a>.
</p>



<h2 id="live-query-examples">Live query examples</h2>
<p>
  The following are live YQL examples:
</p>
<hr/>
<p>
  Selection: Select all documents from the <code>doc</code> source.
  This is the easiest way to count all documents in a source:
</p>
<p><a class="yql-x">select * from doc where true</a></p>
<hr/>

<p>Filtering: Find all documents with <code>ranking</code> in the <code>title</code> field:</p>
<p><a class="yql-x">select * from doc where title contains "ranking"</a></p>
<hr/>

<p>Filtering: Find all documents with <code>ranking</code> in the <code>default</code> <a href="schemas.html#fieldset">fieldset</a>.</p>
<p><a class="yql-x">select * from doc where default contains "ranking"</a></p>
<hr/>

<p>Ordering: Order by number of terms in the document, descending.</p>
<p><a class="yql-x">select * from doc where true order by term_count desc</a></p>
<hr/>

<p>Pagination: Select all documents, return hits 6-15.</p>
<p><a class="yql-x">select * from doc where true limit 15 offset 5</a></p>
<hr/>

<p>Grouping:</p>
<ul>
  <li>Select all documents from the <code>doc</code> source.</li>
  <li>Group by term count in buckets of 100, display average term count per bucket.</li>
  <li>Note on <code>limit 0</code>: This returns zero regular hits, only the grouping result.</li>
</ul>
<p><a class="yql-x">select * from doc where true limit 0 |
  all(
    group( fixedwidth(term_count,100) )
    each( output( avg(term_count) ) )
  )</a></p>
<p>Find more <a href="grouping.html">grouping examples</a>.</p>
<hr/>

<p>Numeric: Select documents with attribute "last_updated" > 1646167144:</p>
<p><a class="yql-x">select * from doc where last_updated > 1646167144</a></p>
<p>
  Numeric: Select documents with integer in field - works both for single-value fields and multivalue,
  like array&lt;int&gt;:
</p>
<p><a class="yql-x">select * from doc where term_count = 1403</a></p>
<hr/>

<p>Phrase: Select documents with the phrase "question answering":</p>
<p><a class="yql-x">select * from doc where default contains phrase("question","answering")</a></p>
<hr/>

<p>
  Timeout: Time out query execution after 100 ms, returning hits found before timing out -
  see <a href="reference/query-api-reference.html#ranking.softtimeout.enable">ranking.softtimeout.enable</a>:
</p>
<p><a class="yql-x">select * from doc where true timeout 100</a></p>
<hr/>

<p>
  Regular expressions: Select documents matching the regular expression
  in the <code>namespace</code> <a href="attributes.html">attribute</a> field:</p>
<p><a class="yql-x">select * from doc where namespace matches "op.*"</a></p>
<hr/>


<h3 id="command-line-queries">Command-line queries</h3>
<p>Use the <a href="vespa-cli.html">Vespa CLI</a> to run a query from the command-line:</p>
<div class="pre-parent">
  <button class="d-icon d-duplicate pre-copy-button" onclick="copyPreContent(this)"></button>
<pre>
$ vespa query 'select * from doc where true'
</pre>
</div>
<p>To use any HTTP client, use <code>-v</code> to generate the encoded YQL string:</p>
<pre>
$ vespa query <span class="pre-hilite">-v</span> 'select * from doc where true'

curl http://127.0.0.1:8080/search/\?timeout=10s\&yql=select+%2A+from+doc+where+true
</pre>
<p>Run the query:</p>
<div class="pre-parent">
  <button class="d-icon d-duplicate pre-copy-button" onclick="copyPreContent(this)"></button>
<pre>
$ curl http://127.0.0.1:8080/search/\?timeout=10s\&yql=select+%2A+from+doc+where+true
</pre>
</div>
<p>Alternatively, set the query as the <code>yql</code> parameter in a POST:</p>
<div class="pre-parent">
  <button class="d-icon d-duplicate pre-copy-button" onclick="copyPreContent(this)"></button>
<pre>
$ curl --data-urlencode 'yql=select * from doc where true' \
  http://127.0.0.1:8080/search/
</pre>
</div>



<!-- ToDo: move this to a live query - need to add a map field to a sample app -->
<h2 id="query-examples">Query examples</h2>
<p id="boolean">Boolean:</p>
<div class="pre-parent">
  <button class="d-icon d-duplicate pre-copy-button" onclick="copyPreContent(this)"></button>
<pre>
$ vespa query 'select * from doc where is_public = true'
</pre>
</div>
<p id="map">Map:</p>
<pre>
$ vespa query 'select * from doc where my_map contains sameElement(key contains "Coldplay", value > 10)'

#
# Schema definition for my_map:
#
field my_map type map&lt;string, int&gt; {
    indexing: summary
    struct-field key   { indexing: attribute }
    struct-field value { indexing: attribute }
}
</pre>
<p id="escapes">Escapes - see the <a href="faq.html#how-does-backslash-escapes-work">FAQ</a>:</p>
<pre>
#
# The artist field is:
#   "artist": "Meta..ica"
#

$ vespa query -v 'select * from music where artist matches "M.ta\\.\\.ica"'
</pre>