path: root/container-search-gui/src/main/resources/gui/_includes/search-api-reference.html

---
# Copyright 2017 Yahoo Holdings. Licensed under the terms of the Apache 2.0 license. See LICENSE in the project root.
title: "Vespa Search API reference"
---

<p>
All the search request parameters listed below can be set in query
profiles. The first four blocks of properties are also modeled as
query profile types. These types can be referred from query profiles
(and inheriting types) to provide type checking on the parameters.
</p><p>
These parameters often have both a full name - which includes the
path from the root query profile - and one or more abbreviated
names. Both names can be used in search requests, while only full
names can be used in query profiles. The full names are case
sensitive, while the abbreviated names are case insensitive.
</p><p>
The parameters modeled as query profiles are also available through
get methods as Java objects from the Query to Searcher components.
</p>



<h2>Index</h2>

<dt>Query</dt>
<dd>
  <ul>
    <li><a href="#yql">yql</a></li>
  </ul>
</dd>
</dl>

<dl>
<dt>Native Execution Parameters</dt>
<dd>
  <ul>
    <li><a href="#hits">hits</a> [<em>count</em>]</li>
    <li><a href="#offset">offset </a>[<em>start</em>]</li>
    <li><a href="#queryProfile">queryProfile</a></li>
    <li><a href="#nocache">nocache</a></li>
    <li><a href="#groupingSessionCache">groupingSessionCache</a></li>
    <li><a href="#searchChain">searchChain</a></li>
    <li><a href="#timeout">timeout</a></li>
    <li><a href="#tracelevel">tracelevel</a></li>
    <li><a href="#trace.timestamps">trace.timestamps</a></li>
  </ul>
</dd>

<dt>Query Model Parameters</dt>
<dd>
  <ul>
    <li><a href="#model.defaultIndex">model.defaultIndex</a> [<em>def-idx, default-index</em>]</li>
    <li><a href="#model.encoding">model.encoding</a> [<em>encoding</em>]</li>
    <li><a href="#model.filter">model.filter</a> [<em>filter</em>]</li>
    <li><a href="#model.language">model.language</a> [<em>lang, language</em>]</li>
    <li><a href="#model.queryString">model.queryString</a> [<em>query</em>]</li>
    <li><a href="#model.restrict">model.restrict</a> [<em>restrict</em>]</li>
    <li><a href="#model.searchPath">model.searchPath</a> [<em>path</em>]</li>
    <li><a href="#model.sources">model.sources</a> [<em>search, sources</em>]</li>
   <li><a href="#model.type">model.type</a> [<em>type</em>]</li>
  </ul>
</dd>

<dt>Ranking</dt>
<dd>
  <ul>
    <li><a href="#ranking.location">ranking.location</a> [<em>location</em>]</li>
    <li><a href="#ranking.features">ranking.features</a> [<em>rankfeature</em>]</li>
    <li><a href="#ranking.listFeatures">ranking.listFeatures</a> [<em>rankfeatures</em>]</li>
    <li><a href="#ranking.profile">ranking.profile</a> [<em>ranking</em>]</li>
    <li><a href="#ranking.properties">ranking.properties</a> [<em>rankproperty</em>]</li>
    <li><a href="#ranking.sorting">ranking.sorting</a> [<em>sorting</em>]</li>
    <li><a href="#ranking.freshness">ranking.freshness</a></li>
    <li><a href="#ranking.queryCache">ranking.queryCache</a></li>
    <li><a href="#ranking.matchPhase">ranking.matchPhase</a></li>
  </ul>
</dd>

<dt>Presentation</dt>
<dd>
  <ul>
    <li><a href="#presentation.bolding">presentation.bolding</a> [<em>bolding</em>]</li>
    <li><a href="#presentation.format">presentation.format</a> [<em>format</em>]</li>
    <li><a href="#presentation.template">presentation.template</a></li>
    <li><a href="#presentation.summary">presentation.summary</a> [<em>summary</em>]</li>
    <li><a href="#presentation.timing">presentation.timing</a></li>
  </ul>
</dd>

<dt>Grouping</dt>
<dd>
  <ul>
    <li><a href="#select">select</a></li>
    <li><a href="#collapse.summary">collapse.summary</a></li>
    <li><a href="#collapsefield">collapsefield</a></li>
    <li><a href="#collapsesize">collapsesize</a></li>
  </ul>
</dd>

<dt>Geographical Searches</dt>
<dd>
  <ul>
    <li><a href="#pos.ll">pos.ll</a></li>
    <li><a href="#pos.radius">pos.radius</a>,</li>
    <li><a href="#pos.attribute">pos.attribute</a></li>
    <li><a href="#pos.bb">pos.bb</a></li>
  </ul>
</dd>

<dt>Streaming Search</dt>
<dd>
  <ul>
    <li><a href="#streaming.userid">streaming.userid</a></li>
    <li><a href="#streaming.groupname">streaming.groupname</a></li>
    <li><a href="#streaming.selection">streaming.selection</a></li>
    <li><a href="#streaming.priority">streaming.priority</a></li>
    <li><a href="#streaming.maxbucketspervisitor">streaming.maxbucketspervisitor</a></li>
  </ul>
</dd>

<dt>Semantic Rules</dt>
<dd>
  <ul>
    <li><a href="#rules.off">rules.off</a></li>
    <li><a href="#rules.rulebase">rules.rulebase</a></li>
    <li><a href="#trace.rules">trace.rules</a></li>
  </ul>
</dd>

<dt>Other</dt>
<dd>
  <ul>
    <li><a href="#recall">recall</a></li>
    <li><a href="#user">user</a></li>
    <li><a href="#nocachewrite">nocachewrite</a></li>
    <li><a href="#hitcountestimate">hitcountestimate</a></li>
    <li><a href="#metrics.ignore">metrics.ignore</a></li>
  </ul>
</dd>
</dl>


<h2 id="query">Query</h2>
<h3 id="yql">yql</h3>
<table class="table table-striped">
<tr><td>Alias</td><td></td></tr>
<tr><td>Values</td><td>String</td></tr>
<tr><td>Default</td><td>None</td></tr>
</table>
<p>
The YQL query will be parsed and executed in the backend.
Only simple YQL programs are supported, refer to
<a href="../query-language.html">YQL</a> for details.
</p>



<h2 id="native-execution-parameters">Native Execution Parameters</h2>
<p>
These parameters are defined in the <code>native</code> query profile type.
</p>


<h3 id="hits">hits</h3>
<table class="table table-striped">
<tr><td>Alias</td><td>count</td></tr>
<tr><td>Values</td>
    <td>
      A positive integer, or 0. The sum of <a href="#offset">offset</a> and
      <a href="#hits">hits</a> should be lower than the configured maxoffset
      value, and will be adjusted to fit. See also comment
      at <code>offset</code>.
    </td>
</tr>
<tr><td>Default</td><td>10</td></tr>
</table>
<p>
The maximum number of hits to return from the result set.
Must be lower than <code>maxHits</code>, which is either set in a
<a href="#queryProfile">query profile</a>, or default 400.
<!-- ToDo: link to def file or code where this is definied -->
</p>


<h3 id="offset">offset</h3>
<table class="table table-striped">
  <tr><td>Alias</td><td>start</td></tr>
  <tr><td>Values</td>
    <td>
      A positive integer, including 0.
    </td>
  </tr>
  <tr><td>Default</td><td>0</td></tr>
</table>
<p>
The index of the first hit to return from the result set.
Must be lower than <code>maxOffset</code>, which is either set in a
<a href="#queryProfile">query profile</a>, or default 1000.
<!-- ToDo: link to def file or code where this is definied -->
</p>


<h3 id="queryProfile">queryProfile</h3>
<table class="table table-striped">
  <tr><td>Alias</td><td><em>None</em></td></tr>
  <tr><td>Values</td>
    <td>
      A query profile id  -  name:version, where version can be omitted
      or partially specified, e.g "myprofile:2.1"
    </td>
  </tr>
  <tr><td>Default</td><td><code>default</code></td></tr>
</table>
<p>
A <a href="../query-profiles.html">query profile</a> has default properties for a query.
The default query profile is named <em>default</em> - example:
<pre>
&lt;query-profile id="default"&gt;
  &lt;field name="maxHits"&gt;10&lt;/field&gt;
  &lt;field name="maxOffset"&gt;1000&lt;/field&gt;
&lt;/query-profile&gt;
</pre>
</p>


<h3 id="nocache">nocache</h3>
<table class="table table-striped">
<tr><td>Alias</td><td></td></tr>
<tr><td>Values</td>
    <td>
      True or false
    </td>
</tr>
<tr><td>Default</td><td>false</td></tr>
</table>
<p>
Set to true to avoid the result being fetched from cache, and avoid
writing the result to cache after fetching it.
</p>


<h3 id="groupingSessionCache">groupingSessionCache</h3>
<table class="table table-striped">
<tr><td>Alias</td><td></td></tr>
<tr><td>Values</td>
    <td>
      True or false
    </td>
</tr>
<tr><td>Default</td><td>false</td></tr>
</table>
<p>
Set to true to store intermediate grouping results in the search back ends when
using multi level grouping expressions in order to speed up grouping at a
potential loss of accuracy. See the <a
href="grouping-syntax.html#sessionCache">grouping reference</a> for more
details.
</p>


<h3 id="searchChain">searchChain</h3>
<table class="table table-striped">
<tr><td>Alias</td><td></td></tr>
<tr><td>Values</td>
    <td>
      A search chain id  -  name:version, where version can be
      omitted or partially specified, e.g "mychain:2.1.3".
    </td>
</tr>
<tr><td>Default</td><td><code>default</code></td></tr>
</table>
<p>
The search chain initially invoked when processing this query. This
search chain may invoke other chains.
</p>


<h3 id="timeout">timeout</h3>
<table class="table table-striped">
<tr><td>Alias</td><td></td></tr>
<tr><td>Values</td>
    <td>
      Positive floating point number with an optional unit. Default unit
      is seconds (s), valid unit strings are e.g. <em>ms</em> and <em>s</em>. To set
      a timeout of one minute, the argument could be set to <em>60 s</em>.
      Space between the number and the unit is optional.
    </td>
</tr>
<tr><td>Default</td><td>Undefined, but guaranteed to be at least 5000 milliseconds. This default can be overridden by configuring timeout in a <a href="../query-profiles.html">query profile.</a></td></tr>
</table>
<p>The query timeout.</p>


<h3 id="trace.level">trace.level</h3>
<table class="table table-striped">
<tr><td>Alias</td>tracelevel<td></td></tr>
<tr><td>Values</td>
    <td>
      Any positive number
    </td>
</tr>
<tr><td>Default</td><td><em>No tracing</em></td></tr>
</table>
<p>
Set to a positive number to collect trace information for debugging
when running a query. Higher numbers give
progressively more detail on query transformations and searcher
execution.
</p>

<h3 id="trace.timestamps">trace.timestamps</h3>
<table class="table table-striped">
<tr><td>Alias</td><td></td></tr>
<tr><td>Values</td>
    <td>
      true or false
    </td>
</tr>
<tr><td>Default</td><td><em>No timestamps in trace</em></td></tr>
</table>
<p>
Enable it to get timing information already at <a href="#tracelevel">tracelevel=1</a> which is useful for debugging latency spent at different components in the search chain without rendering a lot of string data which is associated with higher trace levels.
</p>



<h2 id="query-model">Query Model Parameters</h2>

<h3 id="model.defaultIndex">model.defaultIndex [<em>def-idx, default-index</em>]</h3>
<table class="table table-striped">
<tr><td>Alias</td><td>def-idx, default-index</td></tr>
<tr><td>Values</td><td>An index name</td></tr>
<tr><td>Default</td><td><code>default</code></td></tr>
</table>
<p>
The field which is searched for query terms which doesn't explicitly specify an index.
</p>


<h3 id="model.encoding">model.encoding [<em>encoding</em>]</h3>
<table class="table table-striped">
<tr><td>Alias</td><td>encoding</td></tr>
<tr><td>Values</td><td>Encoding names or aliases defined in the <a href="http://www.iana.org/assignments/character-sets">IANA character sets</a></td></tr>
<tr><td>Default</td><td>utf-8</td></tr>
</table>
<p> Sets the encoding to use when returning a result. The encodings <em>big5</em>,
<em>euc-jp</em>, <em>euc-kr</em>, <em>gb2312</em>, <em>iso-2022-jp</em> and <em>shift-jis</em>
also influences how tokenization is done in the absence of an explicit language setting.
</p><p>
The query is always encoded as UTF-8, independently of how the result will be encoded.
</p>


<h3 id="model.filter">model.filter [<em>filter</em>]</h3>
<table class="table table-striped">
<tr><td>Alias</td><td>filter</td></tr>
<tr><td>Values</td><td>Any allowed collection of filter terms</td></tr>
<tr><td>Default</td><td><em>Not set</em></td></tr>
</table>
<p>
Sets a filter to be combined with the query. Typical use of a filter
is to add machine generated or preferences based filter terms to a raw
user query. The filter is parsed the same way as a query of type any,
the full syntax is available. The positive terms (preceded by +) and
phrases act as AND filters, the negative terms (preceded by -) act as
NOT filters, while the unprefixed terms will be used to RANK the
results. Unless the query has no positive terms, the filter will only
restrict and influence ranking of the result set, never cause more
matches than the query.
</p>


<h3 id="model.language">model.language [<em>lang, language</em>]</h3>
<table class="table table-striped">
<tr><td>Alias</td><td>language, lang</td></tr>
<tr><td>Values</td><td>Ref. RFC 3066</td></tr>
<tr><td>Default</td><td></em>Unspecified</em></td></tr>
</table>
<p>
  Informs Vespa about the natural language of the query. Please see
  <a href="../linguistics.html">linguistics</a> for details.
  This attribute should always be set when it is known. If this
  parameter is not set, it will be guessed from the query and encoding, and
  default to english if it cannot be guessed.
</p>


<h3 id="model.queryString">model.queryString [<em>query</em>]</h3>
<table class="table table-striped">
<tr><td>Alias</td><td>query</td></tr>
<tr><td>Values</td><td>Any HTTP encoded legal Vespa query language string</td></tr>
<tr><td>Default</td><td><em>Not set</em></td></tr>
</table>
<p>
The <a href="simple-query-language-reference.html">Simple Vespa Query Language</a> query string
specifying which documents to match in this query.
</p>


<h3 id="model.restrict">model.restrict [<em>restrict</em>]</h3>
<table class="table table-striped">
<tr><td>Alias</td><td>restrict</td></tr>
<tr><td>Values</td><td>A comma delimited list of document type names.</td></tr>
<tr><td>Default</td><td><em>Search unrestricted</em></td></tr>
</table>
<p>
The document types to restrict the search to when different document
types share the same search cluster.
</p>


<h3 id="model.searchPath">model.searchPath [<em>path</em>]</h3>
<table class="table table-striped">
<tr><td>Alias</td><td>searchpath</td></tr>
<tr><td>Values</td><td><ul>
      <li>searchpath::ELEMENT [';' ELEMENT]*</li>
      <li>ELEMENT::PART ['/' ROW]</li>
      <li>PART::EXP [',' EXP]*</li>
      <li>EXP::NUM | RANGE</li>
      <li>ROW::NUM</li>
      <li>RANGE::'['NUM ',' NUM ' &gt;'</li>
  </ul></td></tr>
<tr><td>Default</td><td><em>Whole cluster</em></td></tr>
</table>
<p>
Specification of which path to send the query to.
Used to select which set of search nodes in the cluster should be used.
Only meant for debugging/monitoring.
</p><p>
Examples:
Note that in an indexed content cluster with flat distribution we have 1 implicit row
and each search node represents a part.
<ul>
  <li>'7/3' = part 7, row 3.</li>
  <li>'7/' = part 7, any row.</li>
  <li>'7,1,9/0' = parts 1,7 and 9, row 0.</li>
  <li>'1,[3,9&gt;/0' = parts 1,3,4,5,6,7,8, row 0.</li>
</ul>
</p><p>
In a cluster with a multi-level dispatch setup we must specify a search path element for each level.
Lets say we have a setup with 2 mid-level dispatch groups, each containing 3 search nodes (and 3 dispatchers):
<ul>
  <li>'0/;2/' = dispatch group (part) 0, any of the dispatchers (row); search node (part) 2, any row (of 1 present).</li>
  <li>'0/1;2/0' = dispatch group (part) 0, dispatcher (row) 1; search node (part) 2, row 0 (of 1 present).</li>
</ul>
</p>


<h3 id="model.sources">model.sources [<em>search, sources</em>]</h3>
<table class="table table-striped">
<tr><td>Alias</td><td>search, sources</td></tr>
<tr><td>Values</td><td>A comma separated list of search cluster names or other source names</td></tr>
<tr><td>Default</td><td><em>Search unrestricted</em></td></tr>
</table>
<p>
The names of the sources to search, e.g one or more search clusters and/or federated sources.
</p>


<h3 id="model.type">model.type [<em>type</em>]</h3>
<table class="table table-striped">
<tr><td>Alias</td><td>type</td></tr>
<tr><td>Values</td><td>web, all, any, phrase, yql, adv (deprecated) -
  refer to <a href="simple-query-language-reference.html">simple query language reference</a></td></tr>
<tr><td>Default</td><td>all</td></tr>
</table>
<p>
Selects the query language syntax of the <a href="#model.queryString">query</a> parameter.
</p>



<h2 id="ranking">Ranking</h2>

<h3 id="ranking.location">ranking.location [<em>location</em>]</h3>
<table class="table table-striped">
<tr><td>Alias</td><td>location</td></tr>
<tr><td>Values</td><td>See <a href="../geo-search.html">Geo search</a></td></tr>
<tr><td>Default</td><td>None</td></tr>
</table>
<p>
Point (one or two dimensional) location to use as base for location ranking.
For geographical locations, it is recommended to add the location using <a href="#pos.ll">pos.ll</a>
<!-- ToDo: Why? -->
</p>


<h3 id="ranking.features">ranking.features.<em>featurename</em> [<em>rankfeature.</em>featurename]</h3>
<table class="table table-striped">
<tr><td>Alias</td><td>rankfeature.featurename</td></tr>
<tr><td>Values</td><td>Any string</td></tr>
<tr><td>Default</td><td>None</td></tr>
</table>
<p>
Set a rank feature to a value. This works for any key name <code>query(anyname)</code> (query features),
and also as a way to override all existing (match and document) features.
Example: <em>query=foo&amp;ranking.features.query(userage)=42&amp;ranking.features.fieldMatch(title)=0.65</em>
</p>


<h3 id="ranking.listFeatures">ranking.listFeatures [<em>rankfeatures</em>]</h3>
<table class="table table-striped">
<tr><td>Alias</td><td>rankfeatures</td></tr>
<tr><td>Values</td><td>boolean</td></tr>
<tr><td>Default</td><td>false</td></tr>
</table>
<p>
Set to true to request <em>all</em> rank features to be calculated and returned.
The rank features will be returned in the summary field rankfeatures.
This option is typically used for MLR training, should not to be used for production.
</p>


<h3 id="ranking.profile">ranking.profile [<em>ranking</em>]</h3>
<table class="table table-striped">
<tr><td>Alias</td><td>ranking</td></tr>
<tr><td>Values</td><td>Any rank profile name</td></tr>
<tr><td>Default</td><td><code>default</code></td></tr>
</table>
<p>
Sets the name of the rank profile to use for assigning relevancy scores.
The default rank profile will be used for back-ends which does not have the given rank profile.
</p>


<h3 id="ranking.properties">ranking.properties.<em>propertyname</em> [<em>rankproperty.propertyname</em>]</h3>
<table class="table table-striped">
<tr><td>Alias</td><td>rankproperty.propertyname</td></tr>
<tr><td>Values</td><td>Any string</td></tr>
<tr><td>Default</td><td><em>None</em></td></tr>
</table>
<p>
Set a rank property that is passed to, and used by a feature executor for this query.
Example: <em>query=foo&amp;ranking.properties.dotProduct.X={a:1,b:2}</em>
</p>


<h3 id="ranking.sorting">ranking.sorting [<em>sorting</em>]</h3>
<table class="table table-striped">
<tr><td>Alias</td><td>sorting</td></tr>
<tr><td>Values</td><td>A valid <a href="sorting.html">sort specification</a></td></tr>
<tr><td>Default</td><td>None - order by relevance</td></tr>
</table>
<p>
A specification of how to sort the result.
Fields you want to sort on must be stored as document attributes in the index structure
by adding <a href="search-definitions-reference.html#attribute">attribute</a> to the indexing statement.
</p>


<h3 id="ranking.freshness">ranking.freshness</h3>
<table class="table table-striped">
<tr><td>Alias</td><td></td></tr>
<tr><td>Values</td><td><code>[integer]</code>, an absolute time in seconds since epoch, or <code>now-[number]</code>, to use a time [integer] seconds into the past, or <code>now</code> to use the current time</td></tr>
<tr><td>Default</td><td>None - use the current time on each node.</td></tr>
</table>
<p>
Sets the time which will be used as <em>now</em> during execution.
</p>


<h3 id="ranking.queryCache">ranking.queryCache</h3>
<table class="table table-striped">
<tr><td>Alias</td><td></td></tr>
<tr><td>Values</td><td>boolean</td></tr>
<tr><td>Default</td><td>false</td></tr>
</table>
<p>
Turns query cache on or off. Search is a two-phase process. If the
query cache is on, the query is stored on the search nodes between the
first and second phase, saving network bandwidth and also query setup
time, at the expense of using more memory.
</p>


<h3 id="ranking.matchPhase">ranking.matchPhase</h3>
<p>Settings which control Vespa's behavior during the match phase.
If these are set in the query they will override any match-phase setting
in the rank profile.</p>
<dt></dt>
<dd>
  <ul>
    <li><a href="#ranking.matchPhase.maxHits">ranking.matchPhase.maxHits</a> the max number of hits that should be generated during the match phase</li>
    <li><a href="#ranking.matchPhase.attribute">ranking.matchPhase.attribute</a> the attribute to limit matches by if more than maxHits hits will be generated</li>
    <li><a href="#ranking.matchPhase.ascending">ranking.matchPhase.ascending</a> whether to keep the documents having the highest (default) or lowest values of the attribute</li>
    <li><a href="#ranking.matchPhase.diversity.attribute">ranking.matchPhase.diversity.attribute</a> the attribute to use to guarantee diversity.</li>
    <li><a href="#ranking.matchPhase.diversity.minGroups">ranking.matchPhase.diversity.minGroups</a> the minimum number of groups grouped by the diversity attribute.</li>
  </ul>
</dd>


<h3 id="ranking.matchPhase.maxHits">ranking.matchPhase.maxHits</h3>
<table class="table table-striped">
<tr><td>Alias</td><td></td></tr>
<tr><td>Values</td><td>long</td></tr>
<tr><td>Default</td><td>If sorting and not ranking: max(10000, maxhits+maxoffset).
  Otherwise: <em>none</em>.</td></tr>
</table>
<p>
The max hits the engine should attempt to produce in the match phase on each partition.
If it is determined during matching that many more hits than this will be generated, the matching will fall back to
take the best (highest or lowest) values of the attribute given by ranking.matchPhase.attribute.
</p><p>
By default, this will be turned on only when sorting is used and grouping is not.
If sorting is used, the primary sort attribute will be used as the match phase attribute if it has fast-search set.
In that case the default can be overridden by setting this value explicitly.
</p>


<h3 id="ranking.matchPhase.attribute">ranking.matchPhase.attribute</h3>
<table class="table table-striped">
<tr><td>Alias</td><td></td></tr>
<tr><td>Values</td><td>An attribute name</td></tr>
<tr><td>Default</td><td><em>none</em></td></tr>
</table>
<p>
The attribute to decide which documents are a match if the match phase
estimates that there will be more than maxHits matches.
This attribute should have fast-search set and should correlate with the order
which would be produced by a full evaluation.
</p>


<h3 id="ranking.matchPhase.ascending">ranking.matchPhase.ascending</h3>
<table class="table table-striped">
<tr><td>Alias</td><td></td></tr>
<tr><td>Values</td><td>boolean</td></tr>
<tr><td>Default</td><td>false</td></tr>
</table>
<p>
Whether the attribute should be sorted in ascending or descending (default) order
to determine which documents to keep as matches.
</p>


<h3 id="ranking.matchPhase.diversity.attribute">ranking.matchPhase.diversity.attribute</h3>
<table class="table table-striped">
<tr><td>Alias</td><td></td></tr>
<tr><td>Values</td><td>An attribute name</td></tr>
<tr><td>Default</td><td>none.</td></tr>
</table>
<p>
The attribute to be used for producing the desired diversity.
Also see <a href="search-definitions-reference.html#diversity-attribute">attribute</a>.
</p>


<h3 id="ranking.matchPhase.diversity.minGroups">ranking.matchPhase.diversity.minGroups</h3>
<table class="table table-striped">
<tr><td>Alias</td><td></td></tr>
<tr><td>Values</td><td>long</td></tr>
<tr><td>Default</td><td>none</td></tr>
</table>
<p>
The minimum number of groups that should be returned from the match phase grouped by the diversity attribute.
Also see <a href="search-definitions-reference.html#diversity-min-groups">min-groups</a>.
</p>



<h2 id="presentation">Presentation</h2>

<h3 id="presentation.bolding">presentation.bolding [<em>bolding</em>]</h3>
<table class="table table-striped">
<tr><td>Alias</td><td>bolding</td></tr>
<tr><td>Values</td><td>boolean</td></tr>
<tr><td>Default</td><td>true</td></tr>
</table>
<p>
Whether or not to bold search terms in <a href="search-definitions-reference.html">search definition</a>
fields defined with <a href="search-definitions-reference.html#bolding">bolding: on</a>
or <a href="search-definitions-reference.html#summary">summary: dynamic</a>.
</p>


<h3 id="presentation.format">presentation.format [<em>format</em>]</h3>
<table class="table table-striped">
<tr><td>Alias</td><td>format</td></tr>
<tr><td>Values</td><td>
  <table class="table table-striped">
    <tr>
      <td><em>No value</em> or <code><a href="default-result-format.html">default</a></code></td>
      <td>The default, builtin JSON format</td>
    </tr>
    <tr>
      <td><code><a href="default-result-format.html">json</a></code></td>
      <td>Builtin JSON format</td>
    </tr>
    <tr>
      <td><code>xml</code></td>
      <td>Deprecated, builtin XML format</td>
    </tr>
    <tr>
      <td><code><a href="page-result-format.html">page</a></code></td>
      <td>Alternative deprecated XML format which is suitable for use with <a href="../page-templates.html">page templates</a>.</td>
    </tr>
    <tr>
      <td><em>Any other value</em></td>
      <td>A custom <a href="../result-rendering.html">result renderer</a> supplied by the application
        </tr>
  </table>

</td></tr>
<tr><td>Default</td><td>default</td></tr>
</table>


<h3 id="presentation.summary">presentation.summary [<em>summary</em>]</h3>
<table class="table table-striped">
<tr><td>Alias</td><td>summary</td></tr>
<tr><td>Values</td><td>
  The name of the <a href="../document-summaries.html#summary-classes-in-queries">summary class</a>
  used to select fields in results.
</td></tr>
<tr><td>Default</td><td>The default summary class of the search definition.</td></tr>
</table>


<h3 id="presentation.template">presentation.template</h3>
<table class="table table-striped">
<tr><td>Alias</td><td></td></tr>
<tr><td>Values</td><td>Any id specification of a deployed page template.</td></tr>
<tr><td>Default</td><td></td></tr>
</table>
<p>
The id of the page template to use for this result. This should be used with the
<a href="page-result-format.html">page</a> result format.
</p>


<h3 id="presentation.timing">presentation.timing</h3>
<table class="table table-striped">
<tr><td>Alias</td><td></td></tr>
<tr><td>Values</td><td>boolean</td></tr>
<tr><td>Default</td><td>false</td></tr>
</table>
<p>
Whether a result renderer should try to add optional timing information
to the rendered page.
</p>



<h2 id="">Grouping and Aggregation</h2>

<h3 id="select">select</h3>
<table class="table table-striped">
<tr><td>Alias</td><td></td></tr>
<tr><td>Values</td><td>A valid grouping specification.</td></tr>
<tr><td>Default</td><td>No grouping</td></tr>
</table>
<p>
Requests specific multi-level result set statistics and/or hit groups to be returned in the result.
Fields you want to retrieve statistics or hit groups for must be stored as document attributes
in the index structure by adding attribute to the indexing statement.
See the <a href="../grouping.html">grouping guide</a>.
</p>


<h3 id="collapsefield">collapsefield</h3>
<table class="table table-striped">
<tr><td>Alias</td><td></td></tr>
<tr><td>Values</td><td>Any document summary field name</td></tr>
<tr><td>Default</td><td>No field collapsing</td></tr>
</table>
<p>
Collapse (i.e. aggregate) results using this field.
Collapsing is run in the container, not content node level.
Define a <em>collapsefield</em> to remove duplicates if the corpus has few duplicates -
this is more efficient than using <a href="#select">grouping</a>.
Otherwise, use grouping.
</p>


<h3 id="collapsesize">collapsesize</h3>
<table class="table table-striped">
<tr><td>Alias</td><td></td></tr>
<tr><td>Values</td><td>A positive integer</td></tr>
<tr><td>Default</td><td>1</td></tr>
</table>
<p>The number of hits to keep in each collapsed bucket</p>


<h3 id="collapse.summary">collapse.summary</h3>
<table class="table table-striped">
  <tr><td>Alias</td><td></td></tr>
  <tr><td>Values</td><td>A valid name of a document summary class.</td></tr>
  <tr><td>Default</td><td>Use default summary or attributes.</td></tr>
</table>
<p>Use this summary class to fetch the field used for collapsing.</p>



<h2 id="geographical-searches">Geographical Searches</h2>

<h3 id="pos.ll">pos.ll</h3>
<table class="table table-striped">
<tr><td>Alias</td><td></td></tr>
<tr><td>Values</td>
  <td>Position given in latitude and longitude - example: <em>S22.4532;W123.9887</em>
    Refer to <a href="search-definitions-reference.html#type:position">position field</a>
    for format specification.</td>
</tr>
<tr><td>Default</td><td>None</td></tr>
</table>


<h3 id="pos.radius">pos.radius</h3>
<table class="table table-striped">
<tr><td>Alias</td><td></td></tr>
<tr><td>Values</td><td>
  Radius of the circle used for filtering. Valid units of measurement are km, m and mi. Examples:
  <ul>
    <li>pos.radius=100m</li>
    <li>pos.radius=42mi</li>
    <li>pos.radius=4km</li>
  </ul>
  One can also specify just a number (internal units, micro-degrees), but this is not recommended.
</td></tr>
<tr><td>Default</td><td>50km</td></tr>
</table>


<h3 id="pos.bb">pos.bb</h3>
<table class="table table-striped">
<tr><td>Alias</td><td></td></tr>
<tr><td>Values</td><td>
  Bounding box for positions, given as latitude and longitude boundaries.
  The four boundaries must be specified as N, S, E, W, with degrees as
  a decimal fraction.  Degrees south of equator or west of Greenwich are
  input as negative numbers. Examples:
  <ul>
    <li>n=37.44899,s=37.3323,e=-121.98241,w=-122.06566</li>
    <li>s=40.183868,w=-74.819519,n=40.248291,e=-74.728798</li>
  </ul>
</td></tr>
<tr><td>Default</td><td>None</td></tr>
</table>


<h3 id="pos.attribute">pos.attribute</h3>
<table class="table table-striped">
  <tr><td>Alias</td><td></td></tr>
  <tr><td>Values</td><td>Any attribute that has zcurve encoded positions as a long attribute.</td></tr>
  <tr><td>Default</td><td>Random choice among the ones declared as position in the searchdefinition.</td></tr>
</table>
<p>
Which attribute to use for the position. Can be both single- or multi-value.
</p>



<h2 id="">Streaming Search</h2>
<p>
The features in this section applies to <a href="../streaming-search.html">streaming search</a> only.
</p>

<h3 id="streaming.userid">streaming.userid</h3>
<table class="table table-striped">
<tr><td>Alias</td><td></td></tr>
<tr><td>Values</td><td>An integer in decimal notation in the range [0, 2^64></td></tr>
<tr><td>Default</td><td>None</td></tr>
</table>
<p>
Restricts streaming search to only stream through documents with document ids having the n=&lt;number&gt;
modifier and the userid part matches the supplied value. This can be used for grouping documents on a 64 bit integer.
</p>


<h3 id="streaming.groupname">streaming.groupname</h3>
<table class="table table-striped">
<tr><td>Alias</td><td></td></tr>
<tr><td>Values</td><td>A string</td></tr>
<tr><td>Default</td><td>None</td></tr>
</table>
<p>
Restricts streaming search to only stream through documents with document ids having the g=&lt;groupname&gt;
modifier and the groupname part matches the supplied value. This can be used for grouping documents on a string.
</p>


<h3 id="streaming.selection">streaming.selection</h3>
<table class="table table-striped">
<tr><td>Alias</td><td></td></tr>
<tr><td>Values</td><td>A string</td></tr>
<tr><td>Default</td><td>None</td></tr>
</table>
<p>
Restricts streaming search using a <a href="document-select-language.html">document selection</a>.
This can be used for selecting a subset of documents based on an advanced expression.
</p>


<h3 id="streaming.priority">streaming.priority</h3>
<table class="table table-striped">
<tr><td>Alias</td><td></td></tr>
<tr><td>Values</td><td><a href="services.html#load-types">Priority class</a></td></tr>
<tr><td>Default</td><td>VERY_HIGH</td></tr>
</table>
<p>
Priority of the streaming search visitor. Having a high priority visitor helps maintain low latencies
even when the system is under load.
</p>


<h3 id="streaming.maxbucketspervisitor">streaming.maxbucketspervisitor</h3>
<table class="table table-striped">
<tr><td>Alias</td><td></td></tr>
<tr><td>Values</td><td>int</td></tr>
<tr><td>Default</td><td>1 (if ordering is set), or infinite</td></tr>
</table>
<p>
If set, visit only this many buckets at a time.
Combine with ordering to reduce visiting time for large users/groups.
</p>



<h2 id="semantic-rules">Semantic Rules</h2>
<p>
Refer to <a href="semantic-rules.html">semantic rules</a>.
</p>

<h3 id="rules.off">rules.off</h3>
<table class="table table-striped">
<tr><td>Alias</td><td></td></tr>
<tr><td>Values</td><td>Boolean</td></tr>
<tr><td>Default</td><td>True</td></tr>
</table>
<p>Turn rule evaluation off for this query</p>


<h3 id="rules.rulebase">rules.rulebase</h3>
<table class="table table-striped">
<tr><td>Alias</td><td></td></tr>
<tr><td>Values</td><td>String</td></tr>
<tr><td>Default</td><td>A rule base name</td></tr>
</table>
<p>The name of the rule base to use for these queries</p>


<h3 id="trace.rules">trace.rules</h3>
<table class="table table-striped">
<tr><td>Alias</td><td>tracelevel.rules</td></tr>
<tr><td>Values</td><td>int</td></tr>
<tr><td>Default</td><td>1-5 (?)</td></tr>
</table>
<p>
The amount of rule evaluation trace output to show, higher number means more details.
This is useful to see a trace from rule evaluation
without having to see trace from all other searchers at the same time.
</p>



<h2 id="other">Other</h2>

<h3 id="recall">recall</h3>
<table class="table table-striped">
<tr><td>Alias</td><td></td></tr>
<tr><td>Values</td><td>Any allowed collection of recall terms</td></tr>
<tr><td>Default</td><td>No recall</td></tr>
</table>
<p>
Sets a recall parameter to be combined with the query.
This is identical to <a href="#model.filter">filter</a>,
except that recall terms are not exposed to the ranking framework and thus not ranked.
As such, one can not use unprefixed terms; they must either by positive or negative.
</p>


<h3 id="user">user</h3>
<table class="table table-striped">
<tr><td>Alias</td><td></td></tr>
<tr><td>Values</td><td>A string</td></tr>
<tr><td>Default</td><td>None</td></tr>
</table>
<p>
The id of the user making the query. The contents of the argument are made available to the search chain,
but it triggers no features in Vespa apart from being propagated to the access log.
</p>


<h3 id="nocachewrite">nocachewrite</h3>
<table class="table table-striped">
<tr><td>Alias</td><td></td></tr>
<tr><td>Values</td><td>Boolean</td></tr>
<tr><td>Default</td><td>False</td></tr>
</table>
<p>Set to true to avoid the result being written to cache when fetched.</p>


<h3 id="hitcountestimate">hitcountestimate</h3>
<table class="table table-striped">
<tr><td>Alias</td><td></td></tr>
<tr><td>Values</td><td>Boolean</td></tr>
<tr><td>Default</td><td>False</td></tr>
</table>
<p>Make this an estimation query.
No hits will be returned, and total hit count will be set to an estimate of what executing
the query as a normal query would give.
</p>

<h3 id="metrics.ignore">metrics.ignore</h3>
<table class="table table-striped">
<tr><td>Alias</td><td></td></tr>
<tr><td>Values</td><td>Boolean</td></tr>
<tr><td>Default</td><td>False</td></tr>
</table>
<p>Ignore metric collection for this query request, useful for warm up queries</p>