rank-features.html

---
# Copyright Vespa.ai. All rights reserved.
title: "Rank Feature Reference"
redirect_from:
- /en/reference/rank-features.html
---

<p>
This is the list of the rank features in Vespa.
These features are available during document ranking for combination into a complete rank score by a
<a href="ranking-expressions.html">ranking expression</a>.
The features are a combination of coarse grained features suitable for handwritten expressions,
and finer grained features suitable for machine learning.
</p><p>
See also <a href="../../basics/ranking.html">the overview of the ranking framework</a>, and
<a href="rank-feature-configuration.html">rank feature configuration parameters</a>.
Notes:
</p>
<ul>
  <li>
    Types: All rank feature values are floats. Integers are converted to exact whole value floats.
    String values are converted to exact whole value floats using a hash function.
    String literals in ranking expressions are converted using the same hash function,
    to enable equality tests on string values.
  </li><li>
    Features which are <em>normalized</em> are between 0 and 1, where 0 is always the minimum and 1 the maximum.
    Normalized features should normally be preferred because they are more easily combined by
    <a href="ranking-expressions.html">ranking expressions</a> into a complete normalized score.
  </li><li>
    A query may override <em>any</em> rank feature value by submitting that value as a feature with the query.
  </li><li>
    Some features have parameters. It is always allowed to quote parameters with <em>"</em>.
    Nested quotes are not allowed and must be escaped using <em>\</em>.
    Parameters that can be parsed as feature names may be left unquoted.
    Examples: <em>foo(bar(baz(5.5)))</em>, <em>foo("bar(\"baz(\\\"5.5\\\")\")")</em>, <em>foo("need quote")</em>
  </li>
</ul>


<h2 id="feature-list">Feature list</h2>

<!--table-to-list-->
<table class="table" id="rank-feature-table">





<tr><td colspan="3"></td></tr>
<tr><td colspan="3"><h3 id="query-features">Query features</h3></td></tr>
<tr class="trx"><th class="thx">Feature name</th><th class="thx">Default</th><th class="thx">Description</th></tr>

<tr><td>query(<em>value</em>)</td>
  <td>0</td>
  <td>
    <p id="query(value)">
    An application specific feature submitted with the query,
    see <a href="../../ranking/ranking-expressions-features.html#using-query-variables">using the query feature</a>.
    </p>
  </td></tr>

<tr><td>term(<em>n</em>).significance</td>
  <td>0</td>
  <td><p id="term(n).significance">
    A normalized number (between 0.0 and 1.0) describing the significance
    of the term; used as a multiplier or weighting factor by many other text matching rank features.
    </p><p>
    This should ideally be set by a searcher in the container for global correctness
    as each node will estimate the significance values from the local corpus.
    Use the
    <a href="https://javadoc.io/doc/com.yahoo.vespa/container-search/latest/com/yahoo/prelude/query/TaggableItem.html#setSignificance(double)">
      Java API for significance</a> or
    <a href="../querying/yql.html#significance">YQL annotation for significance</a>.
    </p><p>
    As a fallback, a significance based on Robertson-Sparck-Jones term
    weighting is used; it is logarithmic from 1.0 for rare terms down
    to 0.5 for common terms (those occurring in every document seen).
    </p><p>
    Note that "rare" is defined as a frequency of 0.000001 or less.
    This is the term document frequency (how many documents contain the
    term out of all documents that can be observed), so you cannot get 1.0
    as the fallback until you actually have a large number of documents
    (minimum 1 million) in the same search process.
    </p><p>
    See <a href="rank-feature-configuration.html#term">numTerms</a> config.</p>
</td></tr>

<tr><td>term(<em>n</em>).weight</td>
  <td>100</td>
  <td><p id="term(n).weight">The importance of matching this query term given in the query</p></td></tr>

<tr><td>term(<em>n</em>).connectedness</td>
  <td>0.1</td>
  <td>
    <p id="term(n).connectedness">
    The normalized strength with which this term is connected to the previous term in the query.
    Must be assigned to query terms in a <a href="../../applications/searchers.html">searcher</a> using the
    <a href="https://javadoc.io/doc/com.yahoo.vespa/container-search/latest/com/yahoo/prelude/query/TaggableItem.html#setConnectivity(com.yahoo.prelude.query.Item,double)">
    Java API for connectivity</a>
    or <a href="../querying/yql.html#connectivity">YQL annotation for connectivity</a>.
    </p>
  </td></tr>

<tr><td>queryTermCount</td>
  <td>0</td>
  <td>
    <p id="queryTermCount">
      The total number of terms in this query, including both user and synthetic terms in all fields.
    </p>
  </td></tr>




<tr><td colspan="3"></td></tr>
<tr><td colspan="3"><h3 id="document-features">Document features</h3></td></tr>
<tr class="trx"><th class="thx">Feature name</th><th class="thx">Default</th><th class="thx">Description</th></tr>

<tr><td>fieldLength(<em>name</em>)</td>
  <td>1000000</td>
  <td>
    <p id="fieldLength(name)">
    The number of terms in this field if one or more query term matched the field,
    1000000 if no query term matched the field.
    </p>
  </td></tr>

<tr><td>attribute(<em>name</em>)</td>
  <td>null</td>
  <td>
    <p id="attribute(name)">
    The value of a <a href="../schemas/schemas.html#tensor">tensor</a>
    or single value <em>numeric</em> attribute or null/NaN if not set.
    Use <em>isNan()</em> to check if value is not defined.
    Using undefined values in ranking expressions leads to undefined behavior.
    </p>
  </td></tr>

<tr><td>attribute(<em>name</em>,<em>n</em>)</td>
  <td>0</td>
  <td>
    <p id="attribute(name,n)">
    The value at index n (base 0) of a <em>numeric</em> array attribute with the given name.
    Note that the index number must be explicit, it cannot be the output of an
    <a href="../schemas/schemas.html#function-rank">expression function</a>.
    The order of the items in an array attribute is the same as the order they have in the input feed.
    If items are added using partial updates they are added to the end of the existing items list.
    </p>
  </td></tr>

<tr><td>attribute(<em>name</em>,<em>key</em>).weight</td>
  <td>0</td>
  <td><p id="attribute(name,key).weight">The weight found at a given key in a weighted set attribute</p></td></tr>

<tr><td>attribute(<em>name</em>,<em>key</em>).contains</td>
  <td>0</td>
  <td>
    <p id="attribute(name,key).contains">1 if the given key is present in a weighted set attribute, 0 otherwise</p>
  </td></tr>

<tr><td>attribute(<em>name</em>).count</td>
  <td>0</td>
  <td><p id="attribute(name).count">The number of elements in the attribute with the given name.</p></td></tr>

<tr><td>tensorFromWeightedSet(<em>source</em>,<em>dimension</em>)</td>
  <td>empty tensor</td>
  <td>
    <p id="tensorFromWeightedSet(source,dimension)">
      Creates a <code>tensor&lt;double&gt;</code> with one mapped dimension
      from the given integer or string weighted set attribute.
      The attribute is specified as the full feature name, <code>attribute(name)</code>.
      The <em>dimension</em> parameter is optional. If omitted the dimension name will be the attribute name.
    </p>
    <p>Example: Given the weighted set:</p>
<pre>
{key1:0, key2:1, key3:2.5}
</pre>
    <p><em>tensorFromWeightedSet(attribute(myField), dim)</em> produces:</p>
<pre>
tensor&lt;double&gt;(dim{}):{ {dim:key1}:0.0, {dim:key2}:1.0, {dim:key3}:2.5} }
</pre>
    {% include note.html content="This creates a temporary tensor,
    and has build cost and extra memory is touched.
    Tensor evaluation is most effective when the cell types of all tensors are equal -
    use <a href='ranking-expressions.html#cell_cast'>cell_cast</a> to enable optimizations.
    Also, duplicating the field in the schema to a native tensor instead of creating from a set
    can increase performance." %}
  </td></tr>

<tr><td>tensorFromLabels(<em>attribute</em>,<em>dimension</em>)</td>
  <td>empty tensor</td>
  <td>
    <p id="tensorFromLabels(source,dimension)">
      Creates a <code>tensor&lt;double&gt;</code> with one mapped dimension
      from the given single value or array attribute.
      The value(s) must be integers or strings. The attribute is specified as the full feature name,
      <code>attribute(name)</code>.
      The <em>dimension</em> parameter is optional. If omitted the dimension name will be the attribute name.
    </p>
    <p>
    Example: Given an attribute field <code>myField</code> containing the array value:
    </p>
<pre>
[v1, v2, v3]
</pre>
    <p><em>tensorFromLabels(attribute(myField), dim)</em> produces:</p>
<pre>
tensor&lt;double&gt;(dim{}):{ {dim:v1}:1.0, {dim:v2}:1.0, {dim:v3}:1.0} }
</pre>
    <p>See <em>tensorFromWeightedSet</em> for performance notes.</p>
  </td></tr>

<tr><td>tensorFromStructs(<em>attribute</em>,<em>key</em>,<em>value</em>,<em>type</em>)</td>
  <td>empty tensor</td>
  <td>
    <p id="tensorFromStructs(attribute,key,value,type)">
      Creates a <code>tensor&lt;type&gt;</code> with one mapped dimension
      from the given <code>array&lt;struct&gt;</code> attribute.
      Keys are taken from the struct field <em>key</em> and values from the struct field <em>value</em>.
      The resulting tensor will have one mapped dimension named after the <em>key</em> field.
      The <em>type</em> parameter is required and must be <code>float</code> or <code>double</code>.
      The function takes exactly four arguments.
    </p>
    <p>Example: Given an <code>array&lt;struct&gt;</code> attribute <code>items</code> with fields
       <code>name</code> (string) and <code>price</code> (float):</p>
<pre>
tensorFromStructs(attribute(items), name, price, float)
</pre>
<pre>
tensor&lt;float&gt;(name{}):{ {name:apple}:1.5, {name:banana}:0.75, {name:cherry}:2.25 }
</pre>

    <p>Example: Integer keys and float values:</p>
<pre>
tensorFromStructs(attribute(ids), id, score, double)
</pre>
<pre>
tensor(id{}):{ {id:100}:10.5, {id:200}:20.75, {id:300}:30.25 }
</pre>

    <p><em>Details:</em> Empty or missing arrays yield an empty tensor of the requested type.
       The first argument must be an <code>attribute(...)</code> source.</p>

    <p>See <em>tensorFromWeightedSet</em> for performance notes.</p>
  </td>
</tr>

<tr><td colspan="3"></td></tr>
<tr><td colspan="3"><h3 id="field-match-features-normalized">Field match features - normalized</h3></td></tr>
<tr><td colspan="3">
  fieldMatch features provide a good measure of the degree
  to which a query matches the text of a field, but are expensive to calculate and therefore
  often only suitable for <a href="../../ranking/phased-ranking.html">second-phase</a> ranking expressions.
  See the <a href="string-segment-match.html">string segment match</a> document
  for details on the algorithm computing this rank-feature set.

  Note that even using a fine-grained sub features like fieldMatch(<em>name</em>).absoluteOccurrence
  will have the same complexity and cost as using the general top level fieldMatch(<em>name</em>) feature.
</td></tr>
<tr class="trx"><th class="thx">Feature name</th><th class="thx">Default</th><th class="thx">Description</th></tr>

<tr><td>fieldMatch(<em>name</em>)</td>
  <td>0</td>
  <td>
    <p id="fieldMatch(name)">
    A normalized measure of the degree to which this query and field matched
    (default, the long name of this is <code>match</code>). Use this if you do not
    want to create your own combination function of more fine-grained fieldmatch features.
    </p>
  </td></tr>

<tr><td>fieldMatch(<em>name</em>).proximity</td>
  <td>0</td>
  <td><p id="fieldMatch(name).proximity">
    Normalized proximity - a value which is close to 1 when matched terms are close
    <em>inside each segment</em>, and close to zero when they are far apart inside segments.
    Relatively more connected terms influence this value more. This is
    absoluteProximity/average connectedness for the query terms for this field.
    </p><p>
    Note that if all the terms are far apart,
    the proximity will be 1, but the number of segments will be high.
    Proximity is only concerned with closeness within segments,
    a total score must also take the number of segments into account.</p>
  </td></tr>

<tr><td>fieldMatch(<em>name</em>).completeness</td>
  <td>0</td>
  <td>
    <p id="fieldMatch(name).completeness">
      The normalized total completeness, where field completeness is more important:
    </p>
    <p>
      <code>queryCompleteness *
        ( 1 - <a href="rank-feature-configuration.html#fieldMatch">fieldCompletenessImportance</a> )
        + <a href="rank-feature-configuration.html#fieldMatch">fieldCompletenessImportance</a> * fieldCompleteness</code>
    </p>
  </td></tr>

<tr><td>fieldMatch(<em>name</em>).queryCompleteness</td>
  <td>0</td>
  <td><p id="fieldMatch(name).queryCompleteness">The normalized ratio of query tokens matched in the field:</p>
    <code>matches/query terms searching this field</code></td></tr>

<tr><td>fieldMatch(<em>name</em>).fieldCompleteness</td>
  <td>0</td>
  <td><p id="fieldMatch(name).fieldCompleteness">The normalized ratio of query tokens which was matched in the field:</p>
    <code>matches/fieldLength</code></td></tr>

<tr><td>fieldMatch(<em>name</em>).orderness</td>
  <td>0</td>
  <td>
    <p id="fieldMatch(name).orderness">
      A normalized metric of how well the order of the terms agrees in the chosen segments:
    </p>
    <p><code>1-outOfOrder/pairs</code></p>
  </td></tr>

<tr><td>fieldMatch(<em>name</em>).relatedness</td>
  <td>0</td>
  <td>
    <p id="fieldMatch(name).relatedness">
      A normalized measure of the degree to which different terms are related (occurring in the same segment):
    </p>
    <p><code>1-(segments-1)/(matches-1)</code></p></td></tr>

<tr><td>fieldMatch(<em>name</em>).earliness</td>
  <td>0</td>
  <td>
    <p id="fieldMatch(name).earliness">
      A normalized measure of how early the first segment occurs in this field.
    </p>
  </td></tr>

<tr><td>fieldMatch(<em>name</em>).longestSequenceRatio</td>
  <td>0</td>
  <td>
    <p id="fieldMatch(name).longestSequenceRatio">A normalized metric of the relative size of the longest sequence:</p>
    <p><code>longestSequence/matches</code></p></td></tr>

<tr><td>fieldMatch(<em>name</em>).segmentProximity</td>
  <td>0</td>
  <td>
    <p id="fieldMatch(name).segmentProximity">
      A normalized metric of the closeness (inverse of spread) of segments in the field:
    </p>
    <p><code>1-segmentDistance/fieldLength</code></p>
  </td></tr>

<tr><td>fieldMatch(<em>name</em>).unweightedProximity</td>
  <td>0</td>
  <td>
    <p id="fieldMatch(name).unweightedProximity">
    The normalized proximity of the matched terms, not taking term connectedness into account.
    This number is close to 1 if all the matched terms are
    following each other in sequence, and close to 0 if they are far from each other or out of order.
    </p>
  </td></tr>

<tr><td>fieldMatch(<em>name</em>).absoluteProximity</td>
  <td>0</td>
  <td>
    <p id="fieldMatch(name).absoluteProximity">
    Returns the normalized proximity of the matched terms, weighted by the connectedness of
    the query terms. This number is 0.1 if all the matched terms are and have default or lower
    connectedness, close to 1 if they are following in sequence and have a high connectedness,
    and close to 0 if they are far from each other in the segments or out of order.
    </p>
  </td></tr>

<tr><td>fieldMatch(<em>name</em>).occurrence</td>
  <td>0</td>
  <td><p id="fieldMatch(name).occurrence">
    Returns a normalized measure of the number of occurrences of the terms of the query.
    This is 1 if there are many occurrences of the query terms <em>in absolute terms,
    or relative to the total content of the field</em>, and 0 if there are none.
    </p><p>
    This is suitable for occurrence in fields containing regular text.</p>
  </td></tr>

<tr><td>fieldMatch(<em>name</em>).absoluteOccurrence</td>
  <td>0</td>
  <td><p id="fieldMatch(name).absoluteOccurrence">
    Returns a normalized measure of the number of occurrence of the terms of the query:
    </p><p class="equation-container" class="equation-container"><!-- depends on mathjax -->
    $$\frac{\sum_{\text{all query terms}}(min(\text{number of occurrences of the term},maxOccurrences))}{(\text{query term count} &times; 100)}$$
    </p><p>
    This is 1 if there are many occurrences of the query terms, and 0 if there are none.
    </p><p>
    This number is not relative to the field length, so it is suitable for uses
    of occurrence to denote relative importance between matched terms
    (i.e. fields containing keywords, not normal text).</p>
  </td></tr>

<tr><td>fieldMatch(<em>name</em>).weightedOccurrence</td>
  <td>0</td>
  <td>
    <p id="fieldMatch(name).weightedOccurrence">
    Returns a normalized measure of the number of occurrence of the terms of the query,
    weighted by term weight.
    This number is close to 1 if there are many occurrences of highly weighted query terms,
    in absolute terms, or relative to the total content of the field, and 0 if there are none.
    </p>
  </td></tr>

<tr><td>fieldMatch(<em>name</em>).weightedAbsoluteOccurrence</td>
  <td>0</td>
  <td><p id="fieldMatch(name).weightedAbsoluteOccurrence">
    Returns a normalized measure of the number of occurrence of the terms of the query,
    taking weights into account so that occurrences of higher weighted query terms
    has more impact than lower weighted terms.
    </p><p>
    This is 1 if there are many occurrences of the highly weighted terms, and 0 if there are none.
    </p><p>
    This number is not relative to the field length, so it is suitable for uses
    of occurrence to denote relative importance between matched terms
    (i.e. fields containing keywords, not normal text).</p>
  </td></tr>

<tr><td>fieldMatch(<em>name</em>).significantOccurrence</td>
  <td>0</td>
  <td><p id="fieldMatch(name).significantOccurrence">
    Returns a normalized measure of the number of occurrence of the terms of the query <em>in absolute terms,
    or relative to the total content of the field</em>, weighted by term significance.
    </p><p>
    This number is 1 if there are many occurrences of the highly significant terms,
    and 0 if there are none.</p>
  </td></tr>





<tr><td colspan="3"></td></tr>
<tr><td colspan="3"><h3 id="field-match-features-normalized-and-relative-to-the-whole-query">
  Field match features - normalized and relative to the whole query</h3></td></tr>
<tr class="trx"><th class="thx">Feature name</th><th class="thx">Default</th><th class="thx">Description</th></tr>
<tr><td>fieldMatch(<em>name</em>).weight</td>
  <td>0</td>
  <td><p id="fieldMatch(name).weight">
    The normalized weight of this match relative to the whole query:
    The sum of the weights of all <em>matched</em> terms/the sum of the weights of all <em>query</em> terms.
    If all the query terms were matched, this is 1.
    If no terms were matched, or these matches has weight zero this is 0.
    </p><p>
    As the sum of this number over all the terms of the query is always 1, sums over all fields of
    normalized rank features for each field multiplied by this number
    for the same field will produce a normalized number.
    </p><p>
    Note that this scales with the number of matched query terms in the field.
    If you want a component which does not, divide by matches.</p>
  </td></tr>

<tr><td>fieldMatch(<em>name</em>).significance</td>
  <td>0</td>
  <td><p id="fieldMatch(name).significance">
    Returns the normalized term significance of the terms of this match relative to the
    whole query: The sum of the significance of all <em>matched</em> terms/the sum of the significance of all
    <em>query</em> terms. If all the query terms were matched, this is 1. If no terms were matched, or if the
    significance of all the matched terms is zero, this number is zero.
    </p><p>
    This metric has the same properties as weight.
    </p><p>
    See the <a href="#term(n).significance">term(n).significance</a> feature for how the significance
    for a single term is calculated.</p>
  </td></tr>

<tr><td>fieldMatch(<em>name</em>).importance</td>
  <td>0</td>
  <td>
    <p id="fieldMatch(name).importance">
      Returns the average of significance and weight. This has the same properties as those metrics.
    </p>
  </td></tr>




<tr><td colspan="3"></td></tr>
<tr><td colspan="3">
  <h3 id="field-match-features-not-normalized">Field match features - not normalized</h3></td></tr>
<tr class="trx"><th class="thx">Feature name</th><th class="thx">Default</th><th class="thx">Description</th></tr>

<tr><td>fieldMatch(<em>name</em>).segments</td>
  <td>0</td>
  <td>
    <p id="fieldMatch(name).segments">
      The number of field text segments which are needed to match the query as completely as possible
    </p>
  </td></tr>

<tr><td>fieldMatch(<em>name</em>).matches</td>
  <td>0</td>
  <td>
    <p id="fieldMatch(name).matches">
      The total number of query terms which was matched in this field
    </p>
  </td></tr>

<tr><td>fieldMatch(<em>name</em>).degradedMatches</td>
  <td>0</td>
  <td>
    <p id="fieldMatch(name).degradedMatches">
    The number of degraded query terms which was matched in this field.
    A degraded term is a term where no occurrence information is available during calculation.
    The number of degraded matches is less than or equal to the total number of matches.
    </p>
  </td></tr>

<tr><td>fieldMatch(<em>name</em>).outOfOrder</td>
  <td>0</td>
  <td>
    <p id="fieldMatch(name).outOfOrder">
      The total number of out of order token sequences <em>within</em> matched field segments
    </p>
  </td></tr>

<tr><td>fieldMatch(<em>name</em>).gaps</td>
  <td>0</td>
  <td>
    <p id="fieldMatch(name).gaps">
      The total number of position jumps (backward or forward) within field segments
    </p>
  </td></tr>

<tr><td>fieldMatch(<em>name</em>).gapLength</td>
  <td>0</td>
  <td><p id="fieldMatch(name).gapLength">The summed length of all gaps within segments</p></td></tr>

<tr><td>fieldMatch(<em>name</em>).longestSequence</td>
  <td>0</td>
  <td>
    <p id="fieldMatch(name).longestSequence">
      The size of the longest matched continuous, in-order sequence in the field
    </p>
  </td></tr>

<tr><td>fieldMatch(<em>name</em>).head</td>
  <td>0</td>
  <td>
    <p id="fieldMatch(name).head">
      The number of tokens in the field preceding the start of the first matched segment
    </p>
  </td></tr>

<tr><td>fieldMatch(<em>name</em>).tail</td>
  <td>0</td>
  <td>
    <p id="fieldMatch(name).tail">
      The number of tokens in the field following the end of the last matched segment
    </p>
  </td></tr>

<tr><td>fieldMatch(<em>name</em>).segmentDistance</td>
  <td>0</td>
  <td>
    <p id="fieldMatch(name).segmentDistance">
    The sum of the distance between all segments making up a match to the query, measured
    as the sum of the number of token positions separating the
    <em>start</em> of each <em>field</em> adjacent segment.
    </p>
  </td></tr>





<tr><td colspan="3"></td></tr>
<tr><td colspan="3"><h3 id="query-and-field-similarity">Query and field similarity</h3></td></tr>
<tr><td colspan="3">
  Normalized feature set measuring the approximate <em>similarity</em> between a field and the query.
  These features are suitable in cases where the query is as large as the field (i.e. is a document)
  such that we are interested in the similarity between the query and the entire field.
  They are cheap to compute even if the query is large.
</td></tr>
<tr class="trx"><th class="thx">Feature name</th><th class="thx">Default</th><th class="thx">Description</th></tr>

<tr><td>textSimilarity(<em>name</em>)</td>
  <td>0</td>
  <td><p id="textSimilarity(name)">A weighted sum of the individual similarity measures.</p></td></tr>

<tr><td>textSimilarity(<em>name</em>).proximity</td>
  <td>0</td>
  <td>
    <p id="textSimilarity(name).proximity">
      A measure of how close together the query terms appear in the field.
    </p>
  </td></tr>

<tr><td>textSimilarity(<em>name</em>).order</td>
  <td>0</td>
  <td>
    <p id="textSimilarity(name).order">
      A measure of the order in which the query terms appear in the field compared to the query.
    </p>
  </td></tr>

<tr><td>textSimilarity(<em>name</em>).queryCoverage</td>
  <td>0</td>
  <td>
    <p id="textSimilarity(name).queryCoverage">
    A measure of how much of the query the field covers when a single term
    from the field can only cover a single term in the query.
    Query term weights are used during normalization.
    </p>
  </td></tr>

<tr><td>textSimilarity(<em>name</em>).fieldCoverage</td>
  <td>0</td>
  <td>
    <p id="textSimilarity(name).fieldCoverage">
    A measure of how much of the field the query covers when a single term from the query
    can only cover a single term in the field.
    </p>
  </td></tr>





<tr><td colspan="3"></td></tr>
<tr><td colspan="3"><h3 id="query-term-and-field-match-features">Query term and field match features</h3></td></tr>
<tr class="trx"><th class="thx">Feature name</th><th class="thx">Default</th><th class="thx">Description</th></tr>

<tr><td>fieldTermMatch(<em>name</em>,<em>n</em>).firstPosition</td>
  <td>1000000</td>
  <td>
    <p id="fieldTermMatch(name,n).firstPosition">
      The position of the first occurrence of this query term in this index field.
      <a href="rank-feature-configuration.html#fieldTermMatch">numTerms</a> configuration
    </p>
  </td></tr>

<tr><td>fieldTermMatch(<em>name</em>,<em>n</em>).occurrences</td>
  <td>0</td>
  <td>
    <p id="fieldTermMatch(name,n).occurrences">
      The number of occurrences of this query term in this index field
    </p>
  </td></tr>

<tr><td>matchCount(<em>name</em>)</td>
  <td>0</td>
  <td>
    <p id="matchCount(name)">
      Returns number of times any term in the query matches this index/attribute field.
    </p>
  </td></tr>

<tr><td>matches(<em>name</em>)</td>
  <td>0</td>
  <td>
    <p id="matches(name)">
      Returns 1 if the index/attribute field with the given name is matched by the query.
    </p>
  </td></tr>

<tr><td>matches(<em>name</em>,<em>n</em>)</td>
  <td>0</td>
  <td>
    <p id="matches(name,n)">
      Returns 1 if the index/attribute field with the given name is matched by the query term with position <em>n</em>.
    </p>
  </td></tr>

<tr><td>termDistance(<em>name</em>,<em>x</em>,<em>y</em>).forward</td>
  <td>1000000</td>
  <td>
    <p id="termDistance(name,x,y).forward">
      The minimum distance between the occurrences of term <em>x</em> and term <em>y</em> in this index field.
      Term <em>x</em> occurs before term <em>y</em>.
    </p>
  </td></tr>

<tr><td>termDistance(<em>name</em>,<em>x</em>,<em>y</em>).forwardTermPosition</td>
  <td>1000000</td>
  <td>
    <p id="termDistance(name,x,y).forwardTermPosition">
      The position of the occurrence of term <em>x</em> in this index field used for the forward distance.
    </p>
  </td></tr>

<tr><td>termDistance(<em>name</em>,<em>x</em>,<em>y</em>).reverse</td>
  <td>1000000</td>
  <td>
    <p id="termDistance(name,x,y).reverse">
      The minimum distance between the occurrences of term <em>y</em> and term <em>x</em> in this index field.
      Term <em>y</em> occurs before term <em>x</em>.
    </p>
  </td></tr>

<tr><td>termDistance(<em>name</em>,<em>x</em>,<em>y</em>).reverseTermPosition</td>
  <td>1000000</td>
  <td>
    <p id="termDistance(name,x,y).reverseTermPosition">
      The position of the occurrence of term <em>y</em> in this index field used for the reverse distance.
    </p>
  </td></tr>







<tr><td colspan="3"></td></tr>
<tr><td colspan="3">
  <h3 id="features-for-indexed-multivalue-string-fields">Features for indexed multivalue string fields</h3></td></tr>
<tr class="trx"><th class="thx">Feature name</th><th class="thx">Default</th><th class="thx">Description</th></tr>

<tr><td>elementCompleteness(<em>name</em>).completeness</td>
  <td>0</td>
  <td>
    <p id="elementCompleteness(name).completeness">
    A weighted combination of fieldCompleteness and queryCompleteness for the element in the field that produces the
    highest value for this output after the elements weight is factored in. The weighting can be adjusted using
    <a href="rank-feature-configuration.html#elementCompleteness">elementCompleteness(name).fieldCompletenessImportance</a>.
    </p>
  </td></tr>

<tr><td>elementCompleteness(<em>name</em>).fieldCompleteness</td>
  <td>0</td>
  <td>
    <p id="elementCompleteness(name).fieldCompleteness">
      The field completeness of the best matching element. This is calculated as:
    </p>
    <p><code>max( (number of query terms matched in the element) /
      (element size), 1.0)</code>.</p>
  </td></tr>

<tr><td>elementCompleteness(<em>name</em>).queryCompleteness</td>
  <td>0</td>
  <td>
    <p id="elementCompleteness(name).queryCompleteness">
      The query completeness of the best matching element. This is calculated as:</p>
    <p>
    <code>(sum of weight for query terms matched in the element) /
      (sum of weight for query terms searching the field)</code>.
    </p>
  </td></tr>

<tr><td>elementCompleteness(<em>name</em>).elementWeight</td>
  <td>0</td>
  <td><p id="elementCompleteness(name).elementWeight">
    The weight of the best matching element, starting from the default - i.e., negative weights will return 0.
  </p></td></tr>

<tr><td>elementSimilarity(<em>name</em>)</td>
  <td>0</td>
  <td>
    <p id="elementSimilarity(name)">
      Aggregated similarity between the query and individual field  elements.
      The same sub-scores used by the <code>textSimilarity</code> feature
      are calculated for each individual element in the field.
      The final output is calculated as the maximum of the combined element
      similarity measures (similarity measures are combined the same way as
      the default output of the <code>textSimilarity</code> feature)
      multiplied with the element weight which is 1 for arrays,
      and the supplied weights for indexed weighted sets.
    </p>
    <p>
      This is a flexible feature;
      how sub-scores are combined for each element and how element scores are aggregated may be configured.
      You may also add additional outputs if you want to capture multiple signals from a single field.
      Use <a href="rank-feature-configuration.html#elementSimilarity">elementSimilarity</a> to customize this feature.
    </p>
  </td></tr>






<tr><td colspan="3"></td></tr>
<tr><td colspan="3">
  <h3 id="attribute-match-features-normalized">Attribute match features - normalized</h3></td></tr>
<tr class="trx"><th class="thx">Feature name</th><th class="thx">Default</th><th class="thx">Description</th></tr>

<tr><td>attributeMatch(<em>name</em>)</td>
  <td>0</td>
  <td>
    <p id="attributeMatch(name)">
    A normalized measure of the degree to which this query and field matched. This is currently the same as completeness.
    Note that depending on what the attribute is used for, this may or may not be a suitable metric.
    If the attribute is a weighted set representing counts of items (like tags),
    <code>normalizedWeight</code> is probably a better metric.
    </p>
  </td></tr>

 <tr><td>attributeMatch(<em>name</em>).completeness</td>
   <td>0</td>
   <td>
     <p id="attributeMatch(name).completeness">
       The normalized total completeness, where field completeness is more important:
     </p><p>
     <code>queryCompleteness * ( 1 - <a href="rank-feature-configuration.html#attributeMatch">fieldCompletenessImportance</a> +
       <a href="rank-feature-configuration.html#attributeMatch">fieldCompletenessImportance</a> * fieldCompleteness )</code>
     </p>
   </td></tr>

<tr><td>attributeMatch(<em>name</em>).queryCompleteness</td>
  <td>0</td>
  <td>
    <p id="attributeMatch(name).queryCompleteness">The query completeness for this attribute:</p>
    <p><code>matches/the number of query terms searching this attribute</code></p></td></tr>

<tr><td>attributeMatch(<em>name</em>).fieldCompleteness</td>
  <td>0</td>
  <td>
    <p id="attributeMatch(name).fieldCompleteness">
    The normalized ratio of query tokens which was matched in the field.
    For arrays: <code>matches/array length</code>
    For weighted sets: <code>sum of weight of matched terms/sum of weights of entire set</code>.
    This is relatively expensive to calculate for large weighted sets.
    </p>
  </td></tr>

<tr><td>attributeMatch(<em>name</em>).normalizedWeight</td>
  <td>0</td>
  <td>
    <p id="attributeMatch(name).normalizedWeight">
      A number which is close to 1 if the attribute weights of most matches in a weighted set are high
      (relative to <a href="rank-feature-configuration.html#attributeMatch">maxWeight</a>), 0 otherwise
    </p>
  </td></tr>

<tr><td>attributeMatch(<em>name</em>).normalizedWeightedWeight</td>
  <td>0</td>
  <td>
    <p id="attributeMatch(name).normalizedWeightedWeight">
    A number which is close to 1 if the attribute weights of most matches in a weighted set are high
    (relative to <a href="rank-feature-configuration.html#attributeMatch">maxWeight</a>),
    and where highly weighted query terms has more impact, 0 otherwise
    </p>
  </td></tr>

<tr>
  <td>closeness(<em>dimension</em>,<em>name</em>)</td>
  <td>0</td>
  <td><p id="closeness(dimension,name)">
    Used with the <a href="../querying/yql.html#nearestneighbor">nearestNeighbor</a> query operator.
    A number which is close to 1 when a point vector in the document is close
    to a matching point vector in the query.
    The document vectors and the query vector must be the same tensor
    type, with one indexed dimension of size N, representing a point in an N-dimensional space.
  </p>
    <ul>
      <li>
        <p>
          <em>dimension</em>: Specifies the dimension of <em>name</em>.
          This must be either the string <code>field</code> or the string <code>label</code>.
        </p>
        <p>
          When using <code>field</code>, the name given must be a field with a tensor attribute of appropriate type.
          Often used when the document type has only one vector field,
          see <a href="../../querying/nearest-neighbor-search#minimal-example">example</a>.
        </p>
        <p>
          When using <code>label</code>, queries are assumed to contain a
          <a href="../querying/yql.html#nearestneighbor">nearestNeighbor</a> query item
          with a <a href="../querying/yql.html#label">label</a> that matches the given <em>name</em>.
          This is useful when having multiple vector fields, where <code>closeness()</code> then maps
          to the nearestNeighbor operator with the field configured.
          <a href="../../querying/nearest-neighbor-search-guide#using-label">Example</a>.
        </p>
      </li>
      <li> <em>name</em>: The value of the field name or label.
      </li>
    </ul>
    <p>
      {% include note.html content="<code>closeness()</code> is calculated <strong>only</strong> based on the vectors
      matched with nearestNeighbor operator.
      This means that the value of <code>closeness()</code> is not necessarily calculated based on the same vector
      returned by <code>closest()</code> rank feature if nearestNeighbor search is approximate, as
      <code>closest()</code> will be calculated based on <em>all</em> specified document vectors." %}
    </p>
    <p>
    The output value is
    $$ closeness(dimension,name) = \frac{1.0}{1.0 + distance(dimension,name)}$$
    </p>
    <p>
    When the tensor field stores multiple vectors per document, the minimum distance
    between the vectors of a document and the query vector is used in the calculation above.
    </p>
  </td></tr>

<tr><td>freshness(<em>name</em>)</td>
  <td>0</td>
  <td><p id="freshness(name)">
    A number which is close to 1 if the timestamp in attribute <em>name</em> is recent compared to the current time
     compared to <a href="rank-feature-configuration.html#freshness">maxAge</a>:
     </p><p>
     <code>max( 1-age(name)/maxAge , 0 )</code>
     </p><p>
     Scales linearly with age, see <a href="#freshness">freshness plot</a>.
  </td></tr>

<tr><td>freshness(<em>name</em>).logscale</td>
  <td>0</td>
  <td><p id="freshness(name).logscale">
    A logarithmic-shaped freshness; also goes from 1 to 0, but looks like <a href="#freshness">freshness plot</a>.
    The function is based on <code>-log(age(name) + scale)</code> and is calculated as:
    </p><p class="equation-container" class="equation-container"><!-- depends on mathjax -->
    $$\frac{log(maxAge + scale) - log(age(name) + scale)}{log(maxAge + scale) - log(scale)}$$
    </p><p>
    where scale is defined using
    <a href="rank-feature-configuration.html#freshness"> halfResponse and maxAge</a>:
    </p><p class="equation-container" class="equation-container"><!-- depends on mathjax -->
    $$\frac{-halfResponse^2}{2 &times; halfResponse - maxAge}$$
    </p><p>
    When <code>age(name) == halfResponse</code> the function output is 0.5.</p>
  </td></tr>






<tr><td colspan="3"></td></tr>
<tr><td colspan="3"><h3 id="attribute-match-features-normalized-and-relative-to-the-whole-query">
  Attribute match features - normalized and relative to the whole query</h3></td></tr>
<tr class="trx"><th class="thx">Feature name</th><th class="thx">Default</th><th class="thx">Description</th></tr>

<tr><td>attributeMatch(<em>name</em>).weight</td>
  <td>0</td>
  <td>
    <p id="attributeMatch(name).weight">
      This has the same semantics as fieldMatch(<em>name</em>).weight.
    </p>
  </td></tr>

<tr><td>attributeMatch(<em>name</em>).significance</td>
  <td>0</td>
  <td>
    <p id="attributeMatch(name).significance">
      This has the same semantics as fieldMatch(<em>name</em>).significance.
    </p>
  </td></tr>

<tr><td>attributeMatch(<em>name</em>).importance</td>
  <td>0</td>
  <td>
    <p id="attributeMatch(name).importance">
      Returns the average of significance and weight. This has the same properties as those metrics.
    </p>
  </td></tr>






<tr><td colspan="3"></td></tr>
<tr><td colspan="3">
  <h3 id="attribute-match-features-not-normalized">Attribute match features - not normalized</h3></td></tr>
<tr class="trx"><th class="thx">Feature name</th><th class="thx">Default</th><th class="thx">Description</th></tr>

<tr><td>attributeMatch(<em>name</em>).matches</td>
  <td>0</td>
  <td><p id="attributeMatch(name).matches">The number of query terms which was matched in this attribute</p></td></tr>

<tr><td>attributeMatch(<em>name</em>).totalWeight</td>
  <td>0</td>
  <td>
    <p id="attributeMatch(name).totalWeight">
      The sum of the weights of the attribute keys matched in a weighted set attribute
    </p>
  </td></tr>

<tr><td>attributeMatch(<em>name</em>).averageWeight</td>
  <td>0</td>
  <td><p id="attributeMatch(name).averageWeight">totalWeight/matches</p></td></tr>

<tr><td>attributeMatch(<em>name</em>).maxWeight</td>
  <td>0</td>
  <td>
    <p id="attributeMatch(name).maxWeight">
      The maximum weight of the attribute keys matched in a weighted set attribute
    </p>
  </td></tr>

<tr><td>closest(<em>name</em>)</td>
  <td>{}</td>
  <td><p id="closest(name)">
    Used with the
    <a href="../querying/yql.html#nearestneighbor">nearestNeighbor</a>
    query operator and a tensor field attribute <em>name</em> storing multiple vectors per document.
    This feature returns a tensor with one or more mapped dimensions and one point with a value of 1.0,
    where the label of that point indicates which document vector was closest to the
    query vector in the nearest neighbor search.
    </p>
    <p>
    Given a tensor field with type <code>tensor&lt;float&gt;(m{},x[3])</code>
    used with the <em>nearestNeighbor</em> operator,
    an example output of this feature is:
    </p>
<pre>
    tensor&lt;float&gt;(m{}):{ 3: 1.0 }
</pre>
    <p>
    In this example, the document vector with label <em>3</em> in the mapped <em>m</em> dimension
    was closest to the query vector.
    </p>
  </td></tr>


<tr><td>closest(<em>name</em>,<em>label</em>)</td>
  <td>{}</td>
  <td><p id="closest(name,label)">
    Used with the
    <a href="../querying/yql.html#nearestneighbor">nearestNeighbor</a>
    query operator tagged with a
    <a href="../../ranking/multivalue-query-operators.html#raw-scores-and-query-item-labeling">label</a> <em>label</em>
    and a tensor field attribute <em>name</em> storing multiple vectors per document.
    </p>
    <p>
    See <a href="#closest(name)">closest(name)</a> for details.
    </p>
  </td></tr>


<tr><td>distance(<em>dimension</em>,<em>name</em>)</td>
  <td>max double value</td>
  <td><p id="distance(dimension,name)">
    Used with the
    <a href="../querying/yql.html#nearestneighbor">nearestNeighbor</a>
    query operator.
    A number which is close to 0 when a point vector in the document is close
    to a matching point vector in the query.
    The document vectors and the query vector must be the same tensor
    type, with one indexed dimension of size N, representing a point in an N-dimensional space.
    <ul>
    <li>
      <p>
        <em>dimension</em>: Specifies the dimension of <em>name</em>.
        This must be either the string <code>field</code> or the string <code>label</code>.
      </p>
      <p>
        When using <code>field</code>, the name given must be a field with a tensor attribute of appropriate type.
        Often used when the document type has only one vector field,
        see <a href="../../querying/nearest-neighbor-search#minimal-example">example</a>.
      </p>
      <p>
        When using <code>label</code>, queries are assumed to contain a
        <a href="../querying/yql.html#nearestneighbor">nearestNeighbor</a> query item
        with a <a href="../querying/yql.html#label">label</a> that matches the given <em>name</em>.
        This is useful when having multiple vector fields, where <code>distance()</code> then maps
        to the nearestNeighbor operator with the field configured.
        <a href="../../querying/nearest-neighbor-search-guide#using-label">Example</a>.
      </p>
    </li>
      <li> <em>name</em>: The value of the field name or label.
      </li>
    </ul>
    <p>
    The output value depends on the
    <a href="../schemas/schemas.html#distance-metric">distance metric</a> used.
    The default is the Euclidean distance between the "n"-dimensional
    query point "d" and the point "d" in the document tensor field:
    $$ distance = \sqrt{\sum_{i=1}^n (q_i - d_i)^2} $$
    </p>
    <p>
    When the tensor field stores multiple vectors per document, the minimum distance
    between the vectors of a document and the query vector is used in the calculation above.
    </p>
  </td></tr>

<tr><td>age(<em>name</em>)</td>
  <td>10B</td>
  <td>
    <p id="age(name)">
    The document age in seconds relative to the unit time value
    stored in the attribute having this name
    </p>
  </td></tr>






<tr><td colspan="3"></td></tr>
<tr><td colspan="3"><h3 id="features-combining-multiple-fields-and-attributes">
  Features combining multiple fields and attributes</h3></td></tr>
<tr class="trx"><th class="thx">Feature name</th><th class="thx">Default</th><th class="thx">Description</th></tr>

<tr><td>match</td>
  <td>0</td>
  <td>
    <p id="match">
    A normalized average of the fieldMatch and attributeMatch scores of all the searched fields
    and attributes, where the contribution of each field and attribute is weighted by its
    <em>weight</em> setting.
    </p>
  </td></tr>

<tr><td>match.totalWeight</td>
  <td>0</td>
  <td>
    <p id="match.totalWeight">
      The sum of the weight settings of all the field and attributes searched by the query
    </p>
  </td></tr>

<tr><td>match.weight.<em>name</em></td>
  <td>100</td>
  <td><p id="match.weight.name">The (schema) weight setting of a field or attribute</p></td></tr>






<tr><td colspan="3"></td></tr>
<tr><td colspan="3">
  <h3 id="rank-scores">Rank scores</h3></td></tr>
<tr class="trx"><th class="thx">Feature name</th><th class="thx">Default</th><th class="thx">Description</th></tr>

<tr><td>bm25(field)</td>
  <td>0</td>
  <td>
    <p id="bm25">
    Calculates the <a href="https://en.wikipedia.org/wiki/Okapi_BM25">Okapi BM25</a>
    ranking function over the given <a href="../schemas/schemas.html#indexing-index">indexed string field</a>.
    This feature is cheap to compute, about 3-4 times faster than nativeRank,
    while still providing a good rank score quality wise.
    This feature is a good candidate for usage in a first phase ranking function when ranking text documents.
    Note that the field must be enabled to be used with the bm25 feature;
    set the <em>enable-bm25</em> flag in the <a href="../schemas/schemas.html#index">index</a>
    section of the field definition.
    See the <a href="../../ranking/bm25.html">BM25 Reference</a> for more detailed information.
    </p>
  </td></tr>

<tr>
  <td>elementwise(bm25(field),dimension,cell_type)</td>
  <td><code>tensor&lt;cell_type&gt;(dimension{}):{}</code></td>
  <td>
    <p id="elementwise-bm25">
      Calculates the <a href="https://en.wikipedia.org/wiki/Okapi_BM25">Okapi BM25</a>
      ranking function over each element in the given <em>multi-valued</em> <a href="../schemas/schemas.html#indexing-index">indexed string field</a> and creates a tensor with a single mapped dimension containing the bm25 score for each matching element.
      The element indexes (starting at 0) are used as dimension labels.
      This feature is more expensive than <a href="#bm25">bm25</a>,
      does not need the <em>enable-bm25</em> flag and can be tuned with
      <a href="rank-feature-configuration.html#elementwise-bm25">rank properties</a>.
    </p>
    <p>
      The <em>cell_type</em> parameter can be omitted (the default value is <code>double</code>) except when setting rank properties.
    </p>
    <p>
      Example: If the <code>content</code> field is of type <code>array&lt;string&gt;</code>
      where query terms are found in elements 2 and 5 then the feature
      <code>elementwise(bm25(content),x,float)</code> as a summary feature
      might be shown as:
    </p>
<pre>
"elementwise(bm25(content),x,float)": {
  "type": "tensor<float>(x{})",
  "cells": {
    "2": 0.5112776,
    "5": 0.1021805
  }
}
</pre>
  </td>
</tr>

<tr><td>nativeRank</td>
  <td>0</td>
  <td>
    <p id="nativeRank">
    A reasonably good rank score which is computed cheaply by Vespa.
    This value only is a good candidate first phase ranking function,
    and is the default used in the default rank profile.
    The value computed by this function may change between Vespa versions.
    See the <a href="nativerank.html">native rank reference</a> for more information.
    </p>
  </td></tr>

<tr><td>nativeRank(field,...)</td>
  <td>0</td>
  <td>
    <p id="nativeRank(field,...)">
      Same as <em>nativeRank</em>, but only the given set of fields are used in the calculation.
    </p>
  </td></tr>

<tr><td>nativeFieldMatch</td>
  <td>0</td>
  <td>
    <p id="nativeFieldMatch">
    Captures how well query terms match in index fields. Used by <em>nativeRank</em>.
    See the <a href="nativerank.html">native rank reference</a> for more information.
    </p>
  </td></tr>

<tr><td>nativeFieldMatch(field,...)</td>
  <td>0</td>
  <td>
    <p id="nativeFieldMatch(field,...)">
      Same as <em>nativeFieldMatch</em>, but only the given set of index fields are used in the calculation.
    </p>
  </td></tr>

<tr><td>nativeProximity</td>
  <td>0</td>
  <td>
    <p id="nativeProximity">
    Captures how near matched query terms occur in index fields. Used by <em>nativeRank</em>.
    See the <a href="nativerank.html">native rank reference</a> for more information.
    </p>
  </td></tr>

<tr><td>nativeProximity(field,...)</td>
  <td>0</td>
  <td>
    <p id="nativeProximity(field,...)">
      Same as <em>nativeProximity</em>, but only the given set of index fields are used in the calculation.
    </p>
  </td></tr>

<tr><td>nativeAttributeMatch</td>
  <td>0</td>
  <td>
    <p id="nativeAttributeMatch">
    Captures how well query terms match in attribute fields. Used by <em>nativeRank</em>.
    See the <a href="nativerank.html">native rank reference</a> for more information.
    </p>
  </td></tr>

<tr><td>nativeAttributeMatch(field,...)</td>
  <td>0</td>
  <td>
    <p id="nativeAttributeMatch(field,...)">
      Same as <em>nativeAttributeMatch</em>, but only the given set of attribute fields are used in the calculation.
    </p>
  </td></tr>

<tr><td>nativeDotProduct(field)</td>
  <td>0</td>
  <td><p id="nativeDotProduct(field)">
    Calculates the sparse dot product between query term weights and match weights for the given field.
    Example: A weighted set string field X:
  </p>
<pre>
"X": {
    "x": 10,
    "y": 20,
    "z": 30
}
</pre>
    <p>
    For the query (x!2 OR y!4), the nativeDotProduct(X) feature
    will have the value 100 (10*2+20*4) for that document.
    </p>
    {% include note.html content='<code>nativeDotProduct</code> and <code>nativeDotProduct(field)</code>
    is less optimal for computing the dot product -
    consider using <a href="#dotProduct(name,vector)">dotProduct(name,vector)</a>.'%}
  </td></tr>

<tr><td>nativeDotProduct</td>
  <td>0</td>
  <td><p id="nativeDotProduct">
    Calculates the sparse dot product between query term weights and match weights as above, but for all term/field combinations.
  </td></tr>

<tr><td>firstPhase</td>
  <td>0</td>
  <td>
    <p id="firstPhase">
      The value of the rank score calculated in the first phase (unavailable in first phase ranking expressions)
    </p>
  </td></tr>

<tr><td>secondPhase</td>
  <td>0</td>
  <td>
    <p id="secondPhase">
      The value of the rank score calculated in the second phase (unavailable in first phase and second phase ranking expressions)
    </p>
  </td></tr>

<tr><td>firstPhaseRank</td>
  <td>max double value</td>
  <td>
    <p id="firstPhaseRank">
      The rank of the document after first phase within the content node when selecting which documents to rerank in second phase. The best document after first phase has rank 1, the second best 2, etc. The feature returns the default value for documents not selected for second phase ranking and for unsupported cases
      (<a href="../../performance/streaming-search.html#differences-in-streaming-search">streaming search</a>,
      <a href="../schemas/schemas.html#summary-features">summary features</a>, first phase expressions). Multiple documents can have the same <em>firstPhaseRank</em> value in multi-node configurations.
    </p>
  </td></tr>

<tr><td>relevanceScore</td>
    <td>-</td>
    <td>
        <p id="relevancescore">
            The value of the rank score calculated either in the first or (when defined) in the second phase (unavailable in first phase and second phase ranking expressions) (since 8.559.30).
        </p>
    </td></tr>

<tr><td colspan="3"></td></tr>
<tr><td colspan="3"><h3 id="global-features">Global features</h3></td></tr>
<tr class="trx"><th class="thx">Feature name</th><th class="thx">Default</th><th class="thx">Description</th></tr>

<tr><td>globalSequence</td>
  <td>n/a</td>
  <td>
    <p id="globalSequence">
      A global sequence number computed as (1 &lt;&lt; 48) - (LocalDocumentId &lt;&lt; 16 || <a href="../applications/services/content.html#node">distribution-key</a>).
      This will give a global sequence to documents. This is a cheap way of having stable ordering of documents. Note the large range of this value.
      Also note that if the system is not stable, e.g. if documents move around due to new nodes coming in, or nodes being removed, it will no longer
      be stable as documents might be found in a different replica. If you need true global ordering we suggest assigning a unique numeric id
      to your documents as an <a href="../schemas/schemas.html#attribute">attribute</a> field and use
      the <a href="#attribute(name)">attribute(name)</a> feature.
    </p>
  </td></tr>

<tr><td>now</td>
  <td>n/a</td>
  <td><p id="now">Time at which the query is executed in unix-time (seconds since epoch)</p></td></tr>

<tr><td>random</td>
  <td>n/a</td>
  <td>
    <p id="random">
    A pseudorandom number in the range [0,1&gt; which is drawn once per document during rank evaluation.
    By default, the current time in microseconds is used as a seed value.
    Users can specify a seed value by setting
    <a href="rank-feature-configuration.html#random">random.seed</a> in the rank profile.
    If you need several independent random numbers the feature can be named like this:
    <code>random(foo)</code>, <code>random(bar)</code>.
    </p>
  </td></tr>

<tr><td>random.match</td>
  <td>n/a</td>
  <td>
    <p id="random.match">
    A pseudorandom number in the range [0,1&gt; that is stable for a given hit.
    This means that a hit will always receive the same random score (on a single node).
    If it is required that the scores be different between different queries,
    specify a seed value dependent upon the query. By default, the seed value is 1024.
    Users can specify a seed value by adding the query parameter
    <a href="../api/query.html#ranking.properties">rankproperty.random.match.seed=&lt;value&gt;</a>.
    If you need several independent random numbers the feature can be named like this:
    <code>random(foo).match</code>, <code>random(bar).match</code>.
    </p>
  </td></tr>

<tr><td>randomNormal(<em>mean</em>,<em>stddev</em>)</td>
  <td>0.0,1.0</td>
  <td>
    <p id="randomNormal(mean,stddev)">
    Same as <a href="#random">random</a>, except the random number is drawn from
    the Gaussian distribution using the supplied mean and stddev parameters.
    Can be called without parameters; default values are assumed.
    Seed is set similarly as <em>random</em>.
    If you need several independent random numbers with the same parameters,
    the feature can be named like this: <code>randomNormal(0.0,1.0,foo)</code>,
    <code>randomNormal(0.0,1.0,bar)</code>.
    If the parameters to <em>randomNormal</em> are not the same,
    you do not need to supply an additional name,
    e.g. <code>randomNormal(0.0, 0.1)</code> and <code>randomNormal(0.0, 0.5)</code>
    results in two independent values.
    </p>
  </td></tr>

<tr><td>randomNormalStable(<em>mean</em>,<em>stddev</em>)</td>
  <td>0.0,1.0</td>
  <td>
    <p id="randomNormalStable(mean,stddev)">
    Same as <a href="#randomNormal(mean,stddev)">randomNormal</a>,
    except that the generated number is stable for a given hit, similar to
    <a href="#random.match">random.match</a>.
    </p>
  </td></tr>

<tr><td>constant(<em>name</em>)</td>
  <td>n/a</td>
  <td>
    <p id="constant(name)">Returns the <a href="../schemas/schemas.html#constant">constant</a> tensor value.</p>
  </td></tr>






<tr><td colspan="3"></td></tr>
<tr><td colspan="3"><h3 id="match-operator-scores">Match operator scores</h3></td></tr>
<tr><td colspan="3">
    See <a href="../../ranking/multivalue-query-operators.html#raw-scores-and-query-item-labeling">
    Raw scores and query item labeling</a>
  </td></tr>
<tr class="trx"><th class="thx">Feature name</th><th class="thx">Default</th><th class="thx">Description</th></tr>

<tr><td>rawScore(<em>field</em>)</td>
  <td>0</td>
  <td><p id="rawScore(field)">The sum of all raw scores produced by match operators for this field.</p></td></tr>

<tr><td>itemRawScore(<em>label</em>)</td>
  <td>0</td>
  <td><p id="itemRawScore(label)">The raw score produced by the query item with the given label.</p></td></tr>



<tr><td colspan="3"></td></tr>
<tr><td colspan="3"><h3 id="geo-search">Geo search</h3></td></tr>
<tr><td colspan="3">
    These features are for ranking on the distances between geographical coordinates, i.e. points on the surface of the earth defined by latitude/longitude pairs. See the main documentation for <a href="../../querying/geo-search.html">
    Geo Search</a>.
    {% include note.html content='Some of these features have the same names as features used with the <a href="../querying/yql.html#nearestneighbor">nearestNeighbor</a> query operator. Take care not to get them mixed up!'%}
  </td></tr>
<tr class="trx"><th class="thx">Feature name</th><th class="thx">Default</th><th class="thx">Description</th></tr>


<tr><td>closeness(<em>name</em>)</td>
  <td>0</td>
  <td><p id="closeness(name)">
    A number which is close to 1 if the position in attribute <em>name</em> is close to the query position compared
    to <a href="rank-feature-configuration.html#closeness">maxDistance</a>:
    </p><p>
    <code>max(1-distance(name)/maxDistance , 0)</code>
    </p><p>
    Scales linearly with distance, see <a href="#closeness">closeness plot</a>.</p>
  </td></tr>

<tr><td>closeness(<em>name</em>).logscale</td>
  <td>0</td>
  <td><p id="closeness(name).logscale">
    A logarithmic-shaped closeness; like normal closeness it goes from 1 to 0,
    but looks like <a href="#closeness">closeness plot</a>.
    The function is a logarithmic fall-off based on
    <code>log(distance + scale)</code> and is calculated as:
    </p><p class="equation-container"><!-- depends on mathjax -->
    $$closeness(name).logscale = \frac{log(maxDistance + scale) - log(distance(name) + scale))}{(log(maxDistance + scale) - log(scale))}$$
    </p><p>
    where scale is defined using
    <a href="rank-feature-configuration.html#closeness">halfResponse and maxDistance</a>:
    </p><p class="equation-container"><!-- depends on mathjax -->
    $$scale = \frac{halfResponse^2}{(maxDistance - 2 &times; halfResponse)}$$
    </p><p>
    When <code>distance(name) == halfResponse</code> the function output is 0.5;
    halfResponse should be less than <code>maxDistance/2</code> since that means
    adding a certain distance when you are close matters more than adding
    the same distance when you're already far away.</p>
</td></tr>

<tr><td>distance(<em>name</em>)</td>
  <td>6400M</td>
  <td>
    <p id="distance(name)">
      The Euclidean distance from the query position to the given position attribute in millionths of degrees (about 10 cm).
      If there are multiple positions in the query, items that actually search in <em>name</em> is preferred.
      Also: if multiple query items search in <em>name</em>, or <em>name</em> is an array of positions, or both,
      the closest distance found is returned.
    </p>
  </td></tr>

<tr><td>distance(<em>name</em>).km</td>
  <td>711648.5</td>
  <td>
    <p id="distance(name).km">
      As above, but scaled, so it uses the kilometer as unit of distance, instead of "micro-degrees".
    </p>
  </td></tr>

<tr><td>distance(<em>name</em>).index</td>
  <td>-1</td>
  <td>
    <p id="distance(name).index">
      The array index of the closest position found.
      Useful when <em>name</em> is of <code>array&lt;position&gt;</code> type.
    </p>
  </td></tr>

<tr><td>distance(<em>name</em>).latitude</td>
  <td>90</td>
  <td>
    <p id="distance(name).latitude">
      The latitude (geographical north-south coordinate) of the closest position found.
      In range from -90.0 (South Pole) to +90.0 (North Pole).
      Useful when <em>name</em> is of <code>array&lt;position&gt;</code> type.
    </p>
  </td></tr>

<tr><td>distance(<em>name</em>).longitude</td>
  <td>-180</td>
  <td>
    <p id="distance(name).longitude">
      The latitude (geographical east-west coordinate) of the closest position found.
      In range from -180.0 (extreme west) to +180.0 (extreme east).
      Useful when <em>name</em> is of <code>array&lt;position&gt;</code> type.
    </p>
  </td></tr>

<tr><td>distanceToPath(<em>name</em>).distance</td>
  <td>6400M</td>
  <td>
    <p id="distanceToPath(name).distance">
    The Euclidean distance from a path through 2d space
    given in the query to the given position attribute in
    millionths of degrees. This is useful e.g. for finding the
    closest locations to a given road. The query path is set in the
    <a href="../api/query.html#ranking.properties">rankproperty.distanceToPath(<em>name</em>).path</a>
    query parameter, using syntax <code>"(x1,y1,x2,y2,..)"</code>
    also in millionth of degrees, see the
    <a href="../../querying/geo-search.html#distance-to-path">distance to path</a> example.
    The closest point along the path is referred to as the <em>intersection</em>.
    </p>
    {% include note.html content="For documents with multiple locations,
    only the closest location is used for ranking purposes."%}
  </td></tr>

<tr><td>distanceToPath(<em>name</em>).traveled</td>
  <td>1</td>
  <td>
    <p id="distanceToPath(name).traveled">
    The normalized distance along the query path traveled before intersection
    (0.0 indicates start of path, 0.5 is middle, and 1.0 is end of path).
    </p>
  </td></tr>

<tr><td>distanceToPath(<em>name</em>).product</td>
  <td>0</td>
  <td>
    <p id="distanceToPath(name).product">
    The cross-product of the intersected path segment and the intersection-to-document vector.
    Given that the document was found to lie closest to the path element <code>A->B</code>,
    the intersected path segment vector is <code>[ B.x - A.x, B.y - A.y ]</code>.
    Furthermore, given that the intersection of that path element
    occurred at point <code>I</code> for document location <code>D</code>,
    the intersection-to-document vector is <code>[ I.x - D.x, I.y - D.y]</code>.
    This is useful e.g. for finding what side of a path a document exists
    by looking at the sign of this value.
    </p>
  </td></tr>


<tr><td colspan="3"></td></tr>
<tr><td colspan="3"><h3 id="utility-features">Utility features</h3></td></tr>
<tr class="trx"><th class="thx">Feature name</th><th class="thx">Default</th><th class="thx">Description</th></tr>

<tr>
  <td>foreach(<em>dimension</em>, <em>variable</em>, <em>feature</em>, <em>condition</em>, <em>operation</em>)</td>
  <td>n/a</td>
  <td>
        <p id="foreach(dimension,variable,feature,condition,operation)">
        <em>foreach</em> iterates over a set of feature output values and performs an operation on them.
        Only the values where the condition evaluates to true are considered for the operation.
        The result of this operation is returned.
        </p>
        <ul>
          <li> <em>dimension</em>: Specifies what to iterate over. This can be:
          <ul>
            <li> <em>terms</em>: All query term indices, from 0 and up to
              <a href="rank-feature-configuration.html#foreach">maxTerms</a>.
            </li> <li> <em>fields</em>: All index field names.
            </li> <li> <em>attributes</em>: All attribute field names.
          </ul>
          </li> <li> <em>variable</em>: The name of the variable 'storing' each of the items you are iterating over.
          </li> <li> <em>feature</em>: The name of the feature you want to use the output value from. Use the <em>variable</em> as part of the feature name, and for each item you iterate over this <em>variable</em> is replaced with the actual item.
            Note that the variable replacement is a simple string replace, so you should use a variable name
            that is not in conflict with the feature name.
          </li> <li> <em>condition</em>: The condition used on each feature output value to find out if the value should be considered by the operation. The condition can be:
          <ul>
            <li> <em>&gt;a</em>: Use feature output if greater than number a.
            </li> <li> <em>&lt;a</em>: Use feature output if less than number a.
            </li> <li> <em>true</em>: Use all feature output values.
          </ul>
          </li> <li> <em>operation</em>: The operation you want to perform on the feature output values. This can be:
          <ul>
            <li> <em>sum</em>: Calculate the sum of the values.
            </li> <li> <em>product</em>: Calculate the product of the values.
            </li> <li> <em>average</em>: Calculate the average of the values.
            </li> <li> <em>max</em>: Find the max of the values.
            </li> <li> <em>min</em>: Find the min of the values.
            </li> <li> <em>count</em>: Count the number of values.
          </ul>
        </ul>
        <p>
        Let's say you want to calculate the average score of the <em>fieldMatch</em> feature for all index fields,
        but only consider the scores larger than 0. Then you can use the following setup of the <em>foreach</em> feature:
        </p><p>
        <code>foreach(fields,N,fieldMatch(N), "&gt;0", average)</code>.
        </p><p>
        Note that when using the conditions <em>&gt;a</em> and <em>&lt;a</em>
        the arguments must be quoted.
        </p><p>
        You can also specify a ranking expression in the <em>foreach</em> feature by using the <em>rankingExpression</em> feature.
        The <em>rankingExpression</em> feature takes the expression as the first and only parameter and
        outputs the result of evaluating this expression.
        Let's say you want to calculate the average score of the squared <em>fieldMatch</em> feature score for all index fields.
        Then you can use the following setup of the <em>foreach</em> feature:
        </p><p>
        <code>foreach(fields, N, rankingExpression("fieldMatch(N)*fieldMatch(N)"), true, average)</code>
        </p><p>
        Note that you must quote the expression passed in to the <em>rankingExpression</em> feature.
        </p>
  </td></tr>

<tr><td>dotProduct(<em>name</em>,<em>vector</em>)</td>
    <td>0</td>
    <td>
      <p id="dotProduct(name,vector)"></p>
      {% include note.html content='Most dot product use cases are better solved using
      <a href="../../ranking/tensor-user-guide.html">tensors</a>.'%}
      <p>
      The sparse dot product of the vector represented by the given weighted set attribute and
      the vector sent down with the query.
      </p><p>
      You can also do an ordinary full dotproduct by using arrays
      instead of weighted sets. This will be a lot faster when you have full vectors in the document with
      more than 5-10% non-zero values. You are also then not limited to integer weights. All the numeric
      datatypes can be used with arrays, so you have full floating point support.
      The 32 bit floating point type yields the fastest execution.
      <ul>
        <li> <em>name</em>:   The name of the weighted set string/integer or array of numeric attribute.
        <li> <em>vector</em>: The name of the vector sent down with the query.
      </ul>
      <p>
      Each unique string/integer in the weighted set corresponds to a dimension
      and the belonging weight is the vector component for that dimension.
      The query vector is set in the
      <a href="../api/query.html#ranking.properties">rankproperty.dotProduct.<em>vector</em></a>
      query parameter, using syntax
      <code>{d1:c1,d2:c2,&hellip;}</code> where <em>d1</em> and <em>d2</em> are dimensions matching the strings/integers in
      the weighted set and <em>c1</em> and <em>c2</em> are the vector components (floating point numbers).
      The number of dimensions in the weighted set and the query vector do not need to be the same.
      When calculating the dot product we only use the dimensions present in both the weighted set and the
      query vector.
      </p><p>
      When using an array the dimensions is a positive integer starting at 0. If the query is sparse all non given dimensions
      are zero. That also goes for dimensions that outside of the array size in each document.
      </p><p>
      Assume a weighted set string attribute X with:
<pre>
"X": {
    "x": 10,
    "y": 20
}
</pre>
      <p>
      for a particular document.
      The result of using the feature dotProduct(X,Y) with the query vector
      rankproperty.dotProduct.Y={x:2,y:4} will then be 100 (10*2+20*4) for this document.
      </p><p>
      Arrays can be passed down as <code>[w1 w2 w3 &hellip;]</code> or on sparse form <code>{d1:c1,d2:c2,&hellip;}</code>
      as is already supported for weighted sets.
      </p>
      {% include note.html content='When the query vector ends up being the same as the query,
      it is better to annotate the query terms with weights
      (see <a href="../querying/simple-query-language.html#term-weight">term weight</a>)
      and use the nativeDotProduct feature instead.
      This will run more efficiently and improve the correlation between
      results produced by the WAND operator and the final relevance score.'%}
      {% include note.html content='When using the dotProduct feature,
      <a href="../../content/attributes.html#fast-search">fast-search</a> is not needed,
      unless also used for searching.
      When using the dotProduct query operator, use fast-search.'%}
    </td></tr>

<tr>
    <td>tokenInputIds(<em>length</em>, <em>input_1</em>, <em>input_2</em>, <em>...</em>)</td>
    <td>n/a</td>
    <td>
        <p id="tokenInputIds(length, input_1, input_2, ...)">
        Convenience function for generating token sequence input to Transformer models.
        Creates a tensor with dimensions <code>d0[1], d1[length]</code>, where
        <code>d0</code> is the batch dimension and <code>d1</code> is the maximum length
        of the token sequence. Assumes the inputs are zero-padded tensors representing
        token sequences. The result is the token sequence:
        </p>

        <p>
        <code>CLS + input_1 + SEP + input_2 + SEP + ... + 0's</code>
        </p>

        <ul>
            <li><em>length</em>:  The maximum length of the token sequence</li>
            <li><em>input_N</em>: Where to retrieve input from. At least one is required.</li>
        </ul>

        <p>
        The inputs are typically retrieved from the query, document attributes or constants.
        For instance, <code>tokenInputIds(128, query(my_input), attribute(my_field))</code>
        where input types are:
        </p>

        <ul>
            <li><code>query(my_input): tensor(d0[32])</code></li>
            <li><code>attribute(my_field): tensor(d0[128])</code></li>
        </ul>

        <p>
        will create a tensor of type <code>d0[1],d1[128]</code> consisting of the CLS token
        <code>101</code>, the tokens from the query, the SEP token <code>102</code>, the
        tokens from the document field, the SEP token <code>102</code>, and 0's for the
        rest of the tensor.
        </p>
    </td>
</tr>

<tr>
  <td>customTokenInputIds(<em>start_sequence_id</em>, <em>sep_sequence_id</em><em>length</em>, <em>input_1</em>, <em>input_2</em>, <em>...</em>)</td>
  <td>n/a</td>
  <td>
      <p id="customTokenInputIds(start_sequence_id, sep_sequence_id, length, input_1, input_2, ...)">
      Convenience function for generating token sequence input to Transformer models.
      Creates a tensor with dimensions <code>d0[1], d1[length]</code>, where
      <code>d0</code> is the batch dimension and <code>d1</code> is the maximum length
      of the token sequence. Assumes the inputs are zero-padded tensors representing
      token sequences. The result is the token sequence:
      </p>

      <p>
      <code>start_sequence_id + input_1 + sep_sequence_id + input_2 + sep_sequence_id + ... + 0's</code>
      </p>

      <ul>
          <li><em>start_sequence_id</em>The start sequence id, typically <em>1</em></li>
          <li><em>sep_sequence_id</em>The separator sequence id, typically <em>2</em></li>
          <li><em>length</em>:  The maximum length of the token sequence</li>
          <li><em>input_N</em>: Where to retrieve input from. At least one is required.</li>
      </ul>

      <p>
      The inputs are typically retrieved from the query, document attributes or constants.
      For instance, <code>customTokenInputIds(1,2,128, query(my_input), attribute(my_field))</code>
      where input types are:
      </p>
      <ul>
          <li><code>query(my_input): tensor(d0[32])</code></li>
          <li><code>attribute(my_field): tensor(d0[128])</code></li>
      </ul>
  </td>
</tr>


<tr>
    <td>tokenTypeIds(<em>length</em>, <em>input_1</em>, <em>input_2</em>, <em>...</em>)</td>
    <td>n/a</td>
    <td>
        <p id="tokenTypeIds(length, input_1, input_2, ...)">
        Convenience function for generating token sequence input to Transformer models.
        Similar to the <code>tokenInputIds</code>, creates a tensor of type
        <code>d0[1],d1[length]</code> which represents a mask with zeros for the
        first input including CLS and SEP token, ones for the rest of the inputs
        (up to and including the final SEP token), and 0's for the rest of the tensor.
        </p>
    </td>
</tr>

<tr>
    <td>tokenAttentionMask(<em>length</em>, <em>input_1</em>, <em>input_2</em>, <em>...</em>)</td>
    <td>n/a</td>
    <td>
        <p id="tokenAttentionMask(length, input_1, input_2, ...)">
        Convenience function for generating token sequence input to Transformer models.
        Similar to the <code>tokenInputIds</code>, creates a tensor of type
        <code>d0[1],d1[length]</code> which represents a mask with ones for all
        tokens that are set (CLS and SEP and all inputs), and zeros for the rest.
        </p>
    </td>
</tr>

</table>



<h2 id="graphs">Graphs for selected ranking functions</h2>

<h3 id="closeness">closeness</h3>
<img src="/assets/img/relevance/closeness-logscale.png" alt="Closeness logscale plot"/>
<p>
The plot above shows the possible outputs from the closeness distance rank feature
using the default maxDistance of 1000 km. The <em>linear(x)</em> graph shows the default closeness
output while the other graphs are logscale output for various values of the scaleDistance
parameter: 9013.305 (1 km), 45066.525 (5 km - the default value), and 901330.5 (100 km).
These values correspond to the following values of the halfResponse parameter:
276154.903 (30.64 km), 593861.739 (65.89 km), and 2088044.581 (231.66 km).
</p>
<!-- gnuplot input (for image on previous line)

 maxd = 1000
 linear(x) = (x > maxd ? 0 : 1-x/maxd)
 logscale(x, scale) = (x > maxd ? 0 : (( log(maxd+scale) - log(x+scale) ) / (log(maxd+scale) - log(scale))))
 logscale_100km(x) = logscale(x,100)
 logscale_5km(x) = logscale(x,5)
 logscale_1km(x) = logscale(x,1)
 set terminal png picsize 1000 400
 set output "closeness-logscale.png"
 plot [0:1100] [-0.1:1.1] logscale_5km(x), logscale_1km(x), logscale_100km(x), linear(x)

gnuplot script -->


<h3 id="freshness">freshness</h3>
<img src="/assets/img/relevance/freshness-logscale.png" alt="Freshness logscale plot"/>
<p>
The plot above shows the possible outputs from the freshness rank feature
using the default maxAge of 7776000s (90 days). The <em>linear(x)</em> graph shows the default freshness
output while the other graphs are logscale output for various values of the halfResponse
parameter: 172800s (2 days), 604800s (7 days - the default value), 1209600s (14 days).
</p>
<!-- gnuplot input (for image on previous line)

maxa = 90
linear(x) = (x > maxa ? 0 : 1-x/maxa)
logscale(x, scale) = (x > maxa ? 0 : (( log(maxa+scale) - log(x+scale) ) / (log(maxa+scale) - log(scale))))
# scale = -halfResponse*halfResponse/(2*halfResponse - maxa)
logscale_2d(x) = logscale(x,0.047)
logscale_7d(x) = logscale(x,0.64)
logscale_14d(x) = logscale(x,3.16)
set terminal png size 1000,400
set output "freshness-logscale.png"
plot [0:90] [0:1] logscale_2d(x), logscale_7d(x), logscale_14d(x), linear(x)

gnuplot script -->