schemas.html

---
# Copyright Vespa.ai. All rights reserved.
title: "Schema reference"
redirect_from:
- en/reference/schema-reference.html
---

<p>
  This reference documents the syntax and content of schemas, document types, and fields.
  This is a reference, see <a href="../../basics/schemas.html">schemas</a> for an overview and examples.
</p>



<h2 id="syntax">Syntax</h2>
<p>
Throughout this document, a string in square brackets represents some argument.
The whole string, including the brackets, is replaced by a concrete string in a schema.
</p><p>
Constructs in schemas have a regular syntax.
Each element starts with the element <em>identifier</em>,
possibly followed by the <em>name</em> of this particular occurrence of the element,
possibly followed by a space-separated list of interleaved <em>attribute names</em>
and <em>attribute values</em>, possibly followed by the <em>element body</em>.
Thus, one will find elements of these varieties:
</p>
<p>
<code>[element-identifier] : [element-body]</code><br/>
<code>[element-identifier] [element-name] : [element-body]</code><br/>
<code>[element-identifier] [element-name] [attribute-name] [attribute-value]</code><br/>
<code>[element-identifier] [element-name] [attribute-name] [attribute-value] {
    [element-body]
}</code><br/>
</p>
<p>
  One-line element values start with a colon and end with a newline.
</p>
<p>
Multiline values (for fields supporting them) are any block of text enclosed in curly brackets.
</p>
<p>
Comments may be inserted anywhere and start with a hash (#).
</p>
<p>
Names are <em>identifiers</em>, they must match <code>["a"-"z","A"-"Z", "_"]["a"-"z","A"-"Z","0"-"9","_"]*</code>.
</p>
<p>A schema file is not sensitive to indentation.</p>



<h2 id="elements">Elements</h2>
<p>
  Elements and structure of a schema file:
</p>
<pre class="pre-config">
<a href="#schema">schema</a>
    <a href="#document">document</a>
        <a href="#struct">struct</a>
            <a href="#field">field</a>
                <a href="#match">match</a>
        <a href="#field">field</a><span style="display:none"> <!-- Keep field types here for the doc search direct display, hide for clarity -->
              <a href="#array">array&lt;type&gt;</a>
              <a href="#bool">bool</a>
              <a href="#byte">byte</a>
              <a href="#double">double</a>
              <a href="#float">float</a>
              <a href="#int">int</a>
              <a href="#long">long</a>
              <a href="#map">map&lt;key-type,value-type&gt;</a>
              <a href="#position">position</a>
              <a href="#predicate">predicate</a>
              <a href="#raw">raw</a>
              <a href="#reference">reference&lt;document-type&gt;</a>
              <a href="#string">string</a>
              <a href="#struct-name">struct-name</a>
              <a href="#tensor">tensor(dimension-1,...,dimension-N)</a>
              <a href="#uri">uri</a>
              <a href="#weightedset">weightedset&lt;element-type&gt;</a>
              <a href="#weightedset-properties">weightedset</a></span>
            <a href="#alias">alias</a>
            <a href="#attribute">attribute</a>
                <a href="#distance-metric">distance-metric</a>
            <a href="#bolding">bolding</a>
            <a href="#dictionary">dictionary</a>
            <a href="#id">id</a>
            <a href="#index">index</a>
                <a href="#index-hnsw">hnsw</a>
            <a href="#indexing">indexing</a>
            <a href="#linguistics">linguistics</a>
            <a href="#match">match</a>
            <a href="#normalizing">normalizing</a>
            <a href="#query-command">query-command</a>
            <a href="#rank">rank</a>
            <a href="#rank-type">rank-type</a>
            <a href="#sorting">sorting</a>
            <a href="#stemming">stemming</a>
            <a href="#struct-field">struct-field</a>
                <a href="#indexing">indexing</a>
                <a href="#match">match</a>
                <a href="#query-command">query-command</a>
                <a href="#struct-field">struct-field</a>
                 &hellip;
                <a href="#summary">summary</a>
                <a href="#summary-to">summary-to <b>DEPRECATED</b></a>
            <a href="#summary">summary</a>
            <a href="#summary-to">summary-to <b>DEPRECATED</b></a>
            <a href="#weight">weight</a>
        <a href="#compression">compression</a>
    <a href="#index">index</a>
    <a href="#field">field</a>
    <a href="#fieldset">fieldset</a>
    <a href="#rank-profile">rank-profile</a>
        <a href="#diversity">diversity</a>
            <a href="#diversity-attribute">attribute</a>
            <a href="#diversity-min-groups">min-groups</a>
        <a href="#match-phase">match-phase</a>
            <a href="#match-phase-attribute">attribute</a>
            <a href="#match-phase-order">order</a>
            <a href="#match-phase-total-max-hits">total-max-hits</a>
            <a href="#match-phase-max-hits">max-hits</a>
        <a href="#firstphase-rank">first-phase</a>
            <a href="#total-keep-rank-count">total-keep-rank-count</a>
            <a href="#keep-rank-count">keep-rank-count</a>
            <a href="#rank-score-drop-limit">rank-score-drop-limit</a>
            <a href="#expression">expression</a>
        <a href="#secondphase-rank">second-phase</a>
            <a href="#expression">expression</a>
            <a href="#secondphase-rank-score-drop-limit">rank-score-drop-limit</a>
            <a href="#secondphase-total-rerank-count">total-rerank-count</a>
            <a href="#secondphase-rerank-count">rerank-count</a>
        <a href="#globalphase-rank">global-phase</a>
            <a href="#expression">expression</a>
            <a href="#globalphase-rerank-count">rerank-count</a>
            <a href="#globalphase-rank-score-drop-limit">rank-score-drop-limit</a>
        <a href="#function-rank">function [name] </a>
        <a href="#inputs">inputs</a>
        <a href="#constants">constants</a>
        <a href="#onnx-model">onnx-model</a>
        <a href="#significance">significance</a>
        <a href="#rank-properties">rank-properties</a>
        <a href="#match-features">match-features</a>
        <a href="#mutate">mutate</a>
            <a href="#on-match">on-match</a>
            <a href="#on-first-phase">on-first-phase</a>
            <a href="#on-second-phase">on-second-phase</a>
            <a href="#on-summary">on-summary</a>
        <a href="#summary-features">summary-features</a>
        <a href="#rank-features">rank-features</a>
        <a href="#ignore-default-rank-features">ignore-default-rank-features</a>
        <a href="#num-threads-per-search">num-threads-per-search</a>
        <a href="#num-search-partitions">num-search-partitions</a>
        <a href="#min-hits-per-thread">min-hits-per-thread</a>
        <a href="#termwise-limit">termwise-limit</a>
        <a href="#post-filter-threshold">post-filter-threshold</a>
        <a href="#approximate-threshold">approximate-threshold</a>
        <a href="#filter-first-threshold">filter-first-threshold</a>
        <a href="#filter-first-exploration">filter-first-exploration</a>
        <a href="#exploration-slack">exploration-slack</a>
        <a href="#target-hits-max-adjustment-factor">target-hits-max-adjustment-factor</a>
        <a href="#filter-threshold">filter-threshold</a>
        <a href="#rank">rank</a>
        <a href="#rank-filter-threshold">filter-threshold</a>
        <a href="#rank-element-gap">element-gap</a>
        <a href="#rank-type">rank-type</a>
        <a href="#weakand">weakand</a>
            <a href="#weakand-stopword-limit">stopword-limit</a>
            <a href="#weakand-adjust-target">adjust-target</a>
            <a href="#weakand-allow-drop-all">allow-drop-all</a>
        <a href="#rank-profile">rank-profile (inner)</a>
    <a href="#constant">constant</a>
    <a href="#onnx-model">onnx-model</a>
    <a href="#stemming">stemming</a>
    <a href="#document-summary">document-summary</a>
        <a href="#summary">summary</a>
    <a href="#import-field">import field</a>
    <a href="#raw-as-base64-in-summary">raw-as-base64-in-summary</a>
</pre>



<h2 id="schema">schema</h2>

<p>The root element of schemas.
A schema describes a type of data and what we should compute over it.
A schema must be defined in a file named <code>[schema-name].sd</code>.</p>
<pre>
schema [name] inherits [name] {
    [body]
}
</pre>

<p>The <code>inherits</code> attribute is optional.
If a schema is inherited, this schema will include all the constructs of it as if they
were defined in this schema (except the parent document type).
The document type in this must declare that it inherits the document type of the parent schema.
</p>

<p>The body is mandatory and may contain:</p>
<table class="table">
  <thead>
  <tr><th>Name</th><th>Occurrence</th><th>Description</th></tr>
  </thead><tbody>
<tr><td><a href="#document">document</a></td>
  <td>One</td>
  <td>A document type defined in this schema</td>
</tr>

<tr><td><a href="#field">field</a></td>
  <td style="white-space:nowrap;">Zero to many</td>
  <td>A field not contained in the document.
    Use <em>synthetic fields</em> (outside <a href="#document">document</a>) to derive new field values
    to be placed in the indexing structure from document fields.
    Find examples in <a href="../../operations/reindexing.html#use-cases">reindexing</a>.</td>
</tr>

<tr><td><a href="#fieldset">fieldset</a></td>
  <td>Zero to many</td>
  <td>Group document fields together for searching</td>
</tr>

<tr><td><a href="#rank-profile">rank-profile</a></td>
  <td>Zero to many</td>
  <td>A bundle of ranking functions and settings, selectable in a query.</td>
</tr>

<tr><td><a href="#constant">constant</a></td>
  <td>Zero to many</td>
  <td>A constant tensor located in a file used for ranking</td>
</tr>

<tr><td><a href="#onnx-model">onnx-model</a></td>
  <td>Zero to many</td>
  <td>An ONNX model located in the application package used for ranking</td>
</tr>

<tr><td><a href="#stemming">stemming</a></td>
  <td>Zero or one</td>
  <td>The default stemming setting.</td>
</tr>

<tr><td><a href="#raw-as-base64-in-summary">raw-as-base64-in-summary</a></td>
  <td>Zero or one</td>
  <td>Base64 encode raw fields in summary rather than using an escaped string. The default is true.</td>
</tr>

<tr><td style="white-space: nowrap"><a href="#document-summary">document-summary</a></td>
  <td>Zero to many</td>
  <td>An explicitly defined document summary</td>
</tr>

<tr><td><a href="#import-field">import field</a></td>
  <td>Zero to many</td>
  <td>Import a field value from a global document</td>
</tr>
</tbody>
</table>



<h2 id="document">document</h2>
<p>
  Contained in <a href="#schema">schema</a> and describes a document type.
  This can also be the root of the schema, if the document is not to be queried directly.
</p>
<pre>
document [name] inherits [name-list] {
    [body]
}
</pre>
<p>
  The document name is optional; it defaults to the containing <code>schema</code>
 element's name. If there is no containing <code>schema</code> element, the document name is required. If the document with a name is defined inside a schema, the document name must match the <code>schema</code> element's name. The reference to <em>document type</em> in the documentation refers to the document name defined here.
</p>
<p>
  The <code>inherits</code> attribute is optional
  and has as value a comma-separated list of names of other document types.
  A document type may inherit the fields of one or more other document types,
  see <a href="/en/schemas/inheritance-in-schemas.html">document inheritance</a> for examples.
  If no document types are explicitly inherited,
  the document inherits the generic <code>document</code> type.
</p>

<p>The body of a document type is optional and may contain:</p>
<table class="table">
  <thead>
  <tr><th>Name</th><th>Occurrence</th><th>Description</th></tr>
  </thead><tbody>
<tr><td><a href="#struct">struct</a></td>
  <td>Zero to many</td>
  <td>A struct type definition for this document.</td>
</tr>

<tr><td><a href="#field">field</a></td>
  <td>Zero to many</td>
  <td>A field of this document.</td>
</tr>

<tr><td><a href="#compression">compression</a></td>
  <td>Zero to one</td>
  <td>Specifies compression options for documents of this document type in storage.</td>
  <!-- ToDo Check does this apply to proton? -->
</tr>
</tbody>
</table>



<h2 id="struct">struct</h2>
<p>
Contained in <a href="#document">document</a>.
Defines a composite type.
A struct consists of zero or more fields that the user can access together as one.
The struct has to be defined before it is used as a type in a field specification.
</p>
<pre>
struct [name] {
    [body]
}
</pre>
<p>The body of a struct is optional and may contain:</p>
<table class="table">
<thead>
<tr><th>Name</th><th>Occurrence</th><th>Description</th></tr>
</thead><tbody>
<tr><td><a href="#field">field</a></td>
  <td>Zero to many</td>
  <td>A field of this struct.</td>
</tr>
</tbody>
</table>



<h2 id="field">field</h2>
<p>
Contained in
<a href="#schema">schema</a>,
<a href="#document">document</a>,
or
<a href="#struct">struct</a>.
Defines a named value with a type and (optionally) how this field
should be stored, indexed, searched, presented, and how it should influence ranking.
</p>
<pre>
field [name] type [type-name] {
    [body]
}
</pre>
Do not use names that are used for other purposes in the indexing language
or other places in the schema file. Reserved names are:
<ul>
  <li>attribute</li>
  <li>body</li>
  <li>case</li>
  <li>context</li>
  <li>documentid</li>
  <li>else</li>
  <li>header</li>
  <li>hit</li>
  <li>host</li>
  <li>if</li>
  <li>index</li>
  <li>position</li>
  <li>reference</li>
  <li>relevancy</li>
  <li>sddocname</li>
  <li>summary</li>
  <li>switch</li>
  <li>tokenize</li>
</ul>
<p>
Other names not to use include any words that start with a number or include special characters.
</p><p>
The <em>type</em> attribute is mandatory - supported types:
</p>
<table class="table">
  <thead>
  <tr>
    <th>Field type</th>
    <th>Description</th>
  </tr>
  </thead>
  <tbody>

  <tr><th>array&lt;type&gt;</th>
    <td>
      <p id="array">
        For single-value (primitive) types, use array&lt;type&gt; to create an array field of the element type:
      </p>
      <table class="table">
        <thead></thead><tbody>
      <tr>
        <th style="width:100px">Index</th>
        <td>Each element is indexed separately</td>
      </tr><tr>
        <th>Attribute</th>
        <td>Added as an array attribute</td>
      </tr><tr>
        <th>Summary</th>
        <td>Added as an array summary field</td>
      </tr>
      </tbody>
      </table>
      <p>
        Also used to create an array field of the given <a href="#struct">struct type</a>.
        The struct type must be defined separately. Example:
      </p>
<pre>
struct person {
    field first_name type string {}
    field last_name  type string {}
}

field people type array&lt;person&gt; {
    indexing: summary
    summary:  matched-elements-only
    struct-field first_name {
        indexing: attribute
        attribute: fast-search
    }
}
</pre>
      <p>
        The entire <em>people</em> field is part of the document summary.
        The <a href="#struct-field">struct field</a> <em>first_name</em> is defined as an <em>attribute</em> for searching,
        with <a href="../../content/attributes.html#fast-search">fast-search</a>.
        A subset, or all, of the struct fields can be defined as attributes.
      </p>
      <p>
        Use the <a href="../querying/yql.html#sameelement">sameElement</a>
        operator to ensure matches in the same struct field instance.
      </p>
      <p>
        Use <a href="#matched-elements-only">matched-elements-only</a>
        to reduce the amount of data that is returned in the document summary.
      </p>
      {% include important.html content="
      <code>key</code> and <code>value</code> are reserved words in an array&lt;struct&gt;,
      as these are used to implement <a href='#map'>map</a>.
      Do not use these as struct-field names."%}
      <p>Restrictions:</p>
      <ul>
        <li>Array of struct types does not support <a href="../../basics/ranking.html">ranking features</a>
          and can only be used for matching and filtering.</li>
        <li>All struct arrays can be fed, retrieved, and used in document summaries.</li>
        <li>Some parts of struct arrays can be searched in <a href="../applications/services/content.html#document">indexed search mode</a>,
        while all parts of struct arrays can be searched in <a href="../../performance/streaming-search.html">streaming search</a>.
        See below for supported cases.</li>
      </ul>
      <table class="table">
        <thead></thead><tbody>
      <tr>
        <th style="width:100px">Index</th>
        <td>
          Only supported in <a href="../../performance/streaming-search.html#differences-in-streaming-search">streaming search</a>.
          Set this on the top-level struct array field to make all parts searchable.
        </td>
      </tr><tr>
        <th>Attribute</th>
        <td>
          Only supported for <a href="#struct-field">struct fields</a>
          that have primitive types (bool, string, int, long, byte, float, double).
          Any struct field must be defined as an attribute to be used for searching.
          The struct type can still contain fields of non-primitive types,
          as long as these are not defined as attributes.
        </td>
      </tr><tr>
        <th>Summary</th>
        <td>Added as an array summary field</td>
      </tr>
      </tbody>
      </table>
    </td></tr>

  <tr><th>bool</th>
    <td><p id="bool">Use for boolean values.</p>
<pre>
field alive type bool {
    indexing: summary | attribute
}
</pre>
      <table class="table">
        <thead></thead><tbody>
      <tr>
        <th style="width:100px">Index</th>
        <td>Not supported</td>
      </tr><tr>
        <th>Attribute</th>
        <td>Added as a boolean</td>
      </tr><tr>
        <th>Summary</th>
        <td>Added as a boolean value (<code>true</code> or <code>false</code>)</td>
      </tr>
      </tbody>
      </table>
      {% include important.html content="
      Defaults to <code>false</code> if not specified.
      "%}
    </td></tr>


  <tr><th>byte</th>
    <td><p id="byte">Use for single 8-bit numbers.</p>
<pre>
field smallnumber type byte {
    indexing: summary | attribute
}
</pre>
      <table class="table">
        <thead></thead><tbody>
      <tr>
        <th style="width:100px">Index</th>
        <td>Not supported. An attribute will automatically be used instead</td>
      </tr><tr>
        <th>Attribute</th>
        <td>Added as a byte which supports range searches</td>
      </tr><tr>
        <th>Summary</th>
        <td>Added as a byte</td>
      </tr>
      </tbody>
      </table>
    </td></tr>

  <tr><th>double</th>
    <td><p id="double">Use for high precision floating point numbers (64-bit IEEE 754 double).</p>
<pre>
field mydouble type double {
    indexing: summary | attribute
}
</pre>
      <table class="table">
        <thead></thead><tbody>
      <tr>
        <th style="width:100px">Index</th>
        <td>Not supported. An attribute will automatically be used instead</td>
      </tr><tr>
        <th>Attribute</th>
        <td>Added as a 64-bit IEEE 754 double which supports range searches</td>
      </tr><tr>
        <th>Summary</th>
        <td>Added as a 64-bit IEEE 754 double</td>
      </tr>
      </tbody>
      </table>
    </td></tr>

  <tr><th>float</th>
    <td><p id="float">Use for floating point numbers (32-bit IEEE 754 float).</p>
<pre>
field myfloat type float {
    indexing: summary | attribute
}
</pre>
      <table class="table">
        <thead></thead><tbody>
      <tr>
        <th style="width:100px">Index</th>
        <td>Not supported. An attribute will automatically be used instead</td>
      </tr><tr>
        <th>Attribute</th>
        <td>Added as a 32-bit IEEE 754 float which supports range searches</td>
      </tr><tr>
        <th>Summary</th>
        <td>Added as a 32-bit IEEE 754 float</td>
      </tr>
      </tbody>
      </table>
    </td></tr>

  <tr><th>int</th>
    <td><p id="int">Use for single 32-bit integers.</p>
<pre>
field release_year type int {
    indexing: summary | attribute
}
</pre>
      <table class="table">
        <thead></thead><tbody>
      <tr>
        <th style="width:100px">Index</th>
        <td>Not supported. An attribute will automatically be used instead</td>
      </tr><tr>
        <th>Attribute</th>
        <td>Becomes integer attributes, which supports range grouping and range searches</td>
      </tr><tr>
        <th>Summary</th>
        <td>Added as a 32-bit integer</td>
      </tr>
      </tbody>
      </table>
    </td></tr>

  <tr><th>long</th>
    <td><p id="long">Use for single 64-bit integers.</p>
<pre>
field bignumber type long {
    indexing: summary | attribute
}
</pre>
      <table class="table">
        <thead></thead><tbody>
      <tr>
        <th style="width:100px">Index</th>
        <td>Not supported. An attribute will automatically be used instead</td>
      </tr><tr>
        <th>Attribute</th>
        <td>Becomes a 64-bit integer attribute, which supports range grouping and range searches</td>
      </tr><tr>
        <th>Summary</th>
        <td>Added as a 64-bit integer</td>
      </tr>
      </tbody>
      </table>
    </td></tr>

  <tr><th>map&lt;key-type,value-type&gt;</th>
    <td>
      <p id="map">
        Use to create a map where each unique key is mapped to a single value.
        Any primitive type can be used as <em>key-type</em> and any primitive type or Vespa struct type as <em>value-type</em>.
        Example of a map of primitive types,
        where the <em>key</em> and <em>value</em> fields are specified as <em>attributes</em>:
      </p>
<pre>
field my_map type map&lt;string, int&gt; {
    indexing: summary
    struct-field key   { indexing: attribute }
    struct-field value { indexing: attribute }
}
</pre>
      <p>
        Note that a Vespa map entry is handled as a <em>struct</em>
        with a <em>key</em> and <em>value</em> field
        with <em>key-type</em> and <em>value-type</em> as types.
        This explains the <em>struct-field</em> syntax above.
        The full <em>my_map</em> field is configured into the document summary.
      </p>
      <p>A more complex example is a map of struct:</p>
<pre>
struct person {
    field first_name type string {}
    field last_name  type string {}
    field age        type int {}
}

field identities type map&lt;string, person&gt; {
    indexing: summary
    summary:  matched-elements-only
    struct-field key {
        indexing:  attribute
        attribute: fast-search
    }
    struct-field value.first_name {
        indexing:  attribute
        attribute: fast-search
    }
    struct-field value.last_name {
        indexing:  attribute
        attribute: fast-search
    }
}
</pre>
      <p>
        This example illustrates that the struct elements are configured individually -
        there is no field configuration for <em>age</em> -
        one can define a subset of the struct fields as attributes.
      </p>
      <p>
        Here, <em>key</em>, <em>value.first_name</em> and <em>value.last_name</em> are defined as attributes.
        This makes them available for searching and <a href="/en/querying/grouping.html#grouping-over-a-map-field">grouping</a>.
        A common use case is requiring matches in the same map entry
        (e.g., match both first and last name for the same person),
        see the <a href="/en/reference/querying/yql.html#sameelement">sameElement</a> operator
        for how to implement this.
        Use <a href="#matched-elements-only">matched-elements-only</a>
        to reduce the amount of data in the document summary.
        </p>
      <p>
        <a href="/en/performance/feature-tuning.html#when-to-use-fast-search-for-attribute-fields">fast-search</a>
        is used to make query access faster by creating an index structure for lookups.
      </p>
      <p>
        As an alternative to a map,
        an <a href="#array">array&lt;struct&gt;</a> can contain the same element multiple times and maintains order.
      </p>
      <p>Restrictions:</p>
      <ul>
        <li>Map of struct or primitive types do not support <a href="../../basics/ranking.html">ranking features</a>
          and can only be used for matching and filtering.</li>
        <li>All map types can be fed, retrieved, and used in document summaries.</li>
        <li>Some map types can be searched in <a href="../applications/services/content.html#document">indexed search mode</a>,
        while all map types can be searched in <a href="../../performance/streaming-search.html">streaming search</a>.
        See below for supported cases:</li>
      </ul>
      <table class="table">
        <thead></thead><tbody>
      <tr>
        <th style="width:100px">Index</th>
        <td>
          Only supported in <a href="../../performance/streaming-search.html#differences-in-streaming-search">streaming search</a>.
          Set this on the top-level map field to make all struct fields in the map field searchable.
        </td>
      </tr><tr>
        <th>Attribute</th>
        <td>
          Only supported for <a href="#struct-field">struct fields</a> where <em>value-type</em> is either a
          primitive type (bool, string, int, long, byte, float, double) or a
          <a href="#struct">struct type</a> with fields of primitive types.
          Any struct field must be defined as an attribute to be used for searching.
          The <em>value-type</em> struct can still contain fields of non-primitive types,
          as long as these are not defined as attributes.
        </td>
      </tr><tr>
        <th>Summary</th>
        <td>Added as a map.</td>
      </tr>
      </tbody>
      </table>
    </td></tr>

  <tr><th>position</th>
    <td>
      <p id="position">
        Used to filter and/or rank documents by distance to a position in the query,
        see <a href="../../querying/geo-search.html">Geo search</a>.
      </p>
<pre>
field location type position {
    indexing: attribute
}
</pre>
      <table class="table">
        <thead></thead><tbody>
      <tr>
        <th style="width:100px">Index</th>
        <td>Not supported</td>
      </tr><tr>
        <th>Attribute</th>
        <td>Added as an interleaved 64-bit integer
          (see <a href="https://en.wikipedia.org/wiki/Z-order_curve">Z-order curve</a>) -
          queries are implemented by doing a set of range searches in the attribute.
          This attribute has <a href="../../content/attributes.html#fast-search">fast-search</a> set implicitly</td>
      </tr><tr>
        <th>Summary</th>
        <td>Refer to the <a href="document-json-format.html#position">reference</a></td>
      </tr>
      </tbody>
      </table>
    </td></tr>

  <tr><th>predicate</th>
    <td>
      <p id="predicate">
        Use to match queries to a set of boolean constraints.
        See <a href="../../schemas/predicate-fields.html#queries">querying predicate fields.</a>
        Predicate fields are not supported in
        <a href="../../performance/streaming-search.html#differences-in-streaming-search">streaming search</a>.
      </p>
<pre>
field predicate_field type predicate {
    indexing: attribute
    index {
        arity: 2  # mandatory
        lower-bound: 3
        upper-bound: 200
        dense-posting-list-threshold: 0.25
    }
}
</pre>
      <table class="table">
        <thead></thead><tbody>
      <tr>
        <th style="width:100px">Index</th>
        <td>Not supported</td>
      </tr><tr>
        <th>Attribute</th>
        <td>Indexed in-memory in a variable-size binary format that is optimized for application during query evaluation</td>
      </tr><tr>
        <th>Summary</th>
        <td>Added as-is</td>
      </tr>
      </tbody>
      </table>
    </td></tr>

  <tr><th>raw</th>
    <td><p id="raw">Use for binary data</p>
<pre>
field rawfield type raw {
    indexing: summary | attribute
}
</pre>
      <table class="table">
        <thead></thead><tbody>
      <tr>
        <th style="width:100px">Index</th>
        <td>Not supported</td>
      </tr><tr>
        <th>Attribute</th>
        <td>Added as raw data. Not searchable.</td>
      </tr><tr>
        <th>Summary</th>
        <td>Added as raw data. Outputted as a base64-encoded string.
          See <a href="document-json-format.html#raw">JSON feed format</a> for details.
        </td>
      </tr>
      </tbody>
      </table>
    </td></tr>

  <tr><th>reference&lt;document-type&gt;</th>
    <td>
      <p id="reference">
        A <em>reference&lt;document-type&gt;</em> field is a reference to an instance of a document-type -
        i.e., a foreign key.
        Reference fields are not supported in
        <a href="../../performance/streaming-search.html#differences-in-streaming-search">streaming search</a>.
      </p>
<pre>
field artist_ref type reference&lt;artist&gt; {
    indexing: attribute
}
</pre>
      The reference is the <a href="../../schemas/documents.html">document id</a> of the document-type instance.
      References are used to join documents in a <a href="../../schemas/parent-child.html">parent-child relationship</a>.
      A reference can only be made to <a href="../applications/services/content.html#document">global</a> documents.
      The following types of references are not supported:
      <ul>
        <li>Self-reference</li>
        <li>Cyclic reference: If document type <em>foo</em> has a reference to <em>bar</em>,
          then <em>bar</em> cannot have a reference to <em>foo</em></li>
      </ul>
      A reference attribute field can be searched using the document id of the parent document-type instance as query term.
      Note that this will be a linear scan as <a href="#attribute">fast-search</a> is not supported.
      <table class="table">
        <thead></thead><tbody>
      <tr>
        <th style="width:100px">Index</th>
        <td>Invalid - deployment will fail</td>
      </tr><tr>
        <th>Attribute</th>
        <td>
          As <a href="#string">string</a> - a reference must be an attribute.
          Can be an empty string or point to a non-existent document.
          Memory usage is about 33 bytes per parent document.
          This is composed of 24 bytes used in a reference store, with a btree structure
          on top of that which requires 5 bytes on average (depends on lid compaction).
          In addition 4 bytes on average for a reference from child document to the parent document
          (depends on lid compaction). In total about 33 bytes.
        </td>
      </tr><tr>
        <th>Summary</th>
        <td>As <a href="#string">string</a></td>
      </tr>
      </tbody>
      </table>
    </td></tr>

  <tr><th>string</th>
    <td>
      <p id="string">
        Use for a text field of any length.
        String fields may only contain <em>text characters</em>, as defined by <code>isTextCharacter</code> in
        <a href="https://github.com/vespa-engine/vespa/blob/master/vespajlib/src/main/java/com/yahoo/text/Text.java">
          com.yahoo.text.Text</a>
      </p>
<pre>
field surname type string {
    indexing: summary | index
}
</pre>
      <table class="table">
        <thead></thead><tbody>
      <tr>
        <th style="width:100px">Index</th>
        <td>
          Refer to <a href="../../linguistics/linguistics.html">linguistics</a>
          for details on normalization, tokenization and stemming.
        </td>
      </tr><tr>
        <th>Attribute</th>
        <td>
          Added as-is. <a href="#match">match</a> exact or prefix is
          supported types of searches in string attributes. Searches are however
          case-insensitive. A query for <code>BritneY.spears</code> will match a
          document containing <code>BrItNeY.SpEars</code>
        </td>
      </tr><tr>
        <th>Summary</th>
        <td>Added as-is</td>
      </tr>
      </tbody>
      </table>
    </td></tr>

  <tr><th>struct</th>
    <td>
      <p id="struct-name">
        Use to define a field with a struct datatype.
        Create a <a href="#struct">struct type</a> inside the document definition and
        declare the struct field in a document or struct using the struct type name as the field type:
      </p>
<pre>
struct person {
    field first_name type string {}
    field last_name type string {}
}
field my_person type person {
    indexing: summary
}
</pre>
      Restrictions:
      <ul>
        <li>Struct fields can <strong>not</strong> be searched in indexed search mode
          (but <a href="#array">array of struct</a> and
          <a href="#map">map type</a> are searchable, with some restrictions).</li>
        <li>Struct fields can be fed, retrieved, and used in document summaries.</li>
      </ul>
      <table class="table">
        <thead></thead><tbody>
      <tr>
        <th style="width:100px">Index</th>
        <td>
          Only supported in <a href="../../performance/streaming-search.html#differences-in-streaming-search">streaming search</a>.
          Set this on the top-level field to make all parts searchable.
        </td>
      </tr><tr>
        <th>Attribute</th>
        <td>Not supported.</td>
      </tr><tr>
        <th>Summary</th>
        <td>Added as a struct.</td>
      </tr>
      </tbody>
      </table>
    </td></tr>

  <tr><th>tensor(dimension-1,...,dimension-N)</th>
    <td>
      <p id="tensor">
        Use to create a tensor field with the given
        <a href="../ranking/tensor.html#tensor-type-spec">tensor type spec</a>
        that can be used for <a href="../../basics/ranking.html">ranking</a> and
        <a href="../../querying/nearest-neighbor-search">nearest neighbor search</a>.
        A tensor field is otherwise <span style="text-decoration: underline;">not</span> searchable.
      </p><p>
      See <a href="../ranking/tensor.html">tensor evaluation reference</a> for definition,
      the <a href="../../ranking/tensor-user-guide.html">tensor user guide</a> and
      the <a href="document-json-format.html#tensor">JSON feed format</a>.
    </p>
<pre>
field tensorfield type tensor&lt;float&gt;(x{},y{}) {
    indexing: attribute | summary
}

field tensorfield type tensor&lt;float&gt;(x[2],y[2]) {
    indexing: attribute | summary
}
</pre>
      <table class="table">
        <thead></thead><tbody>
      <tr>
        <th style="width:100px">Index</th>
        <td>Supported for tensor types with:
          <ul>
            <li>One indexed dimension - single vector per document</li>
            <li>One or more mapped dimensions and one indexed dimension - multiple vectors per document</li>
          </ul>
          See <a href="../../querying/approximate-nn-hnsw">approximate nearest neighbor search</a>.</td>
      </tr><tr>
        <th>Attribute</th>
        <td>Added as-is in an attribute to be used for ranking and nearest neighbor search.</td>
      </tr><tr>
        <th>Summary</th>
        <td>Added as-is.</td>
      </tr>
      </tbody>
      </table>
    </td></tr>

  <tr><th>uri</th>
    <td><p id="uri">Use for URL type matching.
        URI fields are not supported in
        <a href="../../performance/streaming-search.html#differences-in-streaming-search">streaming search</a>.
        </p>
      <table class="table">
        <thead></thead><tbody>
      <tr>
        <th style="width:100px">Index</th>
        <td>
          <p>
            The URL is split into its different components, which are indexed
            separately. Note that only URLs can be indexed this way, not other URIs.
            The different components are as defined by the HTTP standard:
            Scheme, hostname, port, path, query, and fragment. Example:
          <pre>
http://mysite.mydomain.com:8080/path/shop?d=hab&amp;id=1804905709&amp;cat=100#frag1
</pre>
          <table class="table">
            <thead></thead><tbody>
          <tr>
            <th>scheme</th><td>http</td>
          </tr><tr>
            <th>hostname</th><td>mysite.mydomain.com (indexed as "mysite", "mydomain" and "com")</td>
          </tr><tr>
            <th>port</th><td>8080 (note that port numbers 80 and 443 are not indexed, as they are the normal port numbers)</td>
          </tr><tr>
            <th>path</th><td>/path/shop (indexed as "path" and "shop")</td>
          </tr><tr>
            <th>query</th><td>d=hab&amp;id=1804905709&amp;cat=100 (indexed as "d", "hab", "id", "1804905709", "cat" and "100")</td>
          </tr><tr>
            <th>fragment</th><td>frag1</td>
          </tr>
          </tbody>
          </table>
          The syntax for searching these different components is:
          <pre>
[field-name].[component-name]:term
</pre>
          Example: In a URI field <code>sourceurl</code>, search for documents from slashdot:
          <pre>
query=sourceurl.hostname:slashdot
</pre>
          <p>
            URL hostnames also support <em>anchored searching</em>, see
            <a href="../querying/yql.html#uri">search in URL fields</a>.
          </p><p>
          It is not possible to index uri-typed fields into a common index, i.e., it has
          to be indexed separately from other fields. If you need to combine URLs
          with other fields, you could store it in a string-field instead, but then
          you can not search in the different parts of the URL (scheme, hostname,
          port, path, query, and fragment).
        </p><p>
          <strong>Aliasing</strong> also works differently for URL fields - you
          are allowed to create aliases both to the index (as usual) and to the
          components of it. Use
<pre>
alias [component]: [alias]
</pre>
          to create an alias for a component. For example, given this field:
          <pre>
field surl type uri {
    indexing: summary | index
    alias: url
    alias hostname: site
}
</pre>
          <p>
            a search in "surl" and "url" will search in the entire url,
            while "surl.hostname" or "site" will search the hostname.
          </p>
        </td>
      </tr><tr>
        <th>Attribute</th>
        <td>Not allowed</td>
      </tr><tr>
        <th>Summary</th>
        <td>Added as-is as a string</td>
      </tr>
      </tbody>
      </table>
    </td></tr>

  <tr><th>weightedset&lt;element-type&gt;</th>
    <td><p id="weightedset">
      Use to create a multivalue field of the element type,
      where each element is assigned a signed 32-bit integer weight.
      <pre>
field tag type weightedset&lt;string&gt; {
    indexing: attribute | summary
}
</pre>
      <p>
      The element type can be one of the following primitive types: byte, int, long, and string.
      </p>
      <p>
        To access a weighted set in ranking when
        using <code>attribute</code>, see
        <a href="../ranking/rank-features.html#attribute-match-features-not-normalized">attribute the match features</a>,
        or convert the weighted set to a tensor using the tensorFromWeightedSet(field, dimensionName) feature.
      </p>
      <p>
        To access a weighted set in ranking when
        using <code>index</code>, see
        <a href="../ranking/rank-features.html#features-for-indexed-multivalue-string-fields">ranking features
        for indexed multivalued fields</a>. Note that when using <code>index</code> with weightedset, queries
        are matching across elements in the set.
      </p>
      <p>
        It is possible to specify that a new key should be created if it does not exist before the update,
        and that it should be removed if the weight is set to zero -
        see the <a href="#weightedset-properties">reference</a>.
      </p>
      <p>
        The weightedset field does not support filtering on weight.
        If you need that use the <a href="#map">map</a> type and
        <a href="../querying/yql.html#sameelement">sameElement</a> query operator -
        see <a href="../../querying/query-language.html#map">this example</a>.
      </p>
      <table class="table">
        <thead></thead><tbody>
      <tr>
        <th style="width:100px">Index</th>
        <td>
          Each token present in the field is indexed separately.
          Information indexed includes element number, element weight, and a
          list of token occurrence positions for each element in which the token is present
        </td>
      </tr><tr>
        <th>Attribute</th>
        <td>Added as a multivalue weighted attribute</td>
      </tr><tr>
        <th>Summary</th>
        <td>Added as a multivalue summary field if this is an attribute</td>
      </tr>
      </tbody>
      </table>
    </td></tr>
  </tbody>
</table>
<p>
The body of a field is optional for <a href="#schema">schema</a>,
<a href="#document">document</a> and
<a href="#struct">struct</a>. It may contain the following elements:
</p>
<table class="table">
  <thead>
  <tr><th>Name</th><th>Occurrence</th><th>Description</th></tr>
  </thead><tbody>
<tr><td>alias</td>
  <td style="white-space: nowrap">Zero to many</td>
  <td>
    <p id="alias">
      Make an index or attribute available in queries under an additional name.
      This has minimal performance impact and can safely be added to running applications. Example:
    </p>
<pre>
field artist type string {
    alias: artist_name
}
</pre>
    <p>
      <code>alias</code> works for primitive types, i.e, types you can set <code>indexing</code> on like <code>string</code>.
      Composite types are not supported, the below will throw an error when deploying:
    </p>
<pre>
document ppl {
    struct person {
        field first_name type string {}
        field last_name  type string {}
    }
    field p type array&lt;person&gt; {
        struct-field first_name {
            indexing: attribute
        }
        struct-field last_name {
            indexing: attribute
        }
        alias: members
    }
}
</pre>
  </td>
</tr>

<tr><td><a href="#attribute">attribute</a></td>
  <td>Zero to many</td>
  <td><p id="field-attribute">Specify an attribute setting.</p></td>
</tr>

<tr><td><a href="#bolding">bolding</a></td>
  <td>Zero to one</td>
  <td><p id="field-bolding">Specifies whether the content of this field should be bolded.
    Only supported for <a href="#indexing-index">index</a> fields of type string or array&lt;string&gt;.</p></td>
</tr>

<tr><td><a href="#id">id</a></td>
  <td>Zero to one</td>
  <td><p id="field-id">Explicitly decide the numerical id of this field. Is normally not necessary, but can be used to save some disk space.</p></td>
</tr>

<tr><td><a href="#index">index</a></td>
  <td>Zero to many</td>
  <td><p id="field-index">Specify a parameter of an index.</p></td>
</tr>

<tr><td><a href="#indexing">indexing</a></td>
  <td>Zero to one</td>
  <td><p id="field-indexing">The indexing statements used to create index structure additions
    from this field.</p></td>
</tr>

<tr><td><a href="#match">match</a></td>
  <td>Zero to one</td>
  <td><p id="field-match">Set the matching type to use for this field.</p></td>
</tr>

<tr><td><a href="#normalizing">normalizing</a></td>
  <td>Zero or one</td>
  <td><p id="field-normalizing">Specifies the kind of text normalizing to do on a string field.</p></td>
</tr>

<tr><td style="white-space: nowrap"><a href="#query-command">query-command</a></td>
  <td>Zero to many</td>
  <td><p id="field-query-command">Specifies a command which can be received by a plugin searcher in the Search Container.</p></td>
</tr>

<tr><td><a href="#rank">rank</a></td>
  <td>Zero or one</td>
  <td><p id="field-rank">Specify if the field is used for ranking.</p></td>
</tr>

<tr><td><a href="#rank-type">rank-type</a></td>
  <td>Zero to one</td>
  <td><p id="field-rank-type">Selects the set of low-level rank settings to be used for this field
    when using default <code>nativeRank</code>.</p></td>
</tr>

<tr><td><a href="#sorting">sorting</a></td>
  <td>Zero or one</td>
  <td><p id="field-sorting">The sort specification for this field.</p></td>
</tr>

<tr><td><a href="#stemming">stemming</a></td>
  <td>Zero or one</td>
  <td><p id="field-stemming">Specifies stemming options to use for this field.</p></td>
</tr>

<tr><td><a href="#struct-field">struct-field</a></td>
  <td>Zero to many</td>
  <td><p id="field-struct-field">A subfield of a field of type struct. The struct must have been defined to
    contain this subfield in the struct definition. If you want the subfield to
    be handled differently from the rest of the struct, you may specify it within
    the body of the struct-field.</p></td>
</tr>

<tr><td><a href="#summary">summary</a></td>
  <td>Zero to many</td>
  <td><p id="field-summary">Sets a summary setting of this field, set to <code>dynamic</code>
    to make a dynamic summary.</p></td>
</tr>

<tr><td><a href="#summary-to">summary-to</a></td>
  <td>Zero to one</td>
  <td><p id="field-summary-to">
    {% include deprecated.html content="Use <a href='#document-summary'>document-summary</a> instead."%}
    The list of document summary names this should be included in.</p></td>
</tr>

<tr><td><a href="#weight">weight</a></td>
  <td>Zero to one</td>
  <td><p id="field-weight">The importance of a field when searching multiple fields and using <code>nativeRank</code>.</p></td>
</tr>

<tr><td><a href="#weightedset-properties">weightedset</a></td>
  <td>Zero to one</td>
  <td><p id="field-weightedset-properties">Properties of a weightedset <a href="#weightedset">weightedset&lt;element-type&gt;</a></p></td>
</tr>
</tbody>
</table>
<p>
  Fields can not have default values.
  See the <a href="../../schemas/documents.html#fields">document guide</a> for how to auto-set field values.
</p>
<p>
  It is not possible to query for fields without value (i.e. query for NULL) -
  see the <a href="../querying/yql.html">query language reference</a>.
  Fields without value are not returned in <a href="../querying/default-result-format.html">query results</a>.
</p>
<p>
Fields can be declared outside the document block in the schema.
These fields are not part of the document type but behave like regular fields for queries.
Since they are not part of the document, they cannot be written directly,
but instead take their values from document fields, using the <code>input</code> expression:
<code>indexing: input my_document_field | embed | summary | index</code>
</p>
<p>
This is useful e.g., to index a field in multiple ways,
or to change the field value, something which is not allowed with document fields.
When the document field(s) used as input are updated, these fields are updated with them.
</p>



<h2 id="struct-field">struct-field</h2>
<p>
Contained in <a href="#field">field</a> or
<a href="#struct-field">struct-field</a>.
Defines how this struct field (a subfield of a struct) should be stored,
indexed, searched, presented, and how it should influence ranking.
The field in which this struct field is contained must be of
type struct or a collection of type struct:
</p>
<pre>
struct-field [name] {
    [body]
}
</pre>
<p>The body of a struct field is optional and may contain the following elements:</p>
<table class="table">
  <thead>
  <tr><th>Name</th><th>Occurrence</th><th>Description</th></tr>
  </thead>
  <tbody>
  <tr><td><a href="#indexing">indexing</a></td>
    <td>Zero to one</td>
    <td>The indexing statements used to create index structure additions from this field.
      For indexed search only <code>attribute</code> is supported, which makes the struct
      field a searchable in-memory attribute that can also be used for e.g. grouping and ranking.
      For <a href="../../performance/streaming-search.html">streaming search</a>
      <code>index</code> and <code>summary</code> are supported in addition.
    </td>
  </tr>
  <tr><td><a href="#attribute">attribute</a></td>
    <td style="white-space: nowrap">Zero to many</td>
    <td>Specifies an attribute setting. For example <code>attribute:fast-search</code>.</td>
  </tr>
  <tr><td><a href="#rank">rank</a></td>
    <td style="white-space: nowrap">Zero to one</td>
    <td>Specifies <a href="#rank">rank</a> settings</td>
  </tr>
  <tr><td><a href="#match">match</a></td>
    <td style="white-space: nowrap">Zero to one</td>
    <td>Specifies <a href="#match">match</a> settings</td>
  </tr>
  </tbody>
</table>
<p>
  If this struct field is of type struct (i.e., a nested struct), only <a href="#indexing">indexing:summary</a>
    may be specified. See <a href="#array">array&lt;type&gt;</a> for example use.
</p>



<h2 id="fieldset">fieldset</h2>
<p>
  Contained in <a href="#schema">schema</a>.
</p>
  {% include note.html content="this is not related to the
  <a href='../../schemas/documents.html#fieldsets'>Document fieldset</a>.
  Also see the <a href='../../learn/faq#must-all-fields-in-a-fieldset-have-compatible-type-and-matching-settings'>FAQ</a>
  for a discussion of what happens when using different types/match settings." %}
<p>A fieldset groups fields together for searching:</p>
<pre>
fieldset myfieldset {
    fields: a,b,c
}
</pre>
<p>
  Create a fieldset named <code>default</code> to be used as the default
  (i.e., when not specified in the query):
</p>
<pre>
fieldset default {
    fields: a,b,c
}
</pre>
<p>See <a href="../../querying/query-api.html#using-a-fieldset">example queries using fieldset</a>.</p>
<p>
  The fields in the fieldset should be as similar as possible in terms of indexing clause and <a href="#match">match mode</a>.
  If they are not, test the application thoroughly.
  Having different match modes for the fields in the fieldset generates a warning during application deployment.
  If specific match settings for the fieldset are needed, such as <em>exact</em>, specify it using <em>match</em>:
</p>
<pre>
fieldset myfieldset {
    fields: a,b,c
    match {
        exact
    }
}
</pre>
<p>
  Use <a href="#query-command">query-commands</a> in the field set to set search settings. Example:
</p>
<pre>
fieldset myfieldset {
    fields: a,b,c
    query-command:"exact @@"
}
</pre>
<p>Adding a fieldset will not create extra index structures in memory / on disk; it is just a mapping.</p>


<h2 id="compression">compression</h2>
  {% include deprecated.html content="see
  <a href='../release-notes/vespa8.html#compression'>deprecations</a>."%}
<p>
Contained in <a href="#document">document</a>.
If a compression level is set within this element,
<strong>lz4</strong> compression is enabled for whole documents.
<pre>
compression {
    [body]
}
</pre>
The body of a compression specification is optional and may contain:
<table class="table">
  <thead>
  <tr><th>Name</th><th>Occurrence</th><th>Description</th></tr>
  </thead><tbody>
<tr><td>type</td>
  <td style="white-space: nowrap">Zero to one</td>
  <td><p id="type"><strong>LZ4</strong> is the only valid compression method.</p></td>
</tr>
<tr><td>level</td>
  <td>Zero to one</td>
  <td><p id="level">Enable compression. LZ4 is linear and 9 means HC(high compression)</p></td>
</tr>
<tr><td>threshold</td>
  <td>Zero to one</td>
  <td>
    <p id="threshold">
      A percentage (multiplied by 100) giving the maximum size that
      compressed data can have to keep the compressed value.
      If the resulting compressed data is higher than this,
      the document will be stored uncompressed. The default value is 95.
    </p>
  </td>
</tr>
</tbody>
</table>



<h2 id="rank-profile">rank-profile</h2>

<p>Contained in <a href="#schema">schema</a> or equivalently in separate files in the
<a href="../applications/application-packages.html">application package</a>, named
<code>[profile-name].profile</code> in any directory below <code>schemas/[schema-name]/</code>.
A <a href="../../basics/ranking.html#rank-profiles">rank profile</a> is a named set of ranking expression functions and
settings which can be
<a href="../api/query.html#ranking.profile">selected in the query</a>).</p>

<p>Whether defined inline in the schema or in a separate .profile file, the syntax of a rank profile is</p>

<pre>
rank-profile [name] inherits [rank-profile1], [rank-profile2], ...  {
    [body]
}
</pre>

<p>The <code>inherits</code> list is optional and may contain the name of other rank profiles
in this schema or one it inherits.
Elements not defined in this rank profile will then be inherited from those profiles.
Inheriting multiple profiles that define the same elements leads to an error at deployment.</p>

<p>The body of a rank-profile may contain:</p>

<table class="table">
<thead>
<tr><th>Name</th><th>Occurrence</th><th>Description</th></tr>
</thead>
<tbody>
<tr><td><a href="#diversity">diversity</a></td>
  <td>Zero or one</td>
  <td>Specification of required diversity between the different phases.</td>
</tr>
<tr><td><a href="#strict">strict</a></td>
  <td>Zero or one</td>
  <td>true/false: Whether to use strict or loose type checking.</td>
</tr>
<tr><td><a href="#match-phase">match-phase</a></td>
  <td>Zero or one</td>
<td>Ranking configuration to be used for hit limitation during matching.</td>
</tr>
<tr><td><a href="#firstphase-rank">first-phase</a></td>
  <td>Zero or one</td>
<td>The ranking config to be used for first-phase ranking.</td>
</tr>
<tr><td><a href="#secondphase-rank">second-phase</a></td>
  <td>Zero or one</td>
<td>The ranking config to be used for second-phase ranking.</td>
</tr>
<tr><td><a href="#globalphase-rank">global-phase</a></td>
  <td>Zero or one</td>
  <td>The ranking config to be used for global-phase ranking.</td>
</tr>
<tr><td><a href="#function-rank">function [name] </a></td>
  <td>Zero or more</td>
<td>Defines a named function that can be referenced during ranking phase(s) and (if without arguments)
as part of match-and summary-features.</td>
</tr>
<tr><td><a href="#inputs">inputs</a></td>
  <td style="white-space: nowrap">Zero or many</td>
<td>List of query features used in ranking expressions.</td>
</tr>
<tr><td><a href="#constants">constants</a></td>
  <td>Zero or many</td>
<td>List of constant features available in ranking expressions.</td>
</tr>
<tr><td><a href="#mutate">mutate</a></td>
  <td>Zero or many</td>
<td>Specification of mutations you can apply after different phases of a query.</td>
</tr>
<tr><td><a href="#onnx-model">onnx-model</a></td>
  <td>Zero or many</td>
  <td>An onnx model to make available in this profile.</td>
</tr>
<tr><td><a href="#significance">significance</a></td>
  <td>Zero or one</td>
  <td>To enable the use of significance models defined in the service.xml config.</td>
</tr>
<tr><td><a href="#rank-properties">rank-properties</a></td>
  <td>Zero or one</td>
<td>List of any rank property key-values to be used by rank features.</td>
</tr>
<tr><td><a href="#match-features">match-features</a></td>
  <td>Zero or more</td>
<td>The <a href="../ranking/rank-features.html">rank features</a> to be returned with each hit, computed in the <em>match</em> phase.</td>
</tr>
<tr><td><a href="#summary-features">summary-features</a></td>
  <td>Zero or more</td>
<td>The <a href="../ranking/rank-features.html">rank features</a> to be returned with each hit, computed in the <em>fill</em> phase.</td>
</tr>
<tr><td><a href="#rank-features">rank-features</a></td>
  <td>Zero or more</td>
<td>The <a href="../ranking/rank-features.html">rank features</a> to be dumped when using the query-argument
  <a href="../api/query.html#ranking.listfeatures">rankfeatures</a>.</td>
</tr>
<tr><td>ignore-default-rank-features</td>
  <td>Zero or one</td>
  <td>
  <p id="ignore-default-rank-features">
    Do not dump the default set of rank features,
    only those explicitly specified with the <a href="#rank-features">rank-features</a> command.
  </p>
</td>
</tr>
<tr><td>num-threads-per-search</td>
  <td>Zero or one</td>
<td>
  <p id="num-threads-per-search">
    Overrides the global
    <a href="../applications/services/content.html#requestthreads-persearch">persearch</a> threads to a <strong>lower</strong> value.
  </p>
</td>
</tr>
<tr><td>min-hits-per-thread</td>
  <td>Zero or one</td>
<td>
  <p id="min-hits-per-thread">
    After estimating the number of hits for a query prior to query evaluation,
    this number is used to decide how many threads to use for the query.
  </p>
  <p>
    <code>num_treads = min(<a href="#num-threads-per-search">num-threads-per-search</a>,
      estimated_hits / min-hits-per-thread)</code>
  </p>
  <p>
    The current default is 1. If you suspect the fixed cost per thread is too high,
    increasing this number might be a good idea.
    Especially if most of your queries are cheap,
    but you have increased the <a href="#num-threads-per-search">num-threads-per-search</a>
    in order to reduce latency for your costly queries covering a lot of documents.
    The default might change, or the optimal value might be adaptive rendering overrides ignored or counterproductive.
  </p>
</td>
</tr>
<tr><td>num-search-partitions</td>
  <td>Zero or one</td>
<td>
  <p id="num-search-partitions">
    The number of logical partitions in which the corpus is divided on a search node.
    By default, this is the same as <a href="#num-threads-per-search">num-threads-per-search</a>.
    A partition is the smallest unit a search thread will handle.
    If you have a locality in time when searching and feeding documents,
    you might want to split it into more, smaller partitions.
    That way, you avoid that one costly partition leaves some threads idle while others are working hard.
  </p>
  <p>
    If you have 8 threads per search,
    you might have 10x as many partitions at 80 reducing max skew with a similar factor.
    Note that a value of zero turns on adaptive partitioning which tries to solve this optimally.
    {% include note.html content='If <code>num-search-partitions</code> is set to 0 (work sharing is enabled),
    make sure <code>termwise-limit</code> is set to 1.0 (termwise evaluation is disabled).
    This is to avoid redoing termwise evaluation when work is passed from one thread to another.' %}
  </p>
</tr>
<tr><td>termwise-limit</td>
  <td>Zero or one</td>
<td>
  <p id="termwise-limit">
    If estimated number of hits > corpus * termwise-limit,
    it will prune candidates with a CPU cache-friendly
    <a href="../../performance/feature-tuning.html#hybrid-taat-daat">TAAT</a>
    with the terms not needed for ranking,
    prior to doing <a href="../../performance/feature-tuning.html#hybrid-taat-daat">DAAT</a>.
    Current default is 1.0 which turns it off.
    A value between 0.05 and 0.20 can be a good starting point.
    This is particularly useful if you have many weak filters.
    Note that this is a manual override.
    The default might change, or the optimal value might be adaptive rendering overrides ignored or counterproductive.
  </p>
</td>
</tr>
<tr><td>post-filter-threshold</td>
  <td>Zero or one</td>
<td>
  <p id="post-filter-threshold">
    Threshold value (in the range [0.0, 1.0]) deciding if a query with an approximate
    <a href="../querying/yql.html#nearestneighbor">nearestNeighbor</a>
    operator combined with filters is evaluated using post-filtering instead of the default filtering.
    Post-filtering is chosen when the estimated filter hit ratio of the query is <em>larger</em> than this threshold.
    The default value is 1.0, which disables post-filtering.
    See
    <a href="https://blog.vespa.ai/constrained-approximate-nearest-neighbor-search/#controlling-the-filtering-behavior-with-approximate-nearest-neighbor-search">
    Controlling the filtering behavior with approximate nearest neighbor search</a> for more details.
  </p>
  <p>
    With post-filtering the <a href="../querying/yql.html#totaltargethits">totalTargetHits</a> value
    used when searching the HNSW index is auto-adjusted in an effort to expose the node's shgare of <em>totalTargetHits</em>
    hits to first-phase ranking after post-filtering has been applied. The following formula is used:
  </p>
<pre>
    adjustedTargetHits = min(targetHits / estimatedFilterHitRatio, targetHits * targetHitsMaxAdjustmentFactor).
</pre>
  <p>
    Use <a href="#target-hits-max-adjustment-factor">target-hits-max-adjustment-factor</a> to control
    the upper bound of the adjusted <em>targetHits</em>.
  </p>
  <p>
    This parameter has no effect in <a href="../../performance/streaming-search.html#differences-in-streaming-search">streaming search</a>.
  </p>
</td>
</tr>
<tr><td>approximate-threshold</td>
  <td>Zero or one</td>
<td>
  <p id="approximate-threshold">
    Threshold value (in the range [0.0, 1.0]) deciding if a query with an approximate
    <a href="../querying/yql.html#nearestneighbor">nearestNeighbor</a>
    operator combined with filters is evaluated by searching the
    <a href="schemas.html#index-hnsw">HNSW</a>
    graph for approximate neighbors with filtering,
    or performing an
    <a href="../../querying/nearest-neighbor-search">exact nearest neighbor search</a> with pre-filtering.
    The fallback to exact search is chosen when the estimated filter hit ratio of the query is <em>less</em>
    than this threshold.
    The default value is 0.02.
    See
    <a href="https://blog.vespa.ai/constrained-approximate-nearest-neighbor-search/#controlling-the-filtering-behavior-with-approximate-nearest-neighbor-search">
    Controlling the filtering behavior with approximate nearest neighbor search</a> for more details.
  </p>
  <p>
    This parameter has no effect in <a href="../../performance/streaming-search.html#differences-in-streaming-search">streaming search</a>.
  </p>
</td>
</tr>
<tr><td>filter-first-threshold</td>
  <td>Zero or one</td>
<td>
  <p id="filter-first-threshold">
    Threshold value (in the range [0.0, 1.0]) deciding if the filter is checked before computing a distance
    (<em>filter-first heuristic</em>) while searching the
    <a href="schemas.html#index-hnsw">HNSW</a>
    graph for approximate neighbors with filtering.
    This improves the response time at low hit ratios but causes a dip in recall.
    The heuristic is used when the estimated filter hit ratio of the query is <em>less</em>
    than this threshold.
    The default value is 0.2.
  </p>
  <p>
    This parameter has no effect in <a href="../../performance/streaming-search.html#differences-in-streaming-search">streaming search</a>.
  </p>
</td>
</tr>
<tr><td>filter-first-exploration</td>
  <td>Zero or one</td>
<td>
  <p id="filter-first-exploration">
    Value (in the range [0.0, 1.0]) specifying how aggressively the
    filter-first heuristic explores the graph when searching the
    <a href="schemas.html#index-hnsw">HNSW</a>
    graph for approximate neighbors with filtering.
    A higher value means that the graph is explored more aggressively
    and improves the recall at the cost of the response time.
    The default value is 0.01.
  </p>
  <p>
    This parameter has no effect in <a href="../../performance/streaming-search.html#differences-in-streaming-search">streaming search</a>.
  </p>
</td>
</tr>
<tr><td>exploration-slack</td>
  <td>Zero or one</td>
<td>
  <p id="exploration-slack">
    Value (in the range [0.0, 1.0]) specifying slack to delay the termination
    of the search of the
    <a href="schemas.html#index-hnsw">HNSW</a>
    graph for approximate neighbors with or without filtering.
    A higher value means that more of the graph is explored
    and improves the recall at the cost of the response time.
    The default value is 0.0.
  </p>
  <p>
    This parameter has no effect in <a href="../../performance/streaming-search.html#differences-in-streaming-search">streaming search</a>.
  </p>
</td>
</tr>
<tr><td>target-hits-max-adjustment-factor</td>
  <td>Zero or one</td>
<td>
  <p id="target-hits-max-adjustment-factor">
    Value (in the range [1.0, inf]) used to control the auto-adjustment of
    <a href="../querying/yql.html#totaltargethits">totalTargetHits</a> used when evaluating an approximate
    <a href="../querying/yql.html#nearestneighbor">nearestNeighbor</a>
    operator with post-filtering.
    The default value is 20.0.
  <p>
  <p>
    Setting this value to 1.0 disables auto-adjustment of <em>targetHits</em>.
    See <a href="#post-filter-threshold">post-filter-threshold</a> for more details.
  </p>
  <p>
    This parameter has no effect in <a href="../../performance/streaming-search.html#differences-in-streaming-search">streaming search</a>.
  </p>
</td>
</tr>
<tr><td>filter-threshold</td>
  <td>Zero or one</td>
<td>
  <p id="filter-threshold">
    The threshold value (in the range [0.0, 1.0]) deciding when matching in <em>index</em> fields should be treated as filters.
    This happens for query terms with <a href="../../learn/glossary.html#estimated-hit-ratio">estimated hit ratios</a> (in the
    range [0.0, 1.0]) that are above the <em>filter-threshold</em>.
    Use this to optimize query performance when searching large text <a href="../../basics/schemas.html#document-fields">index</a> fields,
    by allowing a per query combination of <a href="#filter">rank: filter</a> and <a href="#normal">rank: normal</a> behavior.
    This parameter can be overridden per <em>index</em> field, see <a href="#rank-filter-threshold">field-level filter-threshold</a>
    for a more detailed description with tradeoffs.
  </p>
  <p>
    In testing with various text datasets (e.g., Wikipedia), a <em>filter-threshold</em> setting of 0.05 has been shown to be a good starting point.
    See <a href="../../performance/feature-tuning.html#tuning-query-performance-for-lexical-search">Tuning query performance for lexical search</a>
    for more details.
  </p>
  <p>
    This parameter has no effect in <a href="../../performance/streaming-search.html#differences-in-streaming-search">streaming search</a>.
  </p>
  <p>
    Use the <a href="/en/reference/api/query.html#ranking.matching.filterThreshold">ranking.matching.filterThreshold</a>
    query parameter to override this value.
  </p>
</td>
</tr>
<tr><td><a href="#rank">rank</a></td>
  <td>Zero or more</td>
<td>Specify rank settings of a field in this profile.</td>
</tr>
<tr><td><a href="#rank-type">rank-type</a></td>
  <td>Zero or more</td>
<td>The rank-type of a field in this profile.</td>
</tr>
<tr><td><a href="#weakand">weakand</a></td>
  <td>Zero or one</td>
  <td>
    <p>
      Tunes the <a href="../../ranking/wand.html#weakand">weakAnd</a> algorithm to automatically
      exclude terms and documents with expected low query significance based on
      <a href="../../learn/glossary.html#document-frequency-normalized">document frequency</a>
      statistics present in the document corpus. This makes matching faster at the cost of potentially reduced recall.
    </p>
  </td>
</tr>
<tr><td><a href="#rank-profile">rank-profile (inner)</a></td>
  <td>Zero or more</td>
  <td>
    <p>An inner rank profile, useful for grouping related profiles, especially when defined in separate .profile files.
    This behaves just like a top level rank profile, except that:</p>
    <ul>
      <li>The full name of the profile to use in queries will be <code>containing-profile-name.inner-profile-name</code>.</li>
      <li>The profile must explicitly inherit the containing profile.</li>
    </ul>
  </td>
</tr>
</tbody>
</table>



<h2 id="match-phase">match-phase</h2>

<p>Contained in <a href="#rank-profile">rank-profile</a>.
The match-phase feature lets you increase performance by limiting hits
exposed to first-phase ranking to the highest (lowest) values of some attribute.
The performance gain may be substantial, especially with an expensive first-phase function.
The quality loss depends on how well the chosen attribute correlates with the
first-phase score.</p>

<p>Documents that have no value of the chosen attribute will be taken as having the value 0.</p>

<p>
  See also <a href="../../performance/graceful-degradation.html#match-phase-degradation">graceful degradation</a>
  and <a href="../../querying/result-diversity#match-phase-diversity">result diversity</a>.
</p>
<pre>
match-phase {
    attribute: [numeric single value attribute]
    order: [ascending | descending]
    total-max-hits: [integer]
}
</pre>
<table class="table">
<thead>
  <tr><th>Name</th><th>Description</th></tr>
</thead><tbody>
  <tr><td>attribute</td>
  <td>
    <p id="match-phase-attribute">
      The quality attribute that decides which documents are a match if the match phase
      estimates that there will be more than the node's share if
      <a href="#match-phase-total-max-hits">total-max-hits</a> hits.
      The attribute must be single-value numeric with <a href="#attribute">fast-search</a> enabled.
      It should correlate with the order which would be produced by a full query evaluation.
      No default.
    </p>
  </td></tr>
  <tr><td>order</td>
  <td>
    <p id="match-phase-order">
      Whether the attribute should be used in <code>descending</code> order (prefer documents with a high value)
      or <code>ascending</code> order (prefer documents with a low value).
      Usually, it is not necessary to specify this,
      as the default value <code>descending</code> is by far the most common.
    </p>
  </td></tr>
  <tr><td style="white-space: nowrap">total-max-hits</td>
    <td>
      <p id="match-phase-total-max-hits">
      The total max hits that should be produced in the match phase across all nodes
      in the group evaluating the query.
      This number should be large, and larger the worse the correlation between the
      match-phase attribute and the first-phase function.</p>
    </td></tr>
  <tr><td style="white-space: nowrap">max-hits</td>
    <td>
      <p id="match-phase-max-hits">
        The max hits each content node should attempt to produce in the match phase.
        Prefer using <a href="#match-phase-total-max-hits">total-max-hits</a> over this.
    </td></tr>
</tbody>
</table>




<h2 id="strict">strict</h2>

<p>Contained in <a href="#rank-profile">rank-profile</a>.
True or false. By default, Vespa uses loose type checking, where any query feature used but not defined in
a query profile type is assumed to be a float.
Set true to cause a deploy failure on missing query property type definitions instead.</p>

<pre>
strict: true
</pre>




<h2 id="diversity">diversity</h2>
<p>
Contained in <a href="#rank-profile">rank-profile</a>.
Diversity is used to guarantee diversity in the different query phases.
If you have <a href="#match-phase">match-phase</a>, it will provide diverse results from match-phase to first-phase.
If you have <a href="#secondphase-rank">second-phase</a>, it will provide diverse results from first-phase to second-phase.
</p>
<p>Read more about this in <a href="../../querying/result-diversity">result diversity</a>.</p>
<p>
Specify the name of an attribute that will be used to provide diversity.
Result sets are guaranteed to get at least <a href="#diversity-min-groups">min-groups</a>
unique values from the <a href="#diversity-min-groups">diversity attribute</a> from this phase,
but no more than max-hits.
For <a href="#match-phase">match-phase</a> max-hits = the node's share of <a href="#match-phase-max-hits">match-phase total-max-hits</a>.
For <a href="#secondphase-rank">second-phase</a> max-hits = the node's share of <a href="#secondphase-total-rerank-count">total-rerank-count</a>
A document is considered a candidate if:
<ul>
  <li>The query has not yet reached the <em>max-hits</em>
    number produced from this phase.</li>
  <li>The query has not yet reached the max number of candidates in one group.
    This is computed by the <em>max-hits</em>
    of the phase divided by <a href="#diversity-min-groups">min-groups</a></li>
</ul>
<pre>
diversity {
    attribute: [attribute name]
    min-groups: [integer]
}
</pre>
<table class="table">
  <thead>
    <tr><th>Name</th><th>Description</th></tr>
  </thead><tbody>
    <tr><td>attribute</td>
      <td>
        <p id="diversity-attribute">
        Which attribute to use when deciding diversity.
        The attribute must be a single-valued numeric, string or <a href="#reference">reference</a> type.
        </p>
      </td></tr>
    <tr><td style="white-space: nowrap">min-groups</td>
      <td>
        <p id="diversity-min-groups">
        Specifies the minimum number of groups returned from the phase.
        Using this with <a href="#match-phase">match-phase</a>
        often means one can reduce <a href="#match-phase-total-max-hits">total-max-hits</a>.
        In <a href="#secondphase-rank">second-phase</a>
        you might reduce <a href="#secondphase-total-rerank-count">total-rerank-count</a> and still get good and diverse results.
        </p>
      </td></tr>
  </tbody>
</table>



<h2 id="firstphase-rank">first-phase</h2>
<p>
Contained in <a href="#rank-profile">rank-profile</a>.
The config specifying the first phase of ranking.
See <a href="../../ranking/phased-ranking.html">
phased ranking with Vespa</a>.

This is the initial ranking performed on all matching documents;
you should therefore avoid doing computationally expensive relevancy calculations here.
By default, this will use the ranking feature <code>nativeRank</code>.
<pre>
first-phase {
    [body]
}
</pre>
The body of a first-phase ranking statement consists of:
<table class="table">
<thead>
<tr><th>Name</th><th>Description</th></tr>
</thead><tbody>
<tr><td><a href="#expression">expression</a></td>
  <td>
    <p>Specify the ranking expression to be used for the first phase of ranking -
    see <a href="../ranking/ranking-expressions.html">ranking expressions</a>.</p>
  </td>
</tr>
<tr><td>total-keep-rank-count</td>
  <td>
    <p id="total-keep-rank-count">How many documents to keep the first phase top rank values for.
    The default value is 10000 per node.</p>
  </td>
</tr>
<tr><td>keep-rank-count</td>
  <td>
    <p id="keep-rank-count">How many documents to keep the first phase top rank values for.
    Prefer <a href="#total-keep-rank-count">total-keep-rank-count</a> over this.</p>
  </td>
</tr>
<tr><td style="white-space: nowrap">rank-score-drop-limit</td>
  <td>
    <p id="rank-score-drop-limit">
      Drop all hits with a first-phase rank score less than or equal to this floating-point number.
      Use this to implement a rank cutoff.
      Default is <code>-Double.MAX_VALUE</code>
    </p>
  </td>
</tr>
</tbody>
</table>



<h2 id="expression">expression</h2>
<p>
Contained in <a href="#firstphase-rank">first-phase</a> or
<a href="#secondphase-rank">second-phase</a> or
<a href="#globalphase-rank">global-phase</a>.
Specify a <a href="../ranking/ranking-expressions.html">ranking expression</a>.
The expression can either be written directly or loaded from a file.
When writing it directly, the syntax is:
<pre>
expression: [ranking expression]
</pre>
or
<pre>
expression {
    [ranking expression]
    [ranking expression]
    [ranking expression]
}
</pre>
<p>
The second format is primarily a convenience feature when using long expressions, enabling them
to be split over multiple lines.
</p><p>
Expressions can also be loaded from a separate file. This is useful when dealing with the long
expressions generated by e.g. MLR. The syntax is:
<pre>
expression: file:[path-to-expressionfile]
</pre>
<p>
The path is relative to the location of the schema definition file.
The file itself must end with <code>.expression</code>. This suffix is optional in the schema.
Therefore <code>expression: file:mlrranking.expression</code> and
<code>expression: file:mlrranking</code> are identical.
Both refer to a file called <code>mlrranking.expression</code> in the <em>schemas</em> directory.
</p>
{% include note.html content="Directories are not allowed in the path."%}



<h2 id="rank-features">rank-features</h2>
<p>
Contained in <a href="#rank-profile">rank-profile</a>.
List of extra <a href="../ranking/rank-features.html">rank features</a> to be dumped
when using the query-argument <a href="../api/query.html#ranking.listfeatures">rankfeatures</a>.
<pre>
rank-features: [feature] [feature]
</pre>
or
<pre>
rank-features {
    [feature]
    [feature]
}
</pre>
<p>
Any number of ranking features can be listed on each line, separated by space.
</p>



<h2 id="inputs">inputs</h2>

<p>Contained in <a href="#rank-profile">rank-profile</a>.
List of inputs: Query features consumed by ranking expressions in this profile.</p>

<p>Query features are set either as a <a href="../api/query.html#ranking.features">request property</a>,
or equivalently from a <a href="../../applications/searchers.html">Searcher</a>, by calling
<code>query.getRanking().getFeatures().put("query(myInput)", myValue)</code>.</p>

<p>Query feature types can also be declared in
<a href="../../querying/query-profiles.html#query-profile-types">query profile types</a>,
but declaring inputs in the profile needing them is usually preferable.</p>

<p>Inputs are inherited from inherited profiles.</p>

<pre>
inputs {
    name [type]? (: value)?
}
</pre>
<table class="table">
<thead>
<tr>
  <th>Name</th>
  <th>Description</th>
</tr>
</thead>
<tbody>
<tr>
  <td>name</td>
  <td>The name of the inputs, written either the full feature name <code>query(myName)</code>, or just as <code>name</code>.
</tr>
<tr>
  <td>type</td>
  <td>The type of the constant, either <code>double</code> or a <a href="../ranking/tensor.html#tensor-type-spec">tensor type</a>.
      If omitted, the type is double.
</tr>
<tr>
  <td>value</td>
  <td>An optional default module, used if this input is not set in the query.
  A number, or a <a href="../ranking/tensor.html#tensor-literal-form">tensor on literal form</a>.
  </td>
</tr>
</tbody>
</table>

<p>Input examples:</p>

<pre>
inputs {
    myDouble: 0.5
    query(myOtherDouble) double
    query(myArray) tensor(x[3])
    query(myMap) tensor(key{}):{key1: 1.0, key2: 2.0}
}
</pre>



<h2 id="constants">constants</h2>

<p>Contained in <a href="#rank-profile">rank-profile</a>.
List of constants available in ranking expressions, resolved and optimized at configuration time.</p>

<p>Constants are inherited from inherited profiles, and from the schema itself.</p>

<pre>
constants {
    name [type]?: value|file:[path]
}
</pre>
<table class="table">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>name</td>
<td>The name of the constant, written either the full feature name <code>constant(myName)</code>, or just as <code>name</code>.
</tr>
<tr>
<td>type</td>
<td>The type of the constant, either <code>double</code> or a <a href="../ranking/tensor.html#tensor-type-spec">tensor type</a>.
If omitted, the type is double.
</tr>
<tr>
<td>value</td>
<td>A number, a <a href="../ranking/tensor.html#tensor-literal-form">tensor on literal form</a>,
or <code>file:</code> followed by a path from the application package root to a
file containing the constant.
The file must be stored in a valid <a href="../ranking/constant-tensor-json-format.html">tensor JSON Format</a>
and end with <code>.json</code>. The file may be lz4 compressed, in which case the ending must be
<code>.json.lz4</code>.
</td>
</tr>
</tbody>
</table>

<p>Constant examples:</p>

<pre>
constants {
    myDouble: 0.5
    constant(myOtherDouble) double: 0.6
    constant(myArray) tensor(x[3]):[1, 2, 3]
    constant(myMap) tensor(key{}]):{key1: 1.0, key2: 2.0}
    constant(myLargeTensor) tensor(x[10000]): file:constants/myTensor.json.lz4
}
</pre>



<h2 id="rank-properties">rank-properties</h2>
<p>
Contained in <a href="#rank-profile">rank-profile</a>.
List of generic properties, in the form of key/value pairs to be used by ranking features.
<a href="../ranking/rank-feature-configuration.html">Examples</a>.
<pre>
rank-properties {
    key: value
}
</pre>
<table class="table">
<thead>
<tr><th>Name</th><th>Description</th></tr>
</thead><tbody>
<tr><td>key</td>
<td>Name of the property.
</tr>
<tr><td>value</td>
<td>A number or any string. Must be quoted if it contains spacing.</td>
</tr>
</tbody>
</table>



<h2 id="function-rank">function (inline)? [name]</h2>
<p>
Contained in <a href="#rank-profile">rank-profile</a>.
Define a named function that can be referenced as a part of the ranking expression, or (if having no arguments) as a feature.
A function accepts any number of arguments.
<pre>
function [name]([arg1], [arg2], [arg3]) {
    expression: &hellip;
}
</pre>
or
<pre>
function [name] ([arg1], [arg2], [arg3]) {
    expression {
        [ranking expression]
        [ranking expression]
        &hellip;
}
</pre>
Note that the parenthesis is required after the name.
A rank-profile example is shown below:
<pre>
rank-profile default inherits default {
    function myfeature() {
        expression: fieldMatch(title) + freshness(timestamp)
    }
    function otherfeature(foo) {
        expression{ nativeRank(foo, body) }
    }

    first-phase {
        expression: myfeature * 10
    }
    second-phase {
        expression: otherfeature(title) * myfeature
    }
    summary-features: myfeature
}
</pre>
<p>
You can not include functions that accept arguments in summary features.
</p><p>
Adding the <code>inline</code> modifier will inline this function in the calling expression
if it also has no arguments.
This is faster for small and cheap functions (and more expensive for others).
</p>



<h2 id="secondphase-rank">second-phase</h2>
<p>
Contained in <a href="#rank-profile">rank-profile</a>.
The config specifying the second phase of ranking.
See <a href="../../ranking/phased-ranking.html">
phased ranking with Vespa</a>.

This is the optional re-ranking phase performed on the top-ranking hits from the
<code>first-phase</code>, and where you should put any advanced relevancy calculations.
For example Machine Learned Ranking (MLR) models.

By default, no second-phase ranking is performed.
<pre>
second-phase {
    [body]
}
</pre>
The body of a secondphase-ranking statement consists of:
<table class="table">
<thead>
<tr><th>Name</th><th>Description</th></tr>
</thead><tbody>
<tr><td><a href="#expression">expression</a></td>
<td><p>Specify the ranking expression to be used for the second phase of ranking. (for a description,
  see the <a href="../ranking/ranking-expressions.html">ranking expression</a> documentation.</p>
  <p id="secondphase-rescoring">Hits not reranked might be re-scored using a linear function to avoid a greater rank score than the worst reranked hit. This linear function will normally attempt to map the first phase rank score range of reranked hits to the reranked rank score range</p>
</td>
</tr>
<tr><td style="white-space: nowrap">rank-score-drop-limit</td>
  <td>
    <p id="secondphase-rank-score-drop-limit">
      When set, drop all hits with a second phase rank score (possibly a <a href="#secondphase-rescoring">re-scored</a> rank score) less than or equal to this floating point number.
      Use this to implement a second-phase rank cutoff.
      By default, this value is not set. This can also be <a href="../api/query.html#ranking.secondphase.rankscoredroplimit">set in the query</a>.
    </p>
  </td>
</tr>
<tr><td style="white-space: nowrap">total-rerank-count</td>
  <td>
    <p id="secondphase-total-rerank-count">
      Optional argument. Specifies the number of hits to be re-ranked in the second phase in total over the content
      nodes that participate in evaluating a query (a <i>group</i>).
      The default value is 100 per node. This can also be
      <a href="../api/query.html#ranking.secondphase.totalrerankcount">set in the query</a>.
      Hits not reranked might be <a href="#secondphase-rescoring">re-scored</a>.
    </p>
  </td>
</tr>
<tr><td style="white-space: nowrap">rerank-count</td>
  <td>
    <p id="secondphase-rerank-count">
    Optional argument. Specifies the number of hits to be re-ranked in the second phase on each content node.
    This can also be <a href="../api/query.html#ranking.secondphase.rerankcount">set in the query</a>.
    Prefer using <a href="#secondphase-total-rerank-count">total-rerank-count</a> over this.
    </p>
  </td>
</tr>
</tbody>
</table>



<h2 id="globalphase-rank">global-phase</h2>
<p>
Contained in <a href="#rank-profile">rank-profile</a>.

The config specifying the global phase of ranking.

See <a href="../../ranking/phased-ranking.html"> phased ranking with Vespa</a>.

This is an optional re-ranking phase performed on the top-ranking hits in
the stateless container after merging hits from all the content nodes.
The "top ranking" here means as scored by the first-phase ranking expression
or (if specified) second-phase ranking expression.

Typically used for computing large ONNX models, which would be expensive to compute on all content nodes.

By default, no global-phase ranking is performed.
<pre>
global-phase {
    [body]
}
</pre>
The body of a global-phase ranking statement consists of:
<table class="table">
<thead>
<tr><th>Name</th><th>Description</th></tr>
</thead><tbody>
<tr><td><a href="#expression">expression</a></td>
<td>Specify the ranking expression to be used for the global phase of ranking. (for a description,
    see the <a href="../ranking/ranking-expressions.html">ranking expression</a> documentation.</td>
</tr>
<tr><td style="white-space: nowrap">rerank-count</td>
<td>
  <p id="globalphase-rerank-count">
    Optional argument. Specifies the number of hits to be re-ranked in the global phase.
    The default value is 100.
    Note for complex setups: Applied to hits from one schema at a time, so if
    a query searches in multiple schemas simultaneously, global-phase may run for 100 hits
    per schema as default.
  </p>
</td>
<tr><td style="white-space: nowrap">rank-score-drop-limit</td>
    <td>
        <p id="globalphase-rank-score-drop-limit">
            When set, drop all hits with a global phase rank score (possibly a <a href="#globalphase-rank">re-scored</a> rank score) less than or equal to this floating point number.
            Use this to implement a global phase rank cutoff.
            By default, this value is not set. This can also be <a href="../api/query.html#ranking.globalphase.rankscoredroplimit">set in the query</a>.
        </p>
    </td>
</tr>
</tbody>
</table>



<h2 id="summary-features">summary-features</h2>
<p>
  Contained in <a href="#rank-profile">rank-profile</a>.
  List of <a href="../ranking/rank-features.html">rank features</a> to be included with each result hit,
  in the <a href="../querying/default-result-format.html#summaryfeatures">summaryfeatures</a> field.
  Also see <a href="../../ranking/ranking-expressions-features.html#accessing-feature-function-values-in-results">
  feature values in results</a>.
</p>
<p>
  If not specified, the features are as specified in the parent profile (if any).
  To inherit the features from the parent profile <em>and</em> specify additional features,
  specify explicitly that the features should be inherited from the parent, as shown below.
  Refer to <a href="/en/schemas/inheritance-in-schemas.html">schema inheritance</a> for examples.
</p>
<p>
  The rank features specified here are computed in the
  <a href="../../applications/searchers.html#multiphase-searching">fill phase</a> of multiphased queries.
</p>
{% include note.html content="Rank-features references in <em>summary-features</em>
are <strong>re-calculated</strong> during the <em>fill protocol phase</em>
for the hits which made it into the global top ranking hits (from all nodes).
See <a href='#match-features'>match-features</a> for an alternative." %}
<pre>
summary-features: [feature] [feature]&hellip;
</pre>
<p>or</p>
<pre>
summary-features [inherits parent-profile (, other-parent-profile)* ]? {
    [feature]
    [feature]
}
</pre>
<p>
Any number of rank features separated by space can be listed on each line.
{% include note.html content="Note that compound expressions must be wrapped in a <a href='https://docs.vespa.ai/en/ranking-expressions-features.html#accessing-feature-function-values-in-results'>function</a> to be accessible by match/summary-features. "%}
</p>


<h2 id="match-features">match-features</h2>
<p>
  Contained in <a href="#rank-profile">rank-profile</a>.
  List of <a href="../ranking/rank-features.html">rank features</a> to be included with each result hit,
  in the <a href="../querying/default-result-format.html#matchfeatures">matchfeatures</a> field.
  Also see <a href="../../ranking/ranking-expressions-features.html#accessing-feature-function-values-in-results">
  feature values in results</a>.
</p>
<p>
  If not specified, the features are as specified in the parent profile (if any).
  To inherit the features from the parent profile <em>and</em> specify additional features,
  specify explicitly that the features should be inherited from the parent as shown below,
  also see <a href="/en/schemas/inheritance-in-schemas.html">schema inheritance</a>.
</p>
<p>To disable match-features from parent rank profiles, use <code>match-features {}</code>.</p>
<p>
  <em>match-features</em> is similar to <a href="#summary-features">summary-features</a>,
  but the rank features specified here are computed in the <em>first protocol phase</em> of
  <a href="../../applications/searchers.html#multiphase-searching">multiprotocol query execution</a>,
  also called the <em>match</em> protocol phase.

  This gives a different performance trade-off, for details, see
  <a href="../../ranking/ranking-expressions-features.html#accessing-feature-function-values-in-results">
    feature values in results</a>.
</p>
<pre>
match-features: [feature] [feature]&hellip;
</pre>
<p>or</p>
<pre>
match-features [inherits parent-profile (, other-parent-profile)* ]? {
    [feature]
    [feature]
}
</pre>
<p>
Any number of ranking features separated by space can be listed on each line.
{% include note.html content="Note that compound expressions must be wrapped in a <a href='https://docs.vespa.ai/en/ranking-expressions-features.html#accessing-feature-function-values-in-results'>function</a> to be accessible by match/summary-features. "%}
</p>



<h2 id="mutate">mutate</h2>
<p>
Contained in <a href="#rank-profile">rank-profile</a>.
Specifies mutating operations you can do to each of the documents that make it through the 4 query phases,
<em>on-match</em>, <em>on-first-phase</em>, <em>on-second-phase</em> and <em>on-summary</em>.
</p>
<pre>
mutate {
    [phase name] { [attribute name] [operation] [numeric_value] }
}
</pre>
The phases are:
<table class="table">
<thead>
<tr><th>Name</th><th>Description</th></tr>
</thead><tbody>
<tr><td>on-match</td>
  <td>
    <p id="on-match">All documents that satisfy the query.</p>
  </td>
</tr>
<tr><td>on-first-phase</td>
  <td>
    <p id="on-first-phase">All documents from <a href="#on-match">on-match</a>,
       and is not dropped due the optional <a href="#rank-score-drop-limit">rank-score-drop-limit</a></p>
  </td>
</tr>
<tr><td>on-second-phase</td>
  <td>
    <p id="on-second-phase">All documents from <a href="#on-first-phase">on-first-phase</a>
    that makes it onto the <a href="#secondphase-rank">second-phase</a> heap.</p>
  </td>
</tr>
<tr><td>on-summary</td>
  <td>
    <p id="on-summary">All documents where are a summary is requested.</p>
  </td>
</tr>
</tbody>
</table>
<p>
  The attribute must be a single value numeric attribute, enabled as <a href="#mutable">mutable</a>.
  It must also be defined outside the <a href="#document">document</a> clause.
</p>
<table class="table">
<thead>
<tr><th>Operation</th><th>Description</th></tr>
</thead><tbody>
<tr>
  <td>=</td>
  <td><p>Set the value of the attribute to the given value.</p></td>
</tr>
<tr>
  <td>+=</td>
  <td><p>Add the given value to the attribute</p></td>
</tr>
<tr>
  <td>-=</td>
  <td><p>Subtract the given value from the attribute</p></td>
</tr>
</tbody>
</table>
<p>
  Find examples and use cases in <a href="../../ranking/phased-ranking.html#rank-phase-statistics">rank phase statistics</a>.
</p>


<h2 id="constant">constant</h2>

<p><i>Prefer to define constants in the rank profiles that need them,
with rank profile inheritance to avoid repetition.
See <a href="#constants">constants</a>.</i>
</p>

<p>Contained in <a href="#schema">schema</a>.
This defines a named constant tensor located in a file with a given type
that can be used in ranking expressions using the rank feature
<a href="../ranking/rank-features.html#constant(name)">constant(name)</a>:
<pre>
constant [name] {
    [body]
}
</pre>
The body of a constant must contain:
<table class="table">
<thead>
<tr><th>Name</th><th>Description</th><th>Occurrence</th></tr>
</thead><tbody>
<tr><td>file</td>
<td>
  Path to the file containing this constant, relative to the application package root.
  The file must be stored in a valid <a href="../ranking/constant-tensor-json-format.html">tensor JSON Format</a>
  and end with <code>.json</code>. The file may be lz4 compressed, in which case the ending must be
  <code>.json.lz4</code>.
</td>
<td>One</td>
</tr>
<tr><td>type</td>
<td>The type of the constant tensor, refer to
  <a href="../ranking/tensor.html#tensor-type-spec">tensor-type-spec</a> for reference.</td>
<td>One</td>
</tr>
</tbody>
</table>
Constant tensor example:
<pre>
constant my_constant_tensor {
    file: constants/my_constant_tensor_file.json
    type: tensor&lt;float&gt;(x{},y{})
}
</pre>
This example has a constant tensor with two mapped dimensions, <code>x</code> and <code>y</code>:
<pre>
{
    "cells": [
        { "address": { "x": "a", "y": "b"}, "value": 2.0 },
        { "address": { "x": "c", "y": "d"}, "value": 3.0 }
    ]
}
</pre>
<p>
When an application with tensor constants is deployed,
the files are distributed to the content nodes
before the new configuration is used by the search nodes.
Incremental changes to constant tensors are not supported.
When changed, replace the old file with a new one and redeploy the application,
or create a new constant with a new name in a new file.
</p>


<h2 id="raw-as-base64-in-summary">raw-as-base64-in-summary</h2>
<p>
Contained in <a href="#schema">schema</a>.
Whether raw fields should be rendered as a base64 encoded string in summary,
the same way as in <a href="document-json-format.html#raw">json feed format</a>,
rather than an escaped string. This is by default true.
</p>

<h2 id="onnx-model">onnx-model</h2>

<p>Contained in <a href="#rank-profile">rank-profile</a> or <a href="#schema">schema</a>.
This defines a named ONNX model located in a file
that can be used in ranking expressions using the "onnx" rank feature.</p>

<p>Prefer to define onnx models in the rank profiles using them.
Onnx models are inherited from parent profiles and from the schema.</p>

<pre>
onnx-model [name] {
    [body]
}
</pre>

<p>
The body of an ONNX model must contain:
<table class="table">
  <thead>
  <tr><th>Name</th><th>Occurrence</th><th>Description</th></tr>
  </thead>
  <tbody>
  <tr>
    <td>file</td>
    <td>One</td>
    <td>
      Path to the location of the file containing the ONNX model.
      The path is relative to the root of the application package containing this schema.
    </td>
  </tr>
  <tr>
    <td>input</td>
    <td style="white-space: nowrap">Zero to many</td>
    <td>
      An input to the ONNX model. The ONNX name, as given in the model, as well as the source for the input, is specified.
    </td>
  </tr>
  <tr>
    <td>output</td>
    <td>Zero to many</td>
    <td>
      An output of the ONNX model. The ONNX name, as given in the model, as well as the
      name for use in Vespa, is specified. If no output is defined and is not
      referred to from the rank feature, the first output defined in the model is used.
    </td>
  </tr>
  <tr>
    <td>gpu-device</td>
    <td>Zero or one</td>
    <td>
      Set the GPU device number to use for computation, starting at 0, i.e.
      if your GPU is <code>/dev/nvidia0</code> set this to 0. This must be an Nvidia CUDA-enabled GPU. Currently only
      models used in <a href="#globalphase-rank">global-phase</a> can make use of GPU-acceleration.
    </td>
  </tr>
  <tr>
    <td>intraop-threads</td>
    <td>Zero or one</td>
    <td>The number of threads available for running operations with multithreaded implementations.</td>
  </tr>
  <tr>
    <td>interop-threads</td>
    <td>Zero or one</td>
    <td>
      The number of threads available for running multiple operations in parallel.
      This is only applicable for <code>parallel</code> execution mode.
    </td>
  </tr>
  <tr>
    <td style="white-space: nowrap">execution-mode</td>
    <td>Zero or one</td>
    <td>Controls how the operators of a graph are executed, either <code>sequential</code> or <code>parallel</code>.</td>
  </tr>
  </tbody>
</table>
<p>For more details including examples, see <a href="../../ranking/onnx">ranking with ONNX models.</a></p>

<h2 id="significance">significance</h2>

<p>
Contained in <a href="#rank-profile">rank-profile</a>.
Configures a <a href="../../ranking/significance">significance model</a>.
</p>
<pre>
significance {
    use-model: true
}
</pre>
<p>The body must contain:</p>
<table class="table">
    <thead>
        <tr><th>name</th>
        <th>occurrence</th>
        <th>description</th></tr>
    </thead>
    <tbody>
        <tr>
            <td>use-model</td>
            <td>One</td>
            <td>Enable or disable the use of significance models specified in  <a href="../applications/services/search.html#significance">service.xml</a>.</td>
        </tr>
    </tbody>
</table>
<p>For more details see <a href="../../ranking/significance">Significance Model.</a></p>



<h2 id="document-summary">document-summary</h2>
<p>
Contained in <a href="#schema">schema</a>.
An explicitly defined document summary. By default, a document summary
named <code>default</code> is created.  Using this element, other document
summaries containing a different set of fields can be created.
<pre>
document-summary [name] inherits [document-summary1], [document-summary2], ... {
    [body]
}
</pre>
<p>
  The <code>inherits</code> attribute is optional.
  If defined, it contains the name of other document summaries in the same schema (or a parent)
  which this summary should inherit the fields of.
  Refer to <a href="../../schemas/inheritance-in-schemas.html">schema inheritance</a> for examples.
</p>
<p>The body of a document summary consists of:</p>
<table class="table">
  <thead>
  <tr><th>Name</th><th>Occurrence</th><th>Description</th></tr>
  </thead>
  <tbody>
  <tr>
    <td>from-disk</td>
    <td>Zero or one</td>
    <td>
      Mark this summary as accessing fields on disk.
      This will silence the warnings that this summary reads from disk;
      in the console for prod deployments, on the command line for manual deployments.
      Read more in <a href="/en/querying/document-summaries.html#performance">Document Summaries</a>
      on how to avoid disk access to speed up queries.
    </td>
  </tr>
  <tr>
    <td><a href="#summary">summary</a></td>
    <td style="white-space: nowrap">Zero to many</td>
    <td>A summary field in this document summary.</td>
  </tr>
  <tr>
    <td>omit-summary-features</td>
    <td>Zero or one</td>
    <td>
      Specifies that <a href="#summary-features">summary-features</a> should be omitted from this document summary.
      Use this to reduce CPU cost in
      <a href="../../applications/searchers.html#multiphase-searching">multiphase searching</a>
      when using multiple document summaries to fill hits,
      and only some of them need the summary features that are specified in the
      <a href="#rank-profile">rank-profile</a>.
    </td>
  </tr>
  </tbody>
</table>
<p>
  Use the <a href="../api/query.html#presentation.summary">summary</a>
  query parameter to choose a document summary in searches
  or in <a href="/en/reference/querying/grouping-language.html#summary">grouping</a>.
  See also <a href="../../querying/document-summaries.html">document summaries</a>.
</p>



<h2 id="stemming">stemming</h2>
<p>
Contained in <a href="#field">field</a>,
<a href="#schema">schema</a> or
<a href="#index">index</a>.
Sets how to stem a field or an index, or how to stem by default. Typically used
with <a href="../../linguistics/linguistics-opennlp.html">OpenNLP linguistics</a>.
Read more on <a href="../../linguistics/linguistics-opennlp.html#stemming">stemming</a>.
<pre>
stemming: [stemming-type]
</pre>
The stemming types are:
<table class="table">
<thead>
<tr><th>Type</th><th>Description</th></tr>
</thead><tbody>
<tr><td>none</td><td>No stemming: Keep words unchanged</td></tr>
<tr><td>best</td><td>Use the 'best' stem of each word according to some heuristic scoring.
This is the default setting</td></tr>
<tr><td>shortest</td><td>Use the shortest stem of each word</td></tr>
<tr><td>multiple</td><td>Use multiple stems. Retains all stems returned from the linguistics library</td></tr>
</tbody>
</table>
{% include note.html content="When combining multiple fields in a <a href='#fieldset'>fieldset</a>,
all fields should use the same stemming type."%}


<h2 id="normalizing">normalizing</h2>
<p>Contained in <a href="#field">field</a>.
Sets <a href="../../linguistics/linguistics-opennlp.html#normalization">normalizing</a> to be done on this field.
The default is to normalize.
<pre>
normalizing: [normalizing-type]
</pre>
<table class="table">
<thead>
<tr><th>Type</th><th>Description</th></tr>
</thead><tbody>
<tr><td>none</td><td>No normalizing.</td></tr>
</tbody>
</table>



<h2 id="dictionary">dictionary</h2>
<p>
    Contained in <a href="#field">field</a>,
    and specifies details of the dictionary used in the inverted index of the field.
    Applies only to <a href="#attribute">attributes</a> annotated with <code>fast-search</code>.
    You can specify either <code>btree</code> or <code>hash</code>, or both.
    If both are specified, btree is used for range/prefix and hash for exact lookups.
</p>

<h3>Dictionary Types</h3>
<p>
    <strong>btree</strong> (Default): Provides good performance for exact, prefix, and range lookups.
    Recommended for most use cases. Find more details in <a href="../../content/attributes.html#index-structures">attribute index structures</a>.
</p>

<p>
    <strong>hash</strong>: Optimized for fields with high cardinality (many unique values),
    such as unique ID fields where each posting list contains only one item.
</p>

<p>
    {% include note.html content='
    When using <code>hash</code>, prefix searches for strings and range searches for numeric fields
    will fall back to a full scan. This is primarily beneficial when you have many unique terms with
    few occurrences each, where dictionary lookup costs would otherwise be significant. '%}
</p>

<h3>Case Handling for String Fields</h3>
<p>
    For string attributes, you can specify how character case is handled:
</p>
<ul>
    <li><strong>uncased</strong> (Default): Case-insensitive - 'bear', 'Bear', and 'BEAR' are treated as identical</li>
    <li><strong>cased</strong>: Case-sensitive - 'bear', 'Bear', and 'BEAR' are treated as different terms</li>
</ul>
<p>
    This setting is automatically checked against the field's <a href="#match">match:casing</a> setting.
</p>

<h3>Important Rules for String Fields with Dictionaries</h3>
<p>
    <strong>For <code>btree</code> dictionaries</strong>: Both <code>cased</code> and <code>uncased</code> options are supported.
</p>
<p>
    <strong>For <code>hash</code> dictionaries</strong>: Only <code>cased</code> is supported for string fields. When using <code>hash</code> dictionaries:
</p>
<ul>
    <li>You <strong>must</strong> set <code>match: cased</code> on the field</li>
    <li>You <strong>must</strong> include <code>cased</code> in the dictionary block</li>
</ul>

<pre>
dictionary {
  hash    <!-- Specifies hash dictionary type -->
  cased   <!-- Required with hash for string fields -->
}
</pre>

<h3>Example: Case-Sensitive Hash Dictionary</h3>
<pre>
field id_str type string {
      indexing:   summary | attribute
      attribute:  fast-search  <!-- Enables dictionary functionality -->
      match:      cased        <!-- Required for hash dictionaries with strings -->
      rank:       filter
      dictionary {
        hash                   <!-- Use hash dictionary type -->
        cased                  <!-- Required for hash dictionaries with strings -->
      }
}
</pre>



<h2 id="attribute">attribute</h2>
<p>Contained in <a href="#field">field</a> or
<a href="#struct-field">struct-field</a>.
Specifies a property of an index structure attribute:
<pre>
attribute [attribute-name]: [property]
</pre>
or
<pre>
attribute [attribute-name] {
    [property]
    [property]
    &hellip;
}
</pre>
Read the <a href="../../content/attributes.html">introduction to attributes</a>.
If the attribute name is specified, it will be used instead of the field name as the name of the attribute.
{% include deprecated.html content="Deprecated, use a field with the wanted name outside the document instead."%}
Actions required when <a href="#modifying-schemas">adding or modifying attributes</a>. Properties:
<table class="table">
<thead>
<tr><th style="width:150px">Property</th><th>Description</th></tr>
</thead><tbody>
<tr><td>fast-search</td><td>Create a dictionary/index structure to speed up search in the attribute.
  <a href="../../content/attributes.html#index-structures">Read more</a>.</td></tr>
<tr><td>fast-access</td><td>
  If <a href="../applications/services/content.html#searchable-copies">searchable-copies</a> &lt;
  <a href="../applications/services/content.html#redundancy">redundancy</a>,
  use <em>fast-access</em> to load the attribute in memory on all nodes with a document replica.
  Use this for fast access when doing
  <a href="../../writing/reads-and-writes.html">partial updates</a> and when used in a
  <a href="../applications/services/content.html#documents">selection expression</a> for garbage collection.
  If <a href="../applications/services/content.html#searchable-copies">searchable-copies</a> ==
  <a href="../applications/services/content.html#redundancy">redundancy</a> (default), this property is a no-op.
  <a href="../../performance/sizing-feeding.html#redundancy-settings">Read more</a>.
</td></tr>
<tr><td>fast-rank</td><td>
  Only supported for <a href="../../ranking/tensor-user-guide.html">tensor</a> field types with at least one mapped dimension.
  Ensures that the per-document tensors are stored in-memory using a format that is more optimal for
  <a href="../ranking/ranking-expressions.html">ranking expression</a> evaluation. This comes at the cost of using more memory.
  Without this setting, these tensors are serialized in-memory,
  which requires deserialization as part of ranking expression evaluation.
  See <a href="../../performance/feature-tuning.html#tensor-ranking">tensor performance</a>.
</td></tr>
<tr><td>paged</td><td>
  This can reduce the memory footprint by allowing paging the attribute data out of memory to disk.
  Not supported for <a href="#tensor">tensor</a> with fast-rank and
  <a href="#predicate">predicate</a> types.
  See <a href="../../content/attributes.html#paged-attributes">paged attributes</a> for details.
  Do not enable <em>paged</em> before fully understanding the consequences.
</td></tr>
<tr><td><a href="#sorting">sorting</a></td><td>The sort specification for this attribute.</td></tr>
<tr><td><a href="#distance-metric">distance-metric</a></td>
<td>
  Specifies the distance metric to use with the <a href="../querying/yql.html#nearestneighbor">nearestNeighbor</a>
  query operator. Only relevant for tensor attribute fields.
</td></tr>
<tr><td>mutable</td><td><p id="mutable">Marks the attribute as a special mutable attribute that can be updated by a
  <a href="#mutate">mutate</a> operation during query evaluation.</p></td>
</tbody>
</table>
<p>
An attribute is <a href="../../querying/searching-multivalue-fields">multivalued</a>
if assigning it multiple values during indexing,
by using a multivalued field type like array or map,
or by using e.g. <a href="../writing/indexing-language.html#split">split</a> /
<a href="../writing/indexing-language.html#for_each">for_each</a>
or by letting multiple fields write their value to the attribute field.
</p><p>
Note that <a href="#normalizing">normalizing</a> and
<a href="../../linguistics/linguistics-opennlp.html#tokenization">tokenization</a>
is not supported for attribute fields.
</p><p>
Queries in attribute fields are not normalized, nor stemmed.
Use <a href="#index">index</a> on fields to enable.
Both <em>index</em> and <em>attribute</em> can be set on a field.
</p>



<h2 id="sorting">sorting</h2>
<p>
Contained in <a href="#attribute">attribute</a> or
<a href="#field">field</a>.
Specifies how sorting should be done.
<pre>
sorting : [property]
</pre>
or
<pre>
sorting {
    [property]
    &hellip;
}
</pre>
<table class="table">
  <thead>
    <tr><th>Property</th><th>Description</th></tr>
  </thead><tbody>
    <tr>
      <td>order</td>
      <td>
        <code>ascending</code> (default) or <code>descending</code>.
        Used unless overridden using <a href="../querying/yql.html#function">order by</a> in query.
      </td>
    </tr>
    <tr>
      <td>function</td>
      <td>
        <a href="../querying/yql.html#function">Sort function</a>:
        <code>uca</code> (default), <code>lowercase</code> or <code>raw</code>.
        Note that if no language or locale is specified in the query, the field,
        or generally for the query, <code>lowercase</code> will be used instead of <code>uca</code>.
        See <a href="../querying/yql.html#order-by">order by</a> for details.
      </td>
    </tr>
    <tr>
      <td>strength</td>
      <td>
        <a href="../querying/yql.html#strength">UCA sort strength</a>, default <code>primary</code> -
        see <a href="../querying/yql.html#strength">strength</a> for values.
        Values set in the query override the schema definition.
      </td>
    </tr>
    <tr>
      <td>locale</td>
      <td>
        <a href="../querying/yql.html#locale">UCA locale</a>, default none,
        indicating that it is inferred from the query.
        It should only be set here if the attribute is filled with data in one language only.
        See <a href="../querying/yql.html#locale">locale</a> for details.
        Values set in the query override the schema definition.
      </td>
    </tr>
  </tbody>
</table>



<h2 id="distance-metric">distance-metric</h2>
<p>
  Specifies the distance metric to use with the <a href="../querying/yql.html#nearestneighbor">nearestNeighbor</a>
  query operator to calculate the distance between document positions and the query position.
  Only relevant for tensor attribute fields, where each tensor holds one or multiple vectors.
</p>
<p>
  Which distance metric to use depends on the model used to produce the vectors;
  it must match the distance metric used during representation learning (model learning).
  If you are using an "off-the-shelf" model to vectorize your data, please ensure
  that the distance metric matches the distance metric suggested for use with the model.
  Different types of vectorization models use different types of distance metrics.
</p>
{% include important.html content="When changing the <code>distance-metric</code> or <code>max-links-per-node</code>,
the content nodes must be restarted to rebuild the HNSW index - see
<a href='#changes-that-require-restart-but-not-re-feed'>changes that require restart but not re-feed</a>"%}
<p>
  The calculated distance will be used to
  select the closest hits for <em>nearestNeighbor</em> query operator, but also to
  build the <a href="../../querying/approximate-nn-hnsw">HNSW</a> index (if specified) and
  to produce the <a href="../ranking/rank-features.html#distance(dimension,name)">distance</a> and
  <a href="../ranking/rank-features.html#closeness(dimension,name)">closeness</a> ranking features.
</p>
<p>
<pre>
distance-metric: [metric]
</pre>
These are the available metrics; the expressions given for <em>distance</em> and <em>closeness</em>
assume a query vector <em>qv = [x0, x1, ...]</em> and an attribute vector <em>av = [y0, y1, ...]</em>
with same dimension of size <em>n</em> for all vectors.
<p>
<table class="table">
<thead>
  <tr><th>Metric</th><th>Description</th><th>distance</th><th>closeness</tr>
</thead>
<tbody>
  <tr>
    <td>euclidean</td>
    <td>The normal <a href="#euclidean">euclidean</a> (aka L2) distance.</td>
    <td>
    <math xmlns="http://www.w3.org/1998/Math/MathML" display="inline">
        <mrow mathsize="120%">
          <mi>d</mi><mo>=</mo><msqrt>
            <mrow>
              <munder><mo>∑</mo><mi>n</mi></munder>
              <msup>
                <mrow>
                  <mo>(</mo>
                  <msub><mi>x</mi><mi>i</mi></msub>
                  <mo>-</mo>
                  <msub><mi>y</mi><mi>i</mi></msub>
                  <mo>)</mo>
                </mrow>
                <mn>2</mn>
              </msup>
            </mrow>
          </msqrt>
        </mrow>
    </math>
    with range: <code>[0,inf)</code></td>
    <td>
    <math xmlns="http://www.w3.org/1998/Math/MathML" display="inline">
    <mfrac><mn>1.0</mn><mrow><mn>1.0</mn><mo>+</mo><mi>d</mi></mrow></mfrac>
    </math>
    </td>
  </tr>
  <tr>
    <td>angular</td>
    <td>The <a href="#angular">angle</a> between <em>qv</em> and <em>av</em> vectors.</td>
    <td>
    <math xmlns="http://www.w3.org/1998/Math/MathML" display="inline">
        <mrow mathsize="120%">
          <mi>d</mi><mo>=</mo>
          <msup><mo>cos</mo><mn>-1</mn></msup><mo>(</mo>
          <mfrac>
            <mrow>
              <mover><mi>q</mi><mo>&#x2192;</mo></mover>
              <mo>&#x22C5;</mo>
              <mover><mi>a</mi><mo>&#x2192;</mo></mover>
            </mrow>
            <mrow>
              <mo>|</mo> <mover><mi>q</mi><mo>&#x2192;</mo></mover> <mo>|</mo>
              <mo>&#x22C5;</mo>
              <mo>|</mo> <mover><mi>a</mi><mo>&#x2192;</mo></mover> <mo>|</mo>
            </mrow>
          </mfrac>
            <mo>)</mo>
        </mrow>
    </math>
    with range: <code>[0,pi]</code></td>
    <td>
    <math xmlns="http://www.w3.org/1998/Math/MathML" display="inline">
    <mfrac><mn>1.0</mn><mrow><mn>1.0</mn><mo>+</mo><mi>d</mi></mrow></mfrac>
    </math>
    </td>
  </tr>
  <tr>
    <td>dotproduct</td>
    <td>Used for <a href="#dotproduct">maximal inner product search</a>.</td>
    <td>
    <math xmlns="http://www.w3.org/1998/Math/MathML" display="inline">
        <mrow mathsize="120%">
          <mi>d</mi><mo>=</mo>
          <mo>-</mo><mo>(</mo>
            <mrow>
              <mover><mi>q</mi><mo>&#x2192;</mo></mover>
              <mo>&#x22C5;</mo>
              <mover><mi>a</mi><mo>&#x2192;</mo></mover>
            </mrow>
            <mo>)</mo>
        </mrow>
    </math>
    with range: <code>[-inf,+inf]</code></td>
    <td>
    <math xmlns="http://www.w3.org/1998/Math/MathML" display="inline">
        <mrow>
          <mo>-</mo><mi>d</mi><mo>=</mo>
          <mover><mi>q</mi><mo>&#x2192;</mo></mover>
          <mo>&#x22C5;</mo>
          <mover><mi>a</mi><mo>&#x2192;</mo></mover>
        </mrow>
    </math>
    </td>
  </tr>
  <tr>
    <td>prenormalized-angular</td>
    <td>Assumes normalized vectors, see <a href="#prenormalized-angular">note</a> below.</td>
    <td>
    <math xmlns="http://www.w3.org/1998/Math/MathML" display="inline">
        <mrow mathsize="120%">
          <mi>d</mi><mo>=</mo>
          <mn>1.0</mn><mo>-</mo><mo>(</mo>
          <mfrac>
            <mrow>
              <mover><mi>q</mi><mo>&#x2192;</mo></mover>
              <mo>&#x22C5;</mo>
              <mover><mi>a</mi><mo>&#x2192;</mo></mover>
            </mrow>
            <msup>
              <mrow>
                <mo>|</mo> <mover><mi>q</mi><mo>&#x2192;</mo></mover> <mo>|</mo>
              </mrow>
              <mn>2</mn>
            </msup>
          </mfrac>
          <mo>)</mo>
        </mrow>
    </math>
    with range: <code>[0,2]</code></td>
    <td>
    <math xmlns="http://www.w3.org/1998/Math/MathML" display="inline">
    <mfrac><mn>1.0</mn><mrow><mn>1.0</mn><mo>+</mo><mi>d</mi></mrow></mfrac>
    </math>
    </td>
  </tr>
  <tr>
    <td>geodegrees</td>
    <td>Assumes geographical coordinates, see <a href="#geodegrees">note</a> below.</td>
    <td>
    <math xmlns="http://www.w3.org/1998/Math/MathML" display="inline">
        <mrow mathsize="120%">
          <mi>d</mi><mo>=</mo>
        </mrow>
    </math> great-circle in km; range: <code>[0,20015]</code></td>
    <td>
    <math xmlns="http://www.w3.org/1998/Math/MathML" display="inline">
    <mfrac><mn>1.0</mn><mrow><mn>1.0</mn><mo>+</mo><mi>d</mi></mrow></mfrac>
    </math>
    </td>
  </tr>
  <tr>
    <td>hamming</td>
    <td>Only useful for binary tensors using &lt;int8&gt; precision, see <a href="#hamming">note</a> below.</td>
    <td>
    <math xmlns="http://www.w3.org/1998/Math/MathML" display="inline">
        <mrow mathsize="120%">
          <mi>d</mi><mo>=</mo>
            <munder><mo>∑</mo><mi>n</mi></munder>
            <mi>popcount</mi>
            <mo>(</mo>
                  <msub><mi>x</mi><mi>i</mi></msub>
                  <mo>XOR</mo>
                  <msub><mi>y</mi><mi>i</mi></msub>
            <mo>)</mo>
        </mrow>
    </math>
    ; range: <code>[0,8*n]</code></td>
    <td>
    <math xmlns="http://www.w3.org/1998/Math/MathML" display="inline">
    <mfrac><mn>1.0</mn><mrow><mn>1.0</mn><mo>+</mo><mi>d</mi></mrow></mfrac>
    </math>
    </td>
  </tr>
</tbody>
</table>

<h3 id="euclidean">euclidean</h3>
<p>
  The default metric is <a href="https://en.wikipedia.org/wiki/Euclidean_distance">Euclidean distance</a>
  which is just the length of a line segment between the two points.
  To compute the Euclidean distance directly in a ranking expression
  instead of fetching one already computed in a nearestNeighbor query
  operator, use the
  <a href="../ranking/ranking-expressions.html#euclidean-distance-t">
  Euclidean_distance helper function</a>:
</p>
<pre>
    function mydistance() {
        expression: euclidean_distance(attribute(myembedding), query(myqueryvector), mydim))
    }
</pre>


<h3 id="angular">angular</h3>
<p>
  The <em>angular</em> distance metric computes the <em>angle</em> between the vectors.
  Its range is <code>[0,pi]</code>, which is the angular distance.
  This is also known as ordering by
  <a href="https://en.wikipedia.org/wiki/Cosine_similarity">cosine similarity</a>
  where the score function is just the cosine of the angle.
  To compute the angular distance directly in a ranking expression, use the
  <a href="../ranking/ranking-expressions.html#cosine-similarity-t">
  cosine_similarity helper function</a>:
<pre>
    function angle() {
        expression: acos(cosine_similarity(attribute(myembedding), query(myqueryvector), mydim))
    }
</pre>
  Conversely, the cosine similarity can be recovered from the
  <a href="../ranking/rank-features.html#distance(dimension,name)">distance rank-feature</a>
  when using a nearestNeighbor query operator:
<pre>
    rank-profile cosine {
        first-phase {
            expression: cos(distance(field, myembedding))
        }
    }
</pre>
  If possible, it's slightly better for performance to normalize both query and document vectors to the same
  L2 norm and use the <code>prenormalized-angular</code> metric instead; but note that returned
  distance and closeness will be different.

<h3 id="dotproduct">dotproduct</h3>
<p>
  The <em>dotproduct</em> distance metric is used to <em>mathematically
  transform</em> a "maximum inner product" search into a form where
  it can be solved by nearest neighbor search, where the dotproduct
  is used as a score directly (large positive dotproducts are
  considered "nearby").
  Internally, an extra dimension is added (ensuring that all vectors
  are normalized to the same length) and a distance similar to
  <em>prenormalized-angular</em> is used to build the HNSW index.
  For details, see
  <a href="https://towardsdatascience.com/maximum-inner-product-search-using-nearest-neighbor-search-algorithms-c125d24777ef">
  this high level guide</a> based on
  <a href="https://www.microsoft.com/en-us/research/wp-content/uploads/2016/02/XboxInnerProduct.pdf">
  section 3.1 Order Preserving Transformations in this paper</a>.
</p>
<p>
  Note that the <em>distance</em> and <em>closeness</em> rank-features will not have the
  usual semantic meanings when using the <em>dotproduct</em> distance metric.
  In particular, <em>closeness</em> will just return the dot product
    <math xmlns="http://www.w3.org/1998/Math/MathML" display="inline">
        <mrow>
          <munder><mo>∑</mo><mi>n</mi></munder>
          <mrow>
            <mo>(</mo>
            <msub><mi>x</mi><mi>i</mi></msub>
            <mo>*</mo>
            <msub><mi>y</mi><mi>i</mi></msub>
            <mo>)</mo>
          </mrow>
        </mrow>
    </math>
  which may have any negative
  or positive value, and <em>distance</em> is just the negative dot product.
  If a normalized closeness in range <code>[0,1]</code> is needed, an appropriate
  <a href="https://en.wikipedia.org/wiki/Sigmoid_function">sigmoid function</a> must be applied.
  For example, if your attribute is named "foobar", and the maximum dotproduct seen is around 4000, the expression
  <code>sigmoid(0.001*closeness(field,foobar))</code>
  could be a possible choice.
</p>
<p>
  The <em>dotproduct</em> distance metric is useful for some vectorization
  models, including matrix factorization, that use "maximum inner
  product" (MIP), with vectors that aren't normalized.
  These models use both direction and magnitude.
</p>

<h3 id="prenormalized-angular">prenormalized-angular</h3>
<p>
  The <em>prenormalized-angular</em> distance metric
  <strong>must only be used</strong> when <strong>both</strong> query and document vectors are normalized.
  This metric was previously named "innerproduct" and required unit-length vectors.
  The new version computes the length of the query vector once and
  assumes all other vectors are of the same length.
</p>
<p>
  Using <em>prenormalized-angular</em> with vectors that are not
  normalized causes unpredictable nearest neighbor search, and is
  observed to give bad results both for performance and quality.
</p>
<p>
  The length, magnitude, or norm of a vector <em>x</em> is calculated as <code>length = sqrt(sum(pow(xi,2)))</code>.
  The unit length normalized vector is then given by <code>[xi/length]</code>.
  Zero vectors may not be used at all.
</p>
<p>
  The Vespa <em>prenormalized-angular</em> computes the
  <a href="https://en.wikipedia.org/wiki/Cosine_similarity">cosine similarity</a>
  and uses <code>1.0 - cos(angle)</code> as the distance metric.
  It gives exactly the same ordering as <code>angular</code> distance,
  but with a distance in the range [0,2], since cosine similarity has range [1,-1],
  so the end result is 0.0 for same direction vectors,
  1.0 for a right angle, and 2.0 for vectors with exactly opposite directions.
  Getting the cosine score (or angle) is therefore easy:
</p>
<pre>
    rank-profile cosine {
        first-phase {
          expression: 1.0 - distance(field, embedding)
        }
        function angle() {
          expression: acos(1.0 - distance(field, embedding))
        }
    }
</pre>
  To compute the cosine similarity directly in a ranking expression
  instead of fetching one already computed in a nearestNeighbor query
  operator, use the
  <a href="../ranking/ranking-expressions.html#cosine-similarity-t">
  cosine_similarity helper function</a>:
<pre>
    function mysimilarity() {
        expression: cosine_similarity(attribute(myembedding), query(myqueryvector), mydim))
    }
</pre>


<h3 id="geodegrees">geodegrees</h3>
<p>
  The <em>geodegrees</em> distance metric is only valid for
  geographical coordinates (two-dimensional vectors containing
  latitude and longitude on Earth, in degrees).  It computes the
  great-circle distance (in kilometers) between two geographical
  points using the
  <a href="https://en.wikipedia.org/wiki/Haversine_formula">Haversine formula</a>.
  See
  <a href="https://github.com/vespa-engine/system-test/blob/master/tests/search/nearest_neighbor/geo.sd">geodegrees system test</a>
  for an example.
</p>

<h3 id="hamming">hamming</h3>
<p>
  The <a href="https://en.wikipedia.org/wiki/Hamming_distance">Hamming distance</a>
  metric counts the number of dimensions where the vectors have different coordinates.
  This isn't useful for floating-point data since it means you only
  get 1 bit of information from each floating-point number.
  Instead, it should be used for binary data, where each bit is
  considered a separate coordinate.  Practically, this means you
  should use the
  <code>int8</code> <a href="../../performance/feature-tuning.html#cell-value-types">cell value type</a>
  for your tensor, with the usual encoding from bit pattern to numerical value, for example:
</p>
  <ul>
      <li><code>00000000</code> &rarr;    <code>0</code> (hex <code>00</code>)</li>
      <li><code>00010001</code> &rarr;   <code>17</code> (hex <code>11</code>)</li>
      <li><code>00101010</code> &rarr;   <code>42</code> (hex <code>2A</code>)</li>
      <li><code>01111111</code> &rarr;  <code>127</code> (hex <code>7F</code>)</li>
      <li><code>10000000</code> &rarr; <code>-128</code> (hex <code>80</code>)</li>
      <li><code>10000001</code> &rarr; <code>-127</code> (hex <code>81</code>)</li>
      <li><code>11111110</code> &rarr;   <code>-2</code> (hex <code>FE</code>)</li>
      <li><code>11111111</code> &rarr;   <code>-1</code> (hex <code>FF</code>)</li>
  </ul>
<p>
  Feeding data for this use case may be done with
  <a href="document-json-format.html#tensor-hex-dump">"hex dump"</a> format
  instead of numbers in range <code>[-128,127]</code> both to have a more natural format
  for representing binary data, and to avoid the overhead of parsing a large JSON array of numbers.
</p>



<h2 id="bolding">bolding</h2>
<p>
Contained in <a href="#field">field</a> or <a href="#summary">summary</a>.
Highlight matching query terms in the <a href="#summary">summary</a>:
<pre>
bolding: on
</pre>
<p>
  The default is no bolding, set <code>bolding: on</code> to enable it.
  Note that this command is overridden by <code>summary: dynamic</code>.
  If both are specified, bolding will be ignored.
  The difference between using bolding instead of <code>summary: dynamic</code>
  is the latter will provide a dynamic abstract in addition to highlighting query terms,
  while the first only highlights.
  Bolding is only supported for <a href="#indexing-index">index</a> fields of type string or array&lt;string&gt;.
</p>
<p>
  The default XML element used to highlight the search terms is &lt;hi&gt; -
  to override, set <em>container.qr-searchers</em> configuration. Example using <code>&lt;strong&gt;</code>:
</p>
<pre>{% highlight xml %}
<container>
    <search>
        <config name="container.qr-searchers">
            <tag>
                <bold>
                    <open>&lt;strong&gt;</open>
                    <close>&lt;/strong&gt;</close>
                </bold>
                <separator>...</separator>
            </tag>
        </config>
    </search>
</container>
{% endhighlight %}</pre>
<p>
  Maximum field byte length for bolding is 64Mb -
  field values larger than this will be represented as a snippet as in <code>summary: dynamic</code>.
</p>



<h2 id="id">id</h2>
<p>
Contained in <a href="#field">field</a>.
Sets the numerical ID of this field.
All fields have a document-internal ID internally for transfer and storage.
IDs are usually determined programmatically as a 31-bit number.
Some storage and transfer space can be saved by instead explicitly setting IDs to a 7-bit number.
<!-- ToDo: check if this applies to proton -->
<pre>
id: [positive integer]
</pre>
<p>An ID must satisfy these requirements:</p>
<ul>
<li>Must be a positive integer</li>
<li>Must be less than 100 or larger than 127</li>
<li>Must be unique within the document and all documents this document inherits</li>
</ul>



<h2 id="index">index</h2>
<p>
Contained in <a href="#field">field</a> or <a href="#schema">schema</a>.
Sets index parameters.
</p>
<p>
  Content in <a href="#string">string</a>-fields with <em>index</em> is <a href="#normalizing">normalized</a> and
  <a href="../../linguistics/linguistics-opennlp.html#tokenization">tokenized</a> by default.
  The field can be single- or multivalued (e.g. <code>array&lt;string&gt;</code>).
</p>
<p>
  For <a href="#tensor">tensor</a>-typed fields, <em>index</em> creates an <a href="#index-hnsw">HNSW</a> index
  for <a href="../../querying/nearest-neighbor-search-guide">Approximate Nearest Neighbor</a> queries,
  with a default <a href="#euclidean">euclidean</a> distance metric.
  The index is built after a <a href="#changes-that-require-restart-but-not-re-feed">content node restart</a> (automated on Vespa Cloud).
</p>
<p>Examples:</p>
<pre>
index [index-name]: [property]
</pre>
or
<pre>
index [index-name] {
    [property]
    [property]
    &hellip;
}
</pre>

{% include deprecated.html content='
If <code>index-name</code> is specified, it will be used instead of the field name as the name of the index.
This use is deprecated, use a synthetic field with the wanted name outside the <code>document</code> block instead -
see an <a href="/en/writing/indexing.html#date-indexing">example</a>.'%}

Parameters:
<table class="table">
  <thead>
  <tr><th>Property</th><th>Occurrence</th><th>Description</th></tr>
  </thead><tbody>
<tr><td><a href="#stemming">stemming</a></td>
  <td>Zero to one</td>
  <td>Set the stemming of this index.
    Indexes without a stemming setting get their stemming setting from
    the fields added to the index. Setting this explicitly is useful if
    fields with conflicting stemming settings are added to this index.</td>
</tr>
<tr><td>arity</td>
  <td>One (mandatory for predicate fields), else zero.</td>
  <td>Set the
    <a href="../../schemas/predicate-fields.html#index-size">arity value for a predicate field</a>.
    The data type for the containing field must be <code>predicate</code>.</td>
</tr>
<tr><td>lower-bound</td>
  <td>Zero to one</td>
  <td>Set the
    <a href="../../schemas/predicate-fields.html#upper-and-lower-bounds">lower bound value for a predicate field</a>.
    The data type for the containing field must be <code>predicate</code>.</td>
</tr>
<tr><td>upper-bound</td>
  <td>Zero to one</td>
  <td>Set the
    <a href="../../schemas/predicate-fields.html#upper-and-lower-bounds">upper bound value for predicate fields</a>.
    The data type for the containing field must be <code>predicate</code>.</td>
</tr>
<tr><td style="white-space: nowrap">dense-posting-list-threshold</td>
  <td>Zero to one</td>
  <td>Set the
    <a href="../../schemas/predicate-fields.html#dense-posting-list-threshold">dense posting list threshold value for predicate fields</a>.
    The data type for the containing field must be <code>predicate</code>.</td>
</tr>
<tr><td>enable-bm25</td>
  <td>Zero to one</td>
  <td>Enable this index field to be used with the
    <a href="../ranking/rank-features.html#bm25">bm25 rank feature</a>.
    This creates posting lists for the
    <a href="../../content/proton.html#index">indexes</a>
    for this field that has interleaved features in the document id streams.
    This makes it fast to compute the <em>bm25</em> score.
    See the <a href="/en/ranking/bm25.html">BM25 reference</a> for details and example use.
  </td>
</tr>
<tr><td><a href="#index-hnsw">hnsw</a></td>
  <td>Zero to one</td>
  <td>
    Specifies optional parameters for an HNSW index to enable faster, approximate nearest neighbor search.
    Only supported for tensor attribute fields with tensor types with:
    <ul>
      <li>One indexed dimension - single vector per document</li>
      <li>One or more mapped dimensions and one indexed dimension - multiple vectors per document</li>
    </ul>
    Used in combination with the
    <a href="../querying/yql.html#nearestneighbor">nearestNeighbor</a>
    query operator.
  </td>
</tr>
</tbody>
</table>



<h2 id="index-hnsw">hnsw</h2>
<p>
Contained in <a href="#index">index</a>.
Specifies optional parameters for an HNSW index to enable faster, approximate nearest neighbor search
using the <a href="../querying/yql.html#nearestneighbor">nearestNeighbor</a> query operator.

{% include note.html content="Specifying the <code>index</code> keyword in the <a href='#indexing'>indexing</a> statement of a tensor creates an HNSW index with default settings, even if this block is not specified! "%}

This implements a modified version of the
Hierarchical Navigable Small World (HNSW) graphs algorithm (<a href="https://arxiv.org/abs/1603.09320">paper</a>).
</p>
<p>Only supported for the following tensor attribute field types:</p>
<ul>
    <li>Single vector per document: Tensor type with one indexed dimension.
        Example: <code>tensor&lt;float&gt;(x[3])</code></li>
    <li>Multiple vectors per document: Tensor type with one or more mapped dimensions and one indexed dimension.
        Examples: <code>tensor&lt;float&gt;(m{},x[3])</code>, <code>tensor&lt;float&gt;(m{},n{},x[3])</code></li>
</ul>
<p>
HNSW indexes are not supported in
<a href="../../performance/streaming-search.html#differences-in-streaming-search">streaming search</a>.
</p>
<pre>
hnsw {
    [parameter]: [value]
    [parameter]: [value]
    ...
}
</pre>
<p>The following parameters are used when building the index graph:</p>
<table class="table">
<thead>
  <tr><th>Parameter</th><th>Description</th></tr>
</thead>
<tbody>
  <tr>
    <td>max-links-per-node</td>
    <td>
    Specifies how many links per HNSW node to select when building the graph. The default value is 16.
    In <a href="https://github.com/nmslib/hnswlib/blob/master/ALGO_PARAMS.md">HNSWlib</a> (implementation based on the paper)
    this parameter is known as <em>M</em>.
    </td>
  </tr>
  <tr>
    <td>neighbors-to-explore-at-insert</td>
    <td>
    Specifies how many neighbors to explore when inserting a document in the HNSW graph. The default value is 200.
    In HNSWlib, this parameter is known as <em>ef_construction</em>.
    </td>
  </tr>
</tbody>
</table>
<p>
  The <a href="#distance-metric">distance metric</a> specified on the <em>attribute</em>
  is used when building and searching the graph. Example:
<pre>
field text_embedding type tensor&lt;float&gt;(x[384]) {
    indexing: summary | attribute | index
    attribute {
        distance-metric: prenormalized-angular
    }
    index {
        hnsw {
            max-links-per-node: 24
            neighbors-to-explore-at-insert: 200
        }
    }
}
</pre>
<p>
See
<a href="../../querying/approximate-nn-hnsw">Approximate Nearest Neighbor Search using HNSW Index</a>
for examples of use, and see
<a href="https://blog.vespa.ai/approximate-nearest-neighbor-search-in-vespa-part-1/">
Approximate Nearest Neighbor Search in Vespa - Part 1</a> blog post
for how the Vespa team selected HNSW as the baseline algorithm for extension and integration in Vespa.
</p>


<h2 id="indexing">indexing</h2>
<p>
Contained in <a href="#field">field</a> or
<a href="#struct-field">struct-field</a>.
One or more Indexing Language instructions used to produce index, attribute
and summary data from this field. Indexing instructions have pipeline
semantics similar to Unix shell commands. The value of the field
enters the pipeline during indexing, and the pipeline puts the value
into the desired index structures, possibly doing transformations and
pulling in other values along the way.
<pre>
indexing: [index-statement]
</pre>
or
<pre>
indexing {
    [indexing-statement];
    [indexing-statement];
    &hellip;
}
</pre>
<p>
If the field containing this is defined outside the document, it
must start with an indexing statement which
outputs a value (either "input [fieldname]" to fetch a field value,
or a literal, e.g, "some-value" ). Fields in documents will use the value of the enclosing
field as input (input [fieldname]) if one isn't explicitly provided.
</p>
<p>
Specify the operations separated by the pipe (<code>|</code>) character.
For advanced processing needs,
use the <a href="../writing/indexing-language.html">indexing language</a>,
or write a <a href="../../applications/document-processors.html"> document processor</a>.
Supported expressions for fields are:
</p>
<table class="table">
<thead>
<tr>
  <th>expression</th>
  <th>description</th>
</tr>
</thead><tbody>
<tr><td>attribute</td>
<td>
<p id="indexing-attribute">
  <a href="../../content/attributes.html">Attribute</a> is used to make a field available for sorting,
  grouping, ranking and searching using <a href="#match">match</a> mode <code>word</code>.
</p>
</td></tr>
<tr><td>index</td>
<td>
  <p id="indexing-index">
  Creates a searchable <a href="../../content/proton.html#index">index</a> for the values of this field
  using <a href="#match">match</a> mode <code>text</code>.
  By default, the index name will be the same as the name of the schema field.
  Use a <a href="#fieldset">fieldset</a> to combine fields in the same set for searching.
  </p>
</td></tr>
<tr><td>set_language</td>
<td>
  Sets document language - <a href="../writing/indexing-language.html#set_language">details</a>.
</td></tr>
<tr><td>summary</td>
<td>
  Includes the value of this field in a <a href="../writing/indexing-language.html#summary">summary</a> field.
  Modify summary output by using <a href="#summary">summary:</a> (e.g., to generate dynamic teasers).
</td></tr>
</tbody>
</table>
<p>
When combining both <code>index</code> and <code>attribute</code> in the indexing statement for a field,
e.g <code>indexing: summary | attribute | index</code>,
the <a href="#match">match</a> mode becomes <code>text</code> for the field.
So searches in this field will not search the contents in the <a href="#attribute">attribute</a> but the index.
</p>
<p>Find examples and more details in the <a href="../../querying/text-matching.html">Text Matching</a> guide.</p>



<h2 id="linguistics">linguistics</h2>
<p>Sets a linguistics 'profile' deciding how content and searches against this field should be linguistically processed.
The profile value is propagated to the <a href="../../linguistics/linguistics.html">linguistics component</a>
which can be configured to do profile-specific processing.</p>
<pre>
linguistics {
    profile: myIndexAndSearchProfile
}
</pre>
or
<pre>
linguistics {
    profile {
        index: myIndexProfile
        search: mySearchProfile
    }
}
</pre>



<h2 id="match">match</h2>
<p>Contained in <a href="#field">field</a>, <a href="#fieldset">fieldset</a> or
<a href="#struct-field">struct-field</a>.
Sets the matching method to use for this field to something other than the default token matching.
<pre>
match: [property]
</pre>
or
<pre>
match {
    [property]
    [property]
    &hellip;
}
</pre>
<p>
Whether the match type is <code>text</code>, <code>word</code> or <code>exact</code>,
all term matching will be done after <a href="../../linguistics/linguistics-opennlp.html#normalization">normalization</a>
and locale-independent lowercasing (in that order).
</p><p>
Find examples and more details in the <a href="../../querying/text-matching.html">Text Matching</a> guide.
Also see search using <a href="../querying/yql.html#matches">regular expressions</a>.
</p>
<table class="table">
<thead>
<tr><th>Property</th><th>Valid with</th><th>Description</th></tr>
</thead><tbody>
<tr><td>text</td>
<td>index</td>
<td><p>
  The default for string fields with <code>index</code>. Can not be combined with exact matching.
  The field is matched per <a href="../../linguistics/linguistics-opennlp.html#tokenization">token</a>.
</p></td>
</tr>

<tr><td>exact</td>
<td>index, attribute</td>
<td><p id="exact">
  Can not be combined with <em>text</em> matching.
  </p><p>
  The field is matched <em>exactly</em>:
  Strings containing any characters whatsoever will be indexed and matched as-is.
  Lowercasing is still performed unless <code>match: cased</code> is also used.
  In queries, the exact match string ends at the exact match terminator (below).
  </p><p>
  A field with <code>match: exact</code> is considered to be
  a <a href="#filter">filter field</a>, just as if <code>rank: filter</code> was specified.
  This is because there is only one word per field
  (or per item in the case of multivalued types such as <code>array&lt;string&gt;</code>),
  so there is little ranking information.
  Turn off the implicit <code>rank: filter</code> by adding <code>rank: normal</code>.
</p></td>
</tr>

<tr><td style="white-space:nowrap;">exact-terminator</td>
<td>index, attribute</td>
<td><p id="exact-terminator">
  Only valid for <code>match: exact</code>. Default is <code>@@</code>.
  Specify terminator in <a href="../api/query.html#model.querystring">query strings</a>.
  If the query strings can contain <code>@@</code>, set a different terminator,
  or use <code>match: word</code>, see below. Example - use:
<pre>
match {
    exact
    exact-terminator: "@%"
}
</pre>
<p>
  on a field called <code>tag</code> to make query <code>tag:a b c!@%</code>
  match documents with the string <em>a b c!</em>
</p><p>
  Example using the default terminator: If <code>tag</code> is an exact match field, the query:
<pre>
someword AND (tag:!*!@@ OR tag:(kanoo)@@)
</pre>
  matches documents with <code>someword</code>
  and either <code>!*!</code> or <code>(kanoo)</code> as a tag.
  Note that without the <code>@@</code> terminating the second tag string,
  the second tag value would be <code>(kanoo))</code>.
  </td>
</tr>

<tr><td>word</td>
<td>index, attribute</td>
<td><p id="word">
  This is the default matching mode for <a href="../../content/attributes.html">string attributes</a>.
  It cannot be combined with <em>text</em> matching.
  </p><p>
  Match word means that the entire content of the field is indexed as a single word.
  </p><p>
  Word matching is like exact matching, but with more advanced query parsing.
  The query terms are heuristically parsed, taking into account some usual query syntax characters.
  One can also use double quotes to include spaces, stars, or exclamation marks.
  </p><p>
  Example: If <code>artist</code> is a string attribute, the query:
<pre>
foo AND (artist:"'N Sync" OR artist:"*NSYNC" OR artist:A*teens OR artist:"Wham!")
</pre>
  <p>
  matches documents with <code>foo</code> and at least one of
  <code>'N Sync</code> or <code>*NSYNC</code> or <code>A*teens</code> or <code>Wham!</code>
  in the artist field
  </p><p>
  Note that without the quotes, the space in <code>'N Sync</code> would end that word
  and would result in a search for just <code>'N</code>,
  similarly the <code>!</code> would mean to increase the weight of a <code>Wham</code> term if not quoted.
</p></td>
</tr>

<tr><td>prefix</td>
<td>attribute</td>
<td><p id="prefix">
  Has no effect, as <a href="../../content/attributes.html">attributes</a>
  always support prefix searches. Prefix matching must be
  <a href="../querying/yql.html#prefix">specified in the query</a>.
  See also <a href="../querying/yql.html#matches">regular expressions</a>.
</p></td>
</tr>

<tr><td>substring</td>
    <td><a href="../../performance/streaming-search.html">Streaming mode</a> only</td>
    <td><p id="substring">
        Set default match mode to <em>substring</em> for the field.
        Only available in streaming search.
        As the data structures in streaming search support substring searches,
        one can always set substring matching in the query,
        without setting the field to the substring default.
        Also see <a href="../querying/yql.html#matches">regular expressions</a>.
    </p></td>
</tr>

<tr><td>suffix</td>
    <td><a href="../../performance/streaming-search.html">Streaming mode</a> only</td>
    <td><p id="suffix">
        Like substring above.
    </p></td>
</tr>

<tr><td>uncased</td>
    <td>index, attribute</td>
    <td><p id="uncased">
        Use case-insensitive matching (the default).
    </p></td>
</tr>

<tr><td>cased</td>
<td>index, attribute</td>
<td><p id="cased">
  Use case-sensitive matching. Usually only used together
  with <code>match: exact</code> or <code>match: word</code> modes.
  When using <code>match: text</code>, note that if you are using a custom
  <a href="../../linguistics/linguistics-custom.html">linguistics implementation</a>,
  this will only have effect for string index fields if that implementation produces cased tokens.
</p></td>
</tr>

<tr><td>max-length</td>
<td>index</td>
<td><p id="max-length">
  Limit the length of the field that will be used for matching.
  By default, only the first 1M characters are indexed.
</p><p>
  When adjusting this limit, it might also be needed to adjust
  <a href="#max-occurrences">max-occurrences</a>.
</p></td>
</tr>

<tr><td>max-occurrences</td>
<td>index</td>
<td><p id="max-occurrences">
  Configure the maximum number of occurrences that will be indexed for
  each unique token/term in the field for a given document.
  If this limit is reached, consecutive occurrences
  of the same token/term are ignored for that document.
  The default value is 10000.
</p><p>
  Adjusting this limit might be needed when using the
  <a href="../querying/yql.html#phrase">phrase</a>,
  <a href="../querying/yql.html#near">near</a>, or
  <a href="../querying/yql.html#onear">onear</a>
  query operators
  to query documents with large field values (see <a href="#max-length">max-length</a>)
  that contain more than 10000 occurrences of common tokens/terms.
  When using these operators, it is only possible to match among the
  first <em>max-occurrences</em> of a token/term in a document.
</p></td>
</tr>

<tr><td>max-token-length</td>
<td>index</td>
<td><p id="max-token-length">
  Configure the max length of tokens that will be indexed for the field.
  Longer tokens are silently ignored.
  The unit is characters (cf. java.lang.String.length()).
  The default value is 1000.
</p></td>
</tr>

<tr><td>gram</td>
<td>index</td>
<td><p id="gram">
  This field is matched using n-grams.
  For example, with the default gram size 2, the string "hi blue" is tokenized to "hi bl lu ue"
  both in the index and in queries to the index.
  </p><p>
  N-gram matching is useful mainly as an alternative to
  <a href="../../linguistics/linguistics-opennlp.html#tokenization">segmentation</a> in CJK languages.
  Typically, it results in increased recall and lower precision.
  However, as Vespa usually uses proximity in ranking,
  the precision offset may not be of much importance.
  Grams consume more resources than other matching methods
  because both indexes and queries will have more terms,
  and the terms contain repetition of the same letters.
  On the other hand, CPU-intensive CJK segmentation is avoided.
  </p><p>
  It may also be used for substring matching in general.
</p></td>
</tr>

<tr><td>gram-size</td>
<td>index</td>
<td><p id="gram-size">
  A positive, nonzero number, default 2.
  Sets the gram size when gram matching is used. Example:</p>
<pre>
match {
    gram
    gram-size: 3
}
</pre>
</td>
</tr>

</tbody>
</table>



<h2 id="rank">rank</h2>
<p>Contained in <a href="#field">field</a>, <a href="#struct-field">struct-field</a> or
<a href="#rank-profile">rank-profile</a>.
Set the kind of ranking calculations that will be done for the field. Even though the
actual ranking expressions decide the ranking, this setting tells Vespa which preparatory calculations
and which data structures are needed for the field.
<pre>
rank [field-name]: [ranking settings]
</pre>
or
<pre>
rank {
    [ranking setting]
}
</pre>
The field name should only be specified when used inside a rank-profile.
The following ranking settings are supported in addition to the default:
<table class="table">
<thead>
<tr><th>Ranking setting</th><th>Description</th></tr>
</thead><tbody>
<tr><td>filter</td><td>
  <p id="filter">
    Indicates that matching in this field should use fast bit vector data structures only.
    This saves CPU during matching, but only a few simple ranking features will be available for the field.
    This setting is appropriate for fields typically used for filtering or simple boosting purposes,
    like filtering or boosting on the language of the document.
  </p>
  <ul>
    <li>
      For <em>index</em> fields, this setting does <span style="text-decoration: underline;">not</span> change index formats
      but helps choose the most compact representation when matching against the field.
    </li>
    <li>
      For <em>attribute</em> fields with <em>fast-search</em> this setting builds additional
      posting list representations (bit vectors) can significantly speed up query evaluation.
    </li>
  </ul>
  <p>
    See <a href="../../performance/feature-tuning.html#when-to-use-fast-search-for-attribute-fields">feature tuning</a> and
    <a href="../../performance/practical-search-performance-guide.html">the practical search performance guide</a>.
  </p>
</td></tr>
<tr><td>normal</td><td>
  <p id="normal">
    The reverse of <code>filter</code>.
    Matching in this field will use normal data structures and give normal match information for ranking.
    Used to turn off implicit <code>rank: filter</code> when using <a href="#exact">match: exact</a>.
    If both <code>filter</code> and <code>normal</code> are set somehow,
    the effect is as if only <code>normal</code> was specified.
  </p>
</td></tr>
</tbody>
</table>
<p>
  Related: See the <a href="../querying/yql.html#filter">filter</a> query annotation
  for how to annotate query terms as filters.
</p>

<h3 id="rank-filter-threshold">filter-threshold</h3>
<p>
    Contained in a <a href="#rank-profile">rank-profile</a>.
    Used to optimize query performance when searching large text <a href="../../basics/schemas.html#document-fields">index</a> fields,
    by allowing a per query combination of <a href="#filter">rank: filter</a> and <a href="#normal">rank: normal</a> behavior.
    See <a href="#filter-threshold">profile-level filter-threshold</a> for how to use the same value for all <em>index</em> fields.
</p>
<pre>
rank [field-name] {
    filter-threshold: 0.05
}
</pre>
<table class="table">
    <thead>
    <tr><th>Setting</th><th>Description</th></tr>
    </thead>
    <tbody>
    <tr><td>filter-threshold</td><td>
    <p>
        Threshold value (in the range [0.0, 1.0]) deciding when matching in this <em>index</em> field should be treated as a filter.
        This happens for query terms with <a href="../../learn/glossary.html#estimated-hit-ratio">estimated hit ratios</a> (in the
        range [0.0, 1.0]) that are above the <em>filter-threshold</em>.
        Then, fast bitvector data structures are used, similar to when the field is set to <a href="#filter">rank: filter</a>.
        This saves CPU and Disk I/O during matching and typically results in faster query evaluation,
        with the downside being that only a boolean signal is available for ranking (the document being a match or not).
        <a href="../../ranking/bm25.html">BM25</a> handles this by assuming one occurrence of the query term in the document,
        and the field length being equal to the average field length.
    </p>
    <p>
        Use this to optimize query performance when searching large text <em>index</em> fields with e.g.
        the <a href="../../ranking/wand.html#weakand">weakAnd</a> query operator and <a href="../../ranking/bm25.html">BM25</a> ranking.
        Query terms that are common in the corpus (e.g., stopwords) are treated as filters with faster matching and simplified ranking,
        while other query terms are handled as usual with full ranking.
    </p>
    <p>
        In testing with various text datasets (e.g., Wikipedia),
        a <em>filter-threshold</em> setting of 0.05 has been shown to be a good starting point.
        <a href="../../performance/feature-tuning.html#posting-lists">Read more</a>.
    </p>
    <p>
        This setting is only relevant for <a href="../../basics/schemas.html#document-fields">index</a> fields,
        and cannot be used in combination with <a href="#filter">rank: filter</a>.
        Has no effect in <a href="../../performance/streaming-search.html#differences-in-streaming-search">streaming search</a>.
    </p>
    </td></tr>
    </tbody>
</table>


<h3 id="rank-element-gap">element-gap</h3>
<p>
    Contained in a <a href="#rank-profile">rank-profile</a>. Used to specify the gap between positions in adjacent elements in multi-value fields. The default value is <code>infinity</code>. It should be specified as <code>infinity</code> or as a positive integer number.
</p>
<p>
  Consider an <code>array&lt;string&gt;</code> field with three elements <code>["a c", "x b x a x x x x x x b", "x x d"]</code>.
  Normally, distance calculation is only performed within an element, thus the minimum forward distance between occurrences for terms <em>a</em> and <em>b</em> is 7.
  By setting the <code>element-gap</code> for the field to 0, adjacent elements are considered and the minimum forward distance between occurrences for terms <em>a</em> and <em>b</em> becomes 3.
  The minimum distance between occurrences for terms <em>c</em> and <em>d</em> is not calculated since they are not in adjacent elements.
</p>
<p>
  The <code>element-gap</code> setting affects the <a href="/en/reference/ranking/rank-features.html#nativeProximity">nativeProximity</a> rank feature,
  the <a href="/en/reference/querying/yql.html#near">near</a> query operator
  and the <a href="/en/reference/querying/yql.html#onear">onear</a> query operator.
</p>
<pre>
rank [field-name] {
    element-gap: 0
}
</pre>
<p>No restart or reindexing is required when changing this setting, it is immediately effective.</p>



<h2 id="query-command">query-command</h2>
<p>Contained in <a href="#fieldset">fieldset</a>, <a href="#field">field</a> or
<a href="#struct-field">struct-field</a>.
Specifies a function to be performed on query terms to the indexes of this field when searching.
The Search Container server has support for writing Vespa Searcher plugins that process these commands.</p>
<pre>
query-command: [an identifier or quoted string]
</pre>

<p>If you write a plugin searcher that needs some index-specific
configuration parameter, that parameter can be set here.</p>

<p>There is one built-in query-command available: <code>phrase-segmenting</code>.
If this is set, terms connected by non-word characters in user queries (such as "a.b")
will be parsed to a phrase item, instead of by default, an AND item where these terms have connectivity
set to 1.</p>


<h2 id="rank-type">rank-type</h2>
<p>Contained in <a
href="#field">field</a> or
<a href="#rank-profile">rank-profile</a>.
Selects the low-level rank settings to be used for this field when using <code>nativeRank</code>.
<pre>
rank-type [field-name]: [rank-type-name]
</pre>
The field name can be skipped inside fields. Defined rank types are:
<table class="table">
  <thead>
  <tr><th>Type</th><th>Description</th></tr>
  </thead><tbody>
  <tr>
    <td>identity</td>
    <td>
      Used for fields that contains only what this document
      <em>is</em>, e.g., "Title". Complete identity hits will get a
      high rank.
    </td>
  </tr><tr>
    <td>about</td>
    <td>
      Some text which is (only) about this document,
      e.g. "Description". About hits get high rank on partial
      matches and higher for matches early in the text and repetitive matches.
      This is the default rank type.
    </td>
  </tr><tr>
    <td>tags</td>
    <td>
      Used for simple tag fields of type tag. The tags rank type uses a logarithmic table to give more relative boost in the low range:
      As tags are added, they should have a significant impact on the rank score, but as more and more tags are added, each new tag should contribute less.
    </td>
  </tr><tr>
    <td>empty</td>
    <td>
      Gives no relevancy effect on matches. Used for fields you just
      want to treat as filters.
    </td>
  </tr>
  </tbody>
</table>
<p>
  For <code>nativeRank</code>, one can specify a rank type per field.
  If the supported rank types do not meet requirements,
  one can explicitly configure the native rank features using rank-properties.
  See the <a href="../ranking/nativerank.html">native rank reference</a> for more information.
</p>


<h2 id="weakand">weakand</h2>
<p>
  Contained in <a href="#rank-profile">rank-profile</a>.
</p>
<p>
  Tunes the <a href="../../ranking/wand.html#weakand">weakAnd</a> algorithm to automatically
  exclude terms and documents with expected low query significance based on document frequency
  statistics present in the document corpus. This makes matching faster at the cost of potentially
  reduced recall.
</p>
<pre>
weakand {
    [body]
}
</pre>
<p>
  Note that all document frequency calculations are done using <em>content node-local</em> document
  statistics (i.e. <a href="../../ranking/significance#global-significance-model">global significance</a>
  does not have an effect). This means results may differ across different content nodes and/or
  content node groups.
</p>
<p>
The body of a <code>weakand</code> statement consists of:
</p>
<table class="table">
  <thead>
    <tr>
      <th>Property</th>
      <th>Occurrence</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="white-space: nowrap">stopword-limit</td>
      <td>Zero to one</td>
      <td>
        <p id="weakand-stopword-limit">
          A number in the range [0, 1]. Represents the maximum
          <a href="../../learn/glossary.html#document-frequency-normalized">normalized document frequency</a> a query term can have in the
          corpus (i.e. the ratio of all documents where the term occurs at least once) before
          it's considered a stopword and dropped entirely from being a part of the
          <code>weakAnd</code> evaluation. This makes matching faster at the cost of
          potentially producing more hits. Dropped terms are not exposed as part of ranking.
        </p>
        <p>Example:</p>
        <pre>stopword-limit: 0.60</pre>
        <p>This will drop all query terms that occur in at least 60% of the documents.</p>
        <p>
          Using <code>stopword-limit</code> is similar to explicitly removing stopwords
          from the query up front, but has the benefit of dynamically adapting to the
          actual document corpus and not having to know—or specify—a set of stopwords.
          <a href="../../performance/feature-tuning.html#posting-lists">Read more</a>.
        </p>
      </td>
    </tr>
    <tr>
      <td style="white-space: nowrap">adjust-target</td>
      <td>Zero to one</td>
      <td>
        <p id="weakand-adjust-target">
          A number in the range [0, 1] representing
          <a href="../../learn/glossary.html#document-frequency-normalized">normalized document frequency</a>.
          Used to derive a per-query document score threshold, where documents scoring
          lower than the threshold will not be considered as potential hits from the
          <code>weakAnd</code> operator. The score threshold is selected to be equal to
          that of the query term whose document frequency is <em>closest</em> to the
          configured <code>adjust-target</code> value.
        <p>
        <p>
          This can be used to efficiently <em>exclude</em> documents that only match terms that
          occur very frequently in the document corpus. Such terms are likely to be stopwords
          that have low semantic value for the query, and excluding documents only containing
          them is likely to have only a minor impact on recall.
        </p>
        <p>
          This makes overall matching faster by reducing the number of hits produced by
          the <code>weakAnd</code> operator.
        </p>
        <p>Example:</p>
        <pre>adjust-target: 0.01</pre>
        <p>
          This excludes documents that only have terms that occur in more than approximately 1%
          of the document corpus. The actual threshold is query-specific and based on the query
          term score whose document frequency is closest to 1%.
        </p>
        <p>
          <code>adjust-target</code> can be used together with <a href="#weakand-stopword-limit">stopword-limit</a>
          to efficiently prune both terms and documents with low significance when processing queries.
          <a href="../../performance/feature-tuning.html#posting-lists">Read more</a>.
        </p>
      </td>
    </tr>
    <tr>
      <td style="white-space: nowrap">allow-drop-all</td>
      <td>Zero to one</td>
      <td>
        <p id="weakand-allow-drop-all">
          A boolean value. The default behavior of <code>weakAnd</code> is to always keep at least one term (the least common one) even though
          it is considered a stopword. This is to avoid dropping all query terms in order to make sure that some hits are produced.
        </p>
        <p>
          If set to <code>true</code>, the <code>weakAnd</code> operator
          will allow removal of all query terms if they are all considered stopwords (i.e., if
          <code>stopword-limit</code> is set and all query terms are above the limit).
        <p>
          This may be desired (and significantly improve query performance) if <code>weakAnd</code> is used together with another query operator,
          e.g. the <a href="../../querying/nearest-neighbor-search#querying-using-nearestneighbor-query-operator">nearestNeighbor</a> operator.
        </p>
        <p>
          Be aware that if this is set to <code>true</code> and all query terms are
          considered stopwords, the <code>weakAnd</code> operator will not produce <em>any</em>
          hits. And by extension, if <code>weakAnd</code> is used by itself, the query may return no hits.
        </p>
        <p>Example:</p>
        <pre>allow-drop-all: true</pre>
        <p>
          This overrides the default behavior of <code>weakAnd</code> and allows all query terms to be dropped if they are all considered stopwords.
        </p>
        <p>
          {% include important.html content="
      Defaults to <code>false</code> if not specified.
      "%}
        </p>
      </td>
    </tr>
  </tbody>
</table>


<h2 id="summary-to">summary-to</h2>
<p>
  {% include deprecated.html content="Use <a href='#document-summary'>document-summary</a> instead."%}
  Contained in <a href="#field">field</a> or
  <a href="#struct-field">struct-field</a>.
  Specifies the name of the document summaries that should contain this field.
</p>
<pre>
summary-to: [summary-name], [summary-name], &hellip;
</pre>
<p>
Fields with summary will always be part of the default summary regardless of this setting. Use explicit <a href="#document-summary">document-summary</a> instead.
See also <a href="../../querying/document-summaries.html">document summaries</a>.
</p>


<h2 id="summary">summary</h2>
<p>
Contained in <a href="#field">field</a> or
<a href="#document-summary">document-summary</a> or
<a href="#struct-field">struct-field</a>.
Declares a summary field.
<pre>
summary: [property]
</pre>
or
<pre>
summary [name] {
    [body]
}
</pre>
The summary <em>name</em> can be skipped if this is set inside a
field. The name will then be the same as the name of the source
field.
<em>full</em> summary is the default. Long field values (like document
content fields) should be made <em>dynamic</em>.
The body of a summary may contain:
<table class="table">
<thead>
<tr><th>Name</th><th>Occurrence</th><th>Description</th></tr>
</thead><tbody>
<tr><td>full</td>
  <td style="white-space:nowrap;">Zero to one</td>
<td>Returns the full field value in the summary (the default).</td>
</tr>
<tr><td>bolding: on</td>
  <td>Zero to one</td>
<td>Specifies whether the content of this field should be <a href="#bolding">bolded</a>.
Only supported for <a href="#indexing-index">index</a> fields of type string or array&lt;string&gt;.</td>
</tr>
<tr><td>dynamic</td>
  <td>Zero to one</td>
<td>Make the value returned in results from this summary field a <em>dynamic abstract</em> of the source
  field by extracting fragments of text around matching query terms. Matching query terms will also be highlighted, in
  similarity with the bolding feature.
  This highlighting is not affected by the query-argument <span class="code">bolding</span>.
  The default XML element used to highlight query terms is
<code>&lt;hi&gt;</code> - refer to <a href="#bolding">bolding</a> for how to configure.
  <em>dynamic</em> is only supported for <a href="#indexing-index">index</a> fields of type string or array&lt;string&gt;.
  For array&lt;string&gt; fields, a dynamic abstract is created per string item in the array.
</td>
</tr>
<tr>
  <td>source</td>
  <td>Zero to one</td>
  <td>
    <p id="source">
      Specifies the name of the field or fields from which the value of this summary field should be fetched.
      If multiple fields are specified, the value will be taken from the first field if that has a value,
      from the second if the first one is empty, and so on.
    </p>
<pre>
source: [field-name], [field-name], &hellip;
</pre>
    <p>
      When this is not specified, the source field is assumed to be the field with the same name as the summary field.
    </p>
    <p>
      Refer to <a href="#add-or-remove-an-existing-document-field-from-document-summary">attribute</a>
      and <a href="#add-or-remove-a-new-non-attribute-document-field-from-document-summary">non-attribute</a>
      fields for modifying a schema.
    </p>
  </td>
</tr>
<tr><td>to</td>
  <td>Zero to one</td>
  <td>Specifies the name of the document summaries that this should be included in.
<pre>
to: [document-summary-name], [document-summary-name], &hellip;
</pre>
  This can only be specified in fields, not in the explicit document
  summaries. When this is not specified, the field will go to the
  <code>default</code> document summary.</td>
</tr>
<tr><td style="white-space: nowrap">matched-elements-only</td>
  <td>Zero to one</td>
  <td>
  <p id="matched-elements-only">
    Specifies that only the matched elements in a searchable
    <a href="#array">array of primitive</a>,
    <a href="#weightedset">weightedset</a>,
    <a href="#array">array of struct</a> or
    <a href="#map">map type</a> field are returned as part of document summary.
    For array of struct or map type fields, this is typically used in accordance with the
    <a href="../querying/yql.html#sameelement">sameElement</a> operator,
    but it can also be used when searching directly on a sub-struct field.
    It is also supported when the field is <a href=#import-field>imported</a>.
  </p>
  <p>See <a href="#map">example use</a> and example schemas:</p>
  <ul>
    <li><a href="https://github.com/vespa-engine/system-test/blob/master/tests/search/matched_elements_only/indexed/test.sd">
      matched elements only</a></li>
    <li><a href="https://github.com/vespa-engine/system-test/blob/master/tests/search/struct_and_map_types/attribute_fields/test.sd">
      array of struct and map type</a></li>
  </ul>
</td>
</tr>
<tr><td style="white-space: nowrap">select-elements-by</td>
  <td>Zero to one</td>
  <td>
  <p id="select-elements-by">
    Use a summary feature to control which elements in an
    <a href="#array">array of primitive</a> or
    <a href="#array">array of struct</a> field are returned as part of document summary.
  </p>
<pre>
select-elements-by: &lt;summary-feature-name&gt;
</pre>
  <p>
    The summary feature used must be a tensor with a single mapped
    dimension. An element will be returned if its id is a label along
    the mapped dimension of this tensor.
  </p>
  <ul>
    <li><a href="https://github.com/vespa-engine/system-test/blob/master/tests/search/chunk_selection/test.sd">schema example</a></li>
  </ul>
</td>
</tr>
<tr><td style="white-space: nowrap">tokens</td>
<td>Zero to one</td>
<td>
<p id="tokens">
Make the value returned in results from this summary field be an array
of the tokens indexed in the source field. Multiple tokens at the same
location are put into a nested array.
</p>
<p>
The source field must be specified,
and it must be an <a href="#indexing-index">index</a> or
<a href="#indexing-attribute">attribute</a> field of type string,
array&lt;string&gt; or weightedset&lt;string&gt;. If the source field
is of type weightedset&lt;string&gt; then the summary field is
rendered as if the source field was of type array&lt;string&gt;,
weights are not shown.
</p>

<p>
This is mainly useful for <a href="../../querying/text-matching.html#tokens-example">linguistics transformations debugging</a>, to correlate query trace with the tokens indexed.
</p>
</td>
</tr>
</tbody>
</table>
<p>
  Read more about <a href="../../querying/document-summaries.html">document summaries</a>.
</p>



<h2 id="weight">weight</h2>
<p>
Contained in <a href="#field">field</a>.
The weight of a field - the default is 100.
The field weight is used when calculating the <a href="../../basics/ranking.html">rank scores</a>.
</p>
<pre>
weight: [positive integer]
</pre>



<h2 id="weightedset-properties">weightedset</h2>
<p>
Contained in <a href="#field">field</a> of type weightedset.
Properties of a weighted set.
<pre>
weightedset: [property]
</pre>
or
<pre>
weightedset {
    [property]
    [property]
    &hellip;
}
</pre>
<table class="table">
  <thead>
  <tr><th>Property</th><th>Occurrence</th><th>Description</th></tr>
  </thead><tbody>
<tr><td style="white-space: nowrap">create-if-nonexistent</td>
  <td style="white-space:nowrap;">Zero to one</td>
  <td>If the weight of a key is adjusted in a document using a partial update increment or decrement command,
    but the key is currently not present, the command will be ignored by default.
    Set this to make keys to be created in this case instead.
    This is useful when the weight is used to represent the count of the key.
<pre>
field tag type weightedset&lt;string&gt; {
    indexing: attribute | summary
    weightedset {
        create-if-nonexistent
        remove-if-zero
    }
}
</pre>
  </td>
</tr>
<tr><td>remove-if-zero</td>
  <td>Zero to one</td>
  <td>This is the companion of <code>create-if-nonexistent</code> for the converse case:
    By default, keys may have zero as weight.
    With this turned on, keys whose weight is adjusted (or set) to zero will be removed.</td>
</tr>
</tbody>
</table>


<h2 id="import-field">import field</h2>
<p>
Contained in <a href="#schema">schema</a>.
Using a <a href="#reference">reference</a> to a document type,
import a field from that document type into this schema to be used for matching, ranking, grouping, and sorting.
Only attribute fields can be imported.
Importing fields are not supported in
<a href="../../performance/streaming-search.html#differences-in-streaming-search">streaming search</a>.
</p>
<p>
The imported field inherits all but the following properties from the parent field:
</p>
<ul>
    <li><a href="#attribute">attribute: fast-access</a></li>
</ul>
<p>
Refer to <a href="../../schemas/parent-child.html">parent/child</a> for a complete example.
Note that the imported field is put <span style="text-decoration: underline">outside</span> the document type:
</p>
<pre>
schema myschema {
    document myschema {
        field parentschema_ref type reference&lt;parentschema&gt; {
            indexing: attribute
        }
    }
    import field parentschema_ref.name as parent_name {}
}
</pre>
<p>
Extra restrictions apply for some of the field types:
<table class="table">
  <thead>
    <tr>
      <th>Field type</th>
      <th>Restriction</th>
    </tr>
  </thead>
  <tbody>
    <tr>
        <td>array of struct</td>
        <td>Can be imported if at least one of the struct fields has an attribute.
            All struct fields with attributes must have primitive types.
            Only the struct fields with attributes will be visible.</td>
    </tr><tr>
        <td>map of struct</td>
        <td>Can be imported if the key field has an attribute, and
            at least one of the struct fields has an attribute.
            All struct fields with attributes must have primitive types.
            Only the key field and the struct fields with attributes will be visible.</td>
    </tr><tr>
        <td>map</td>
        <td>Can be imported if both key and value fields have primitive types and have attributes.</td>
    </tr><tr>
        <td>position</td>
        <td>Can be imported if it has an attribute.</td>
    </tr><tr>
        <td style="white-space: nowrap">array of position</td>
        <td>Can be imported if it has an attribute.</td>
    </tr>
  </tbody>
</table>
<p>
To use an imported field in summary, create an explicit
<a href="#document-summary">document summary</a> containing the field.
</p><p>
Imported fields can be used to expire documents, but <a href="../../schemas/documents.html#document-expiry">read this first</a>.
</p>



<h2 id="document-and-search-field-types">Document and search field types</h2>
<p>
Note that it is possible to make a document field
of one type into one or more instances of another search field, by
declaring a field outside the document, which uses other fields as
input. For example, to create an integer attribute for a
string containing a comma-separated list of integers in the document,
do like this:
</p>
<pre>
schema example {
    document example {
        field yearlist type string { # Comma-separated years
        }
    }

    field year type array&lt;int&gt; { # Search field using the yearlist value
        indexing: input yearlist | split "," | attribute
    }
}
</pre>



<h2 id="modifying-schemas">Modifying schemas</h2>
<p>
This section describes how a schema in a live application can be modified—categories:
<ol>
  <li><a href="#valid-changes-without-restart-or-re-feed">
    Valid changes without restart or re-feed</a></li>
  <li><a href="#changes-that-require-restart-but-not-re-feed">
    Changes that require restart but not re-feed</a></li>
  <li><a href="#changes-that-require-reindexing">
    Changes that require reindexing</a></li>
  <li><a href="#changes-that-require-re-feed">
    Changes that require re-feed</a></li>
</ol>
<p>
When running <code>vespa prepare</code> on a new application package,
the changes in the schema files are compared with the files in the current active package.
If some of the changes require restart or re-feed, the output from <code>vespa prepare</code>
specifies which actions are needed.
</p>
{% include important.html content="
For changes that are not covered below,
and no output is returned from <code>vespa prepare</code>,
the impact is undefined and in no way guaranteed to allow a system to stay live until re-feeding.
Changes not related to the schema are discussed
in <a href='/en/operations/self-managed/admin-procedures.html'>admin procedures</a>."%}


<h3 id="valid-changes-without-restart-or-re-feed">Valid changes without restart or re-feed</h3>
<p>
Procedure:
<ol>
  <li>Run <code>vespa prepare</code> on the changed application</li>
  <li>Run <code>vespa activate</code>. The changes will take effect immediately</li>
</ol>
Changes:
<table class="table">
  <thead>
  <tr><th>Change</th><th>Description</th></tr>
  </thead>
  <tbody>
  <tr><th>Add a new document field</th>
  <td>
  Add a new document field as index, attribute, summary or any combination of these.
  Existing documents will implicitly get the new field with no content.
  Documents fed after the change can specify the new field.
  If the field has existed with the same type earlier,
  then old content <em>may or may not</em> reappear
  </td></tr>

  <tr><th>Remove a document field</th>
  <td>
  Existing documents will no longer see the removed field,
  but the field data is not completely removed from the search node
  </td></tr>

  <tr><th>Add or remove an existing document field from document summary</th>
  <td>
    <p id="add-or-remove-an-existing-document-field-from-document-summary">
      Add an existing field to summary or any number of summary classes,
      and remove an existing field from summary or any number of summary classes. Example:
    </p>
<pre>
    document-summary short-summary {
        summary artist {}
    }
</pre>
    <p>
      A change adding an <a href="../../content/attributes.html">attribute</a> field with a new name to a summary class
      using <a href="#source">source</a> does not require restart or re-feed:
    </p>
<pre>
    field artist type string {
            indexing: summary | attribute
    }

    document-summary rename-summary {
        summary <span class="pre-hilite">artist_name</span> {
            <span class="pre-hilite">source: artist</span>
        }
    }
</pre>
    <p>
      Also see <a href="#add-or-remove-a-new-non-attribute-document-field-from-document-summary">non-attribute</a>
      fields.
    </p>
  </td></tr>

  <tr><th>Remove the attribute aspect from a field that is also an index field</th>
  <td>
  This is the only scenario of changing the attribute aspect of a document field that is allowed without restart
  </td></tr>

  <tr><th>Add, change or remove field sets</th>
  <td>
  Change <a href="#fieldset">fieldsets</a> used to group fields together for searching
  </td></tr>

  <tr><th>Change the alias or sorting attribute settings for an attribute field</th>
  <td><!-- ToDo -->
  </td></tr>

  <tr><th>Add, change or remove rank profiles</th>
  <td><!-- ToDo -->
  </td></tr>

  <tr><th>Change document field weights</th>
  <td><!-- ToDo -->
  </td></tr>

  <tr><th>Add, change or remove field aliases</th>
  <td><!-- ToDo -->
  </td></tr>


  <tr><th>Add, change or remove rank settings for a field</th>
  <td>
  Exception: Changing <code>rank: filter</code> on an attribute field in mode <em>index</em> requires restart.
  See details in <a href="#changes-that-require-restart-but-not-re-feed">next section</a>
  </td></tr>

  <tr><th>Add or remove a schema</th>
  <td>
  Removing a schema definition file will make <a href="../../content/proton.html">proton</a>
  drop all documents of that type, subsequently releasing memory and disk.
  </td></tr>
  </tbody>
</table>


<h3 id="changes-that-require-restart-but-not-re-feed">Changes that require restart but not re-feed</h3>
<p>
Procedure:
<ol>
  <li>Run <code>vespa prepare</code> on the changed application.
    Output specifies which restart actions are needed
  <li>Run <code>vespa activate</code></li>
  <li>Restart <code>services</code> on the services specified in the <code>prepare</code> output
</ol>
Changes:
<table class="table">
  <thead>
  <tr><th>Change</th><th>Description</th></tr>
  </thead>
  <tbody>
  <tr><th>Change the attribute aspect of a document field</th>
  <td>
    Add or remove a field as attribute.
    When adding, the attribute is populated based on the field value in stored documents during restart.
    When removing, the field value in stored documents is updated based on the content in the attribute during restart.
  </td></tr>

  <tr><th>Change the attribute settings for an attribute field</th>
  <td>
  Change the following attribute settings: <code>fast-search</code>, <code>fast-access</code>, <code>fast-rank</code>, <code>paged</code>.
  </td></tr>

  <tr><th>Change the rank filter setting for an attribute field</th>
  <td>
  Add or remove <code>rank: filter</code> on an attribute field.
  </td></tr>

  <tr><th>Change the hnsw index settings for a tensor attribute field</th>
  <td>
  Adding or removing the <a href="#index-hnsw">hnsw index</a> on a tensor attribute field,
  or changing the <code>distance-metric</code> or <code>max-links-per-node</code> requires a restart to rebuild the index.
  Changing <code>neighbors-to-explore-at-insert</code> requires a restart, but does not rebuild the index.
  </td></tr>

  <tr><th>Change the distance metric for a tensor attribute field</th>
  <td>
  Change, add, or remove the <a href="#distance-metric">distance metric</a> on a tensor attribute field.
  If no distance metric is specified, <em>euclidean</em> is used as the default.
  </td></tr>

  </tbody>
</table>
<p>
Example: Given a content cluster <em>mycluster</em> with mode <em>index</em>:
</p>
<pre>
schema test {
    document test {
        field f1 type string { indexing: summary }
    }
}
</pre>
Then add field <code>f1</code> as an attribute:
<pre>
schema test {
    document test {
        field f1 type string { indexing: attribute | summary }
    }
}
</pre>
The following is output from <code>vespa prepare</code> -
which restart actions are needed:
<pre>
WARNING: Change(s) between active and new application that require restart:
In cluster 'mycluster' of type 'search':
    Restart services of type 'searchnode' because:
        1) Document type 'test': Field 'f1' changed: add attribute aspect
</pre>


<h3 id="changes-that-require-reindexing">Changes that require reindexing</h3>
<p>
All the changes listed below require <a href="../../operations/reindexing.html">reindexing</a>
of all documents. Unlike re-feed, which requires an external source of data, reindexing is done
using documents stored in Vespa, and is automatic (once triggered). It can also run concurrently
with feed and serving, but until reindexing is complete, affected fields will be empty
or have potentially wrong annotations not matching the query processing. Procedure:
</p>
<ol>
  <li>Run <code>vespa prepare</code> on the changed application.
    Output specifies which reindexing actions are needed
  <li>Run <code>vespa activate</code></li>
  <li><a href="../api/deploy-v2.html#reindex">Enable reindexing</a> for the indicated document types and clusters</li>
  <li>Run <code>vespa prepare</code> and <code>vespa activate</code> again to start reindexing process</li>
</ol>
<p>Changes:</p>
<table class="table">
  <thead>
  <tr><th>Change</th><th>Description</th></tr>
  </thead>
  <tbody>
      <tr><th>Change index aspect of a document field</th>
      <td>
        This changes the document processing pipeline before documents arrive in the backend.
        Only documents fed after index aspect was added
        will have annotations and be present in the reverse index.
        Only documents fed after index aspect was removed
        will avoid disk bloat due to unneeded annotations.
      </td></tr>

      <tr><th>Switch stemming/normalizing on or off</th>
      <td>
        <p>
        This changes the document processing pipeline before documents
        arrive in the backend, and what annotations are made for an indexed field.
        </p>
        {% include important.html content="If not re-feeding after such a change, serving works,
        but recall is undefined as the index has been produced using a different setting
        than the one used when doing stemming/normalizing of the query terms."%}
      </td></tr>

      <tr><th>Add, change, or remove match settings for a field</th>
      <td>
        <p>
        Example: Adding <code>match: word</code> to a field.
        </p><p>
        This changes the document processing pipeline before documents
        arrive in the backend, and what annotations are made for an indexed field.
        </p>
        {% include important.html content="If not reindexing after such a change, serving works,
        but recall is undefined as the index has been produced using one match mode
        while run-time is using a different match mode."%}
      </td></tr>

      <tr>
        <th>Add or remove a new non-attribute document field from document summary</th>
        <td>
          <p id="add-or-remove-a-new-non-attribute-document-field-from-document-summary">
            A change adding an <a href="/en/basics/schemas.html#document-fields">index or summary</a> field
            (without <a href="/en/content/attributes.html">attribute</a>)
            with a new name to a summary class using <a href="#source">source</a> requires re-index:
          </p>
<pre>
    field artist type string {
            indexing: summary | index
    }

    document-summary rename-summary {
        summary <span class="pre-hilite">artist_name</span> {
            <span class="pre-hilite">source: artist</span>
        }
    }
</pre>
          <p>
            Also see <a href="#add-or-remove-an-existing-document-field-from-document-summary">attribute</a> fields.
          </p>
        </td>
      </tr>

  </tbody>
</table>
Example: Given a content cluster <em>mycluster</em> with mode <em>index</em>:
<pre>
schema test {
    document test {
        field f1 type string { indexing: summary }
    }
}
</pre>
Then add field <code>f1</code> as an index:
<pre>
schema test {
    document test {
        field f1 type string { indexing: index | summary }
    }
}
</pre>
The following is output from <code>vespa prepare</code> -
which reindex actions are needed:
<pre>
WARNING: Change(s) between active and new application that require re-index:
Reindex document type 'test' in cluster 'mycluster' because:
    1) Document type 'test': Field 'f1' changed: add index aspect, indexing script: '{ input f1 | summary f1; }' -&gt; '{ input f1 | tokenize normalize stem:"SHORTEST" | index f1 | summary f1; }'
</pre>


<h3 id="changes-that-require-re-feed">Changes that require re-feed</h3>
<p>
All the changes listed below require re-feeding of all documents.
Unless a change is listed in the above sections, treat it as if it were listed here.
Until re-feed is complete, affected fields will be empty
or have potentially wrong annotations not matching the query processing. Procedure:
</p>
<ol>
  <li>Run <code>vespa prepare</code> on the changed application.
    Output specifies which re-feed actions are needed
  <li>Stop feeding, wait until done</li>
  <li>Run <code>vespa activate</code></li>
  <li>Re-feed all documents</li>
</ol>
Changes:
<table class="table">
  <thead>
  <tr><th>Change</th><th>Description</th></tr>
  </thead>
  <tbody>
      <tr>
        <th>Change a document field's data type or collection type</th>
      <td>
        <p>
        Existing documents will no longer have any content for this field.
        To populate the field, re-feed the existing documents using the new type for this field.
        There will be no automatic conversion from old to new field type.
        </p>
        {% include important.html content="If not re-feeding after such a change, serving works,
        but searching this field will not give any results"%}
      </td></tr>

      <tr><th>Change a tensor attribute's tensor type</th>
      <td><!-- ToDo -->
      </td></tr>

  </tbody>
</table>
Example: Given a content cluster <em>mycluster</em> with mode <em>index</em>:
<pre>
schema test {
    document test {
        field f1 type string { indexing: summary }
    }
}
</pre>
Then change field <code>f1</code> to hold an int:
<pre>
schema test {
    document test {
        field f1 type int { indexing: summary }
    }
}
</pre>
The following is output from <code>vespa prepare</code> -
which re-feed actions are needed:
<pre>
WARNING: Change(s) between active and new application that require re-feed:
Re-feed document type 'test' in cluster 'mycluster' because:
    1) Document type 'test': Field 'f1' changed: data type: 'string' -&gt; 'int'
</pre>