YQL Query Language Reference

The following numeric operators are available: = < > <= >=. In addition to that, the range operator can be used for numeric fields.

where 500 >= price

The range operator range(field, lower bound, upper bound) is supported for numeric and string fields. On numeric fields, it uses the intuitive ordering of numbers, and on string fields, it uses the lexicographical order.

Support for string fields available since Vespa 8.755.13 .

Numbers must be in the signed 32-bit range. Input 64-bit signed numbers using L as suffix.

where range(numeric_field_name, 0, 5000000000L)

When used with a string field, the string bounds have to be enclosed in (single or double) quotes.

where range(string_field_name, "A", "C")

One can also use the strings -Infinity or Infinity as the lower or upper bound, respectively, to express unbounded ranges. Note that these strings must not be enclosed in quotes:

where (range(year, 2000, Infinity))

An all-encompassing numeric range matches every document that has a value set for the field. This is a way to select the documents where a numeric field is present:

where range(size, -Infinity, Infinity)

Documents where the field is unset are not matched. For the complementary query - finding documents missing a value - see count fields with NaN and the FAQ entry on querying for fields with no value.

The weightedset field does not support filtering on weight. Solve this using the map type and sameElement query operator - see example.

The boolean operator is: =

where alive = true

The right-hand side argument of the contains operator is either a string literal, or a function, like phrase.

contains is the basic building block for text matching. The kind of matching to be done depends on the field settings in the schema.

where title contains "madonna"

where title contains ({stem: false}"madonna")

The matched field must be an indexed field or attribute.

Fields inside structs are referenced using dot notation - e.g mystruct.mystructfield.

and accepts other and statements, or statements, userQuery, logically inverted statements - and contains statements as arguments:

where title contains "madonna" and title contains "saint"

or accepts other or statements, and statements, userQuery - and contains statements as arguments:

where title contains "madonna" or title contains "saint"

Use the ! operator to match document that does not satisfy some condition:

where title contains "madonna" and !(title contains "saint")

Phrases are expressed as a function:

where text contains phrase("st", "louis", "blues")

near() matches if all argument terms occur within the specified distance, in any order. Negative terms (prefixed with !) exclude matches where those terms appear within the exclusion distance.

where field contains near("a", "b", "c")
where field contains ({distance: 5}near("web", "search"))
where field contains near("sql", "database", !"nosql")

Negative terms must come after all positive terms. For multi-value fields, setting element-gap for the field in the rank profile enables distance calculation between adjacent elements.

Features below near() and onear() are filtered based on the spans for the operator match before they are exposed to the ranking features. Given the query

text contains ({distance:1}near("a","b"))

and two documents.

The text field in the first document is "a a a a a a b b b b b b". The spans for the near match are [[5,6]]. Only the last occurrence of "a" and the first occurrence of "b" are kept.

The text field in the second document is "a b c a b c a b c a b c". The spans for the near match are [[0,1],[3,4],[6,7],[9,10]]. All occurrences of "a" and "b" are kept.

onear() (ordered near) is like near(), but requires terms to appear in the same order as specified in the query. With distance set to (number of terms - 1), onear() is equivalent to phrase().

where field contains onear("web", "search", "engine")
where field contains ({distance: 5}onear("neural", "network"))
where field contains onear("java", "tutorial", !"script")

Negative terms must come after all positive terms. For multi-value fields, setting element-gap for the field in the rank profile enables distance calculation between adjacent elements.

The sameElement() operator lets you denote conditions that must match within the same element in multivalue fields containing structs or strings.

By default, sameElement uses AND to combine the conditions: All the conditions must match in the same element to produce a match.

Usage examples for the sameElement() operator:

• array-of-struct fields

For example, given the struct and array of this struct

struct person {
    field first_name    type string {}
    field last_name     type string {}
    field year_of_birth type int {}
}

field persons type array<person> {
    indexing: summary
    struct-field first_name    { indexing: attribute }
    struct-field last_name     { indexing: attribute }
    struct-field year_of_birth { indexing: attribute }
}

we can use the query

where persons contains sameElement(first_name contains 'Joe', last_name contains 'Smith', year_of_birth < 1940)

to return all documents containing a Joe Smith born before 1940 in the persons array.

• Search map fields

Searching a map is done by treating it as an array of a struct with the field members key and value. For example, given the map

field identities type map<string, person> {
    indexing: summary
    struct-field key                 { indexing: attribute }
    struct-field value.first_name    { indexing: attribute }
    struct-field value.last_name     { indexing: attribute }
    struct-field value.year_of_birth { indexing: attribute }
}

we can use the query

where identities contains sameElement(key contains 'father', value.first_name contains 'Joe', value.last_name contains 'Smith', value.year_of_birth < 1940)

to return all documents that have a Joe Smith born before 1940 keyed as a 'father'.

• array-of-string fields

sameElement() may also be used to search array of string fields. Supported query operators inside sameElement() are and, equiv, near, onear, or, rank and phrase. and can be used with !.

For example, given the field

field chunks type array<string> {
    indexing: index | summary
}

we can use the following queries:

where chunks contains sameElement("one" and "two")
where chunks contains sameElement("one" and equiv("two","three"))
where chunks contains sameElement("one" and ({distance: 5}near("two","three",!"four")))
where chunks contains sameElement("one" and phrase("two","three"))
where chunks contains sameElement("one" and !"two")
where chunks contains sameElement("one" or "two")
where chunks contains sameElement(rank("one" and "two", "three"))

Features inside sameElement() for indexed fields are filtered based on the matching elements, e.g., elementwise(bm25(descriptions),x,double) will only contain tensor cells based on the matching elements.

• array fields at specific indices

Use the elementFilter annotation to restrict matching to specific element indices. For example, given a field my_numbers type array<int>:

where my_numbers contains ({elementFilter:[2]}sameElement("42"))

This only matches the element at index 2 in the array field. Multiple indices can be given: {elementFilter:[0, 2, 5]}.

A shorthand form is also available:

where my_numbers[2] = 42

The shorthand form only supports a single index. Use the elementFilter annotation to match multiple indices.

Available since Vespa 8.773.18 .

The mapMatch() operator represents a restricted variant of the sameElement() operator for searching map-like fields. Map-like fields are fields of type map and fast-search map fields, where the latter can only be searched via the mapMatch() operator.

In contrast to the sameElement() operator, the mapMatch() always takes two arguments and is limited in which operators can be used inside of it: The first argument has to use key with

• a contains operator if the key type is string or
• a numeric equality operator if the key type is numeric.

• a contains operator if the value type is string or
• a numeric operator or range operator if the value type is numeric.

Usage examples for the mapMatch() operator:

• map fields

Searching a map is done analogously to the sameElement() operator. For example, given the map

field my_map type map<string, string> {
    indexing: summary
    struct-field key   { indexing: attribute }
    struct-field value { indexing: attribute }
}

we can use the query

where my_map contains mapMatch(key contains 'color', value contains 'black')

or its shorthand form

where my_map{'color'} contains 'black'

to return all documents that have 'black' as their 'color'.

• fast-search map fields

The syntax is the same as for fields of type map; just use the full name of the fast-search map field instead. For example, given the map

field my_map type map<string, int> {
    indexing: summary
    fast-search-map-field my_lookup
}

we can search its fast-search map field via the query

where my_map.my_lookup contains mapMatch(key contains 'price', value = 50)

or its shorthand form

where my_map.my_lookup{'price'} = 50

to return all documents that have a 'price' of exactly 50. We can use the query

where my_map.my_lookup contains mapMatch(key contains 'price', range(value, 0, 99))

or its shorthand form

where range(my_map.my_lookup{'price'}, 0, 99)

to return all documents that have a 'price' between 0 and 99.

The alternatives operator is used to provide multiple variants of a token at the same position in the query. The token alternatives are given with a normalized exactness score denoting the extent to which they mean "the same thing" as the first alternative.

where fieldName contains alternatives({"sneakers":1.0, "shoes":0.7})

For cases where two terms in the same field should produce exactly the same behavior when matched, the equiv() operator can be used. This behaves like a special case of or.

where fieldName contains equiv("A","B")

The matching logic of equiv is the same as OR, and an OR does not have the limitations that EQUIV does (below). The difference is in how matches are visible to ranking functions. All words that are children of an OR count for ranking, while with EQUIV, they look like a single word to ranking:

• Counts as only +1 for queryTermCount
• Counts as 1 word for completeness measures
• Proximity will not discriminate different words inside the EQUIV
• Connectivity can be set between the entire EQUIV and the word before and after
• Items inside the EQUIV are not directly visible to ranking features, so weight and connectivity on those will have no effect

Limitations on how equiv can be used in a query:

• equiv may not appear inside a phrase
• It may only contain TermItem and PhraseItem instances. Operators like and cannot be placed inside equiv
• PhraseItems inside equiv will rank like as if they have size 1

Learn how to use equiv.

where myUrlField contains uri("vespa.ai/foo")

Various subfields are supported to search components of the URL, see the field type definition.

Levenshtein edit distance search within a string or array<string> attribute.

where myStringAttribute contains ({prefixLength:1, maxEditDistance:2}fuzzy("parantesis"))

Annotations below are configuring fuzzy:

Find an example in text matching.

Regular expression match is supported using posix extended syntax, with the limitation that it is case-insensitive.

Example matching both madonna, madona and with any number of ns:

where attribute_field matches "mado[n]+a"

Find more examples in the text matching guide.

text() accepts any text and tokenizes it into a set of tokens to be searched in a given field or fieldSet. By default, the tokens are searched with a weakAnd operator. You can override the default behavior via annotations: text() supports the same annotations as userInput().

Example:

      where text_field contains text("some text")

With annotations:

      where text_field contains ({language:'en'}text("some text"))

The text argument can be given as a reference using "@parameterName":

      yql=select * from sources * where text_field contains text(@text)&text=some text

userInput() parses text from end users or models that may contain query syntax for choosing the fields to search, specifying phrases and negative terms etc. Since the query in userInput can specify fields, there is no "contains field" prefix before the userInput operator.

yql=select * from sources * where userInput('some text')

The argument can be given as a reference using "@parameterName":

yql=select * from sources * where userInput(@text)&text=some text

Both of these will result in the query

select * from sources * where weakAnd(default contains "some", default contains "text")

The default behavior may be overridden by annotations:

yql=select * from sources * where ({grammar.syntax:'none',grammar.tokenization:'linguistics',grammar.composite:'near',distance:3}userInput('some text'))

In addition, other annotations, like stem or ranked, will take effect as normal.

More examples can be found in the query API guide.

userQuery() reads from model.queryString and parses the query using simple query language. If set, model.filter is combined with model.queryString before the parsing.

The user query is first parsed, then the resulting tree is inserted into the corresponding place in the YQL query tree. Example:

$ vespa query 'select * from sources * where vendor contains "brick and mortar" AND price < 50 AND userQuery()' \
  query="abc def -ghi" \
  type=all

This evaluates to a query where:

• the numeric field price must be less than 50
• vendor must match brick and mortar
• the default index must contain the two terms abc and def, and not contain ghi.

Use model.defaultIndex to specify a field or fieldset if not using default - see example.

The first, and only the first, argument of the rank() function determines whether a document is a match, but all arguments are used for calculating rank features. The rank operator is useful for boosting documents based on the presence of certain terms without impacting matching or retrieval logic.

where rank(a contains "A", b contains "B", c contains "C")

It's also useful in hybrid search use cases. See blog post for usage examples. For example, retrieve using the nearestNeighbor query operator as the first argument and have matching features calculated for the other arguments.

where rank(nearestNeighbor(field, queryVector), a contains "A", b contains "B", c contains "C")

Using labeled(subQuery, "mylabel", 4.25) wraps an arbitrary sub-query with a label "mylabel" and score. If the sub-query matches a document, the score (4.25 in this example) can be picked up by ranking expressions using the itemRawScore rank feature. Available since Vespa 8.743.16 . Typically used together with the rank operator, like this:

where rank(title contains "running shoes",
           labeled(memberDiscountPercent >= 20 AND inStock > 0, "memberDiscount", 2.0),
           labeled(premiumBrand = true OR todaysFeaturedBrand = true, "premiumOrFeaturedBrand", 1.0))

And a ranking profile could use

  expression: bm25(title) + itemRawScore(memberDiscount) + 31.5 * itemRawScore(premiumOrFeaturedBrand)

This is similar to Lucene's ConstantScoreQuery, often used in Elasticsearch/OpenSearch through function_score or in Solr with ^= query syntax.

The in operator is used to match a set of values in an integer or string field. A document is considered a match when at least one of the values matches the content of the field. This is an optimized shorthand for multiple OR conditions, and is similar to the IN operator in SQL. Available since Vespa 8.293.15 . Example:

where integer_field in (10, 20, 30)
where string_field in ('germany', 'france', 'norway')

field string_field type string {
    indexing: summary | index # or attribute
    match: word
    rank:filter
    attribute: fast-search # if attribute
  }

Using the in operator against string fields with match:text will cause recall issues because the field contents will be tokenized during indexing while the in operator does not tokenize the values.

The argument before in is the name of the field or fieldset to search. The argument after in is a comma-separated list of values, enclosed in parentheses. String values must be single or double-quoted if passed inline in YQL

For multi-value fields (like arrays), the in operator works by checking if any element in the array matches any of the values in the set. This is similar to SQL's IN operator but more streamlined for array comparisons. Example:

where integer_array_field in (10, 20, 30)

If integer_array_field = [5, 10, 15], it will match because 10 is in the array. Similarly, if integer_array_field = [20, 25, 30], it will match because both 20 and 30 are in the array.

For faster query parsing use parameter substitution to submit the values as an additional request parameter. Quoting of string values are optional. Example:

where integer_field in (@integer_values)&integer_values=10,20,30
where string_field in (@string_values)&string_values=germany,france,norway

The in operator acts as a single term in the query tree, and does not provide any match information for text ranking features.

For a discussion of usage and examples refer to:

• multivalue query operators
• multi-lookup set filtering
• in operator system test

dotProduct calculates the dot product between the weighted set in the query and a weighted set field in the document as its rank score contribution:

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

The result is stored as a raw score.

A normal use case is a collection of weighted tokens produced by an algorithm, to match against a corpus containing weighted tokens produced by another algorithm in order to implement personalized content exploration. See example usage of dotProduct in practical performance guide .

Refer to multivalue query operators for a discussion of usage and examples.

Keys must be single or double-quoted if passed inline in YQL - alternatively, use parameter substitution to submit the weighted set with a simple format for faster query parsing - example: where dotProduct(description, @myterms).

When using weightedSet to search a field, all tokens present in the searched field will be matched against the weighted set in the query. This means that using a weighted set to search a single-value attribute field will have similar semantics to using a normal term to search a weighted set field. The low-level matching information resulting from matching a document with a weighted set in the query will contain the weights of all the matched tokens in descending order. Each matched weight will be represented as a standard occurrence on position 0 in element 0.

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

weightedSet has similar semantics to equiv, as it acts as a single term in the query. However, the restriction dictating that it contains a collection of weighted tokens directly enables specific back-end optimizations that improves performance for large sets of tokens compared to using the generic equiv or or operators.

Keys must be single or double-quoted if passed inline in YQL - alternatively, use parameter substitution to submit the weighted set with a simple format for faster query parsing - example: where weightedSet(description, @myterms).

wand can be used to search for documents where weighted tokens in a field matches a subset of weighted tokens in the query. At the same time, it internally calculates the dot product between token weights in the query and the field. wand is guaranteed to return the top-k hits according to its internal dot product rank score. It is an operator that scales adaptively from or to and.

Note that total hit count becomes inaccurate when using wand.

wand optimizes the performance of using multiple threads per search in the backend, and is also called Parallel Wand.

wand also allows numeric arguments, then the search argument is an array of arrays of length two. In each pair, the first number is the search term, the second its weight:

where wand(description, [[11,1], [37,2]])

Keys must be single or double-quoted if passed inline in YQL - alternatively, use parameter substitution to submit the weighted set with a simple format for faster query parsing - example: where wand(description, @myterms).

where ({scoreThreshold: 0.13, totalTargetHits: 7}wand(description, {"a":1, "b":2}))

Refer to using wand for introduction to the WAND algorithm and example usage of wand in practical performance guide .

weakAnd is sometimes called Vespa Wand. Unlike wand, it accepts arbitrary word matches (across arbitrary fields) as arguments. Only a limited number of documents are returned for ranking (default is 100), but it does not guarantee to return the best k hits. This function can be seen as an optimized or:

where weakAnd(a contains "A", b contains "B")

where ({totaltargetHits: 7}weakAnd(a contains "A", b contains "B"))

Unlike wand, weakAnd can be used to search across several fields of various types, but it does NOT guarantee to return the top-k best number of hits. It can however be combined with any ranking expression. Keep in mind that this expression should correlate with its simple internal ranking score that uses query term weight and inverse document frequency for matching terms.

Refer to using wand for a usage and examples.

geoLocation matches a position inside a geographical circle, specified as latitude, longitude, and a maximum distance (radius). See also geoBoundingBox. Example:

where geoLocation(myfieldname, 63.5, 10.5, "200 km")

In this example we search for documents near 63.5° north, 10.5° east, and within a 200 km radius. So a document with a "myfieldname" position in Trondheim, Norway at N63°25'47;E10°23'36 would match. The first parameter is the name of the attribute field. The second parameter is the latitude (positive for north, negative for south). The third parameter is the longitude (positive for east, negative for west). The fourth parameter must be a string specifying the radius and its units, where the supported units/suffixes include "km", "m" (abbr. for meters), "miles", "mi" (abbr. for miles), "deg" (abbr. for degrees) and "d" (contextual abbr. for degrees). The "deg" / "d" unit / suffix gives radius the same units as latitude. Any negative number for radius (e.g. "-1 m") is interpreted as an "infinite" radius, letting any geographical position at all match the geoLocation operator.

The position attribute in the schema could look like:

field myfieldname type position {
    indexing: attribute | summary
}

Arrays of positions are also possible:

field myfieldname type array<position> {
    indexing: attribute
}

Properties:

geoBoundingBox requires a position to be inside a geographical rectangle; specified as 4 numbers (in degrees). The 4 numbers must be in a specific order: south-western corner (minimum latitude, minimum longitude) followed by north-eastern corner (maximum latitude, maximum longitude). Examples:

where geoBoundingBox(myfieldname, 63.25, 10.01, 63.45, 10.61)
where geoBoundingBox(myfieldname, -23.12, -43.85, -22.59, -42.89)

In the first example we search for documents inside a rectangular map view around Trondheim, Norway. So a document with a "myfieldname" position at 63°25'50"N 10°23'42"E would match. The second example surrounds Rio de Janeiro, Brazil.

• The first parameter is the name of the attribute field.
• The 2nd parameter is the minimum (southern) latitude (positive for north, negative for south).
• The 3rd parameter is the minimum (western) longitude (positive for east, negative for west).
• The 4th parameter is the maximum (northern) latitude (positive for north, negative for south).
• The 5th parameter is the maximum (eastern) longitude (positive for east, negative for west).

See the geoLocation operator for more details about positions. Note that there is no ranking contribution from this operator; if you want to get the distance to the center of the box, you need an additional geoLocation item with that point.

Properties:

nearestNeighbor matches the top-k nearest neighbors in a multidimensional vector space. Points in the vector space are specified as tensors with one indexed dimension, where the size of that dimension is equal to the dimensionality of the vector space.

The document vectors are stored in a tensor field attribute, and the query vector is sent with the query request. The following tensor field types are supported:

• Single vector per document: Tensor type with one indexed dimension. Example: tensor<float>(x[3])
• Multiple vectors per document: Tensor type with one or more mapped dimensions and one indexed dimension. Examples: tensor<float>(m{},x[3]), tensor<float>(m{},n{},x[3])

Euclidean distance is used as the default distance metric and the exact nearest neighbors are returned. When storing multiple vectors per document, the vector that is closest to the query vector is used when calculating the distance between the document and the query. If an HNSW index is specified on the tensor field, the approximate nearest neighbors are returned. Example:

where ({totaltargetHits: 10}nearestNeighbor(doc_vector, query_vector))&input.query(query_vector)=[3,5,7]&ranking=semantic

In this example we search for the top 10 nearest neighbors in a 3-dimensional vector space. totalTargetHits specifies the top-k nearest neighbors to expose to a user defined semantic rank profile. The totalTargetHits annotation is required. The first parameter of nearestNeighbor is the name of the tensor field attribute containing the document vectors (doc_vector).

The second parameter is the name of the tensor sent with the query request (query_vector). Specifying query_vector as the name means the query request must set this tensor as input.query(query_vector) - see the reference. The tensor type of the input query vector must be defined in the rank profile:

rank-profile semantic {
    inputs {
        query(query_vector) tensor<float>(x[3])
    }
    first-phase: closeness(field, doc_vector)
}

Also see defining query feature types. Failure to define the query input tensor in the schema will fail the request:

  Expected 'query(query_vector)' to be a tensor, but it is the string '[3,5,7]'

The document tensor field attribute is defined as follows:

field doc_vector type tensor<float>(x[3]) {
    indexing: attribute | summary
}

The example above does not define HNSW index and the search for neighbors will be exact.

See Nearest Neighbor Search, Approximate Nearest Neighbor Search using HNSW Index and Nearest Neighbor Search Guide for more detailed examples.

Properties:

nonEmpty takes as its only argument an arbitrary search expression. It will then perform a set of checks on that expression. If all the checks pass, the result is the same expression, otherwise the query will fail. The checks are as follows:

1. No empty search term
2. No empty operators, like phrases without terms
3. No null markers (NullItem) from e.g. failed query parsing

yql=select * from sources * where bar contains "a" and nonEmpty(bar contains "bar" and foo contains @foo)&foo=

Note how "foo" is empty in this case, which will force the query to fail. If "foo" contained a searchable term, the query would not have failed.

predicate() specifies a predicate query - see predicate fields. It takes three arguments: the predicate field to search, a map of attributes, and a map of range attributes:

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

Due to a quirk in YQL-parsing, one cannot specify an empty map, use the number 0 instead.

where predicate(predicate_field,0,{"age":20L})

Matches all documents of any type. Care must be taken when using this since processing all documents as matches is expensive. At minimum, consider restricting to only one schema where you know the corpus isn't too big, see the model.restrict URL parameter.

Does not match any document at all. Not useful in itself, but could potentially be used as a placeholder in the query tree.

Remove accents from this term if it is the setting for this field. Refer to linguistics.

Whether to allow empty input for query parsing and query terms in text/userInput. If true, a NullItem instance is inserted in the proper place in the query tree. If false, the query will fail if the user provided input can not be parsed or is empty.

Force phrase or AND operator if re-segmenting (e.g. in stemming) this term results in multiple terms. Default is choosing from language settings.

Map of string: string. Custom annotations. No special semantics inside the YQL layer. Example:

annotations : {cox: "another"}

Used in nearestNeighbor. The optional approximate annotation may be set to false to disallow usage of an approximate HNSW index. This is especially useful to compare exact and approximate results in order to perform tuning of other parameters. This annotation is default true when an HNSW index is specified, otherwise it is always false.

Ascending hit order. Used by hitLimit.

A numeric interval is by default a closed interval. If the lower bound is exclusive, set to leftOpen. If the upper bound is exclusive, set to rightOpen. If both bounds are exclusive, set the annotation to open. Example:

where ({bounds:"rightOpen"}range(year, 2000, 2018))

Map of id: int, weight: double of explicit connectivity between this item and the item with the given id - see text matching and ranking. Example:

connectivity: {id: 4, weight: 0.8}

Descending hit order. Used by hitLimit.

Used by userInput. Same as model.defaultIndex in the query API. If grammar is set to raw or segment, this will be the field searched.

The distance annotation sets the maximum position difference to count as a match, see near / onear. All matching terms must fit within positions [P, P+distance] where P is the first term's position. Default is 2.

where text contains ({distance: 5}near("a", "b"))

Used with sameElement. Restricts matching in an array field to specific indices. A non-empty list makes sameElement match if and only if there is a match at one or more of the specified indices.

where my_numbers contains ({elementFilter:[0, 2, 5]}sameElement("42"))

Used in nearestNeighbor. The distanceThreshold annotation may be used to filter away hits with a higher distance than the given threshold from the results. Note that one will never get more hits with distanceThreshold than you would get without it - to get more hits, increase totalTargetHits, too. The units for the threshold depends on the distance metric used.

where myUrlField.hostname contains uri("vespa.ai")

will match vespa.ai and docs.vespa.ai, while

where myUrlField.hostname contains ({startAnchor: true}uri("vespa.ai"))

will only match vespa.ai.

Regard this term as a "filter" term and not a term from the end user. Terms that are annotated with "filter:true" are not bolded. See also model.filter. Bolding of terms is controlled by schema:bolding.

Default sort function for strings is uca. Field sort specification can be configured in the schema, values in the query overrides the schema settings.

Numeric fields are numerically sorted.

How to parse userInput. raw will treat the user input as a string to be matched without any processing, segment will do a first pass through the linguistic libraries, while the rest of the values will treat the string as a query to be parsed.

The individual model.type settings can also be set, using grammar.composite, grammar.tokenization, grammar.syntax, and grammar.profile—refer to the model.type documentation.

See also userInput examples.

Numeric operations support hitLimit. This is used for capped range search. An alternative to using negative and positive values for hitLimit is always using a positive number of hits (as a negative number of hits does not make much sense) and combine this with either of the ascending and descending annotations (but not both). Example: {hitLimit: 38, descending: true} would be equivalent to setting it to -38, i.e. only populate with 38 hits and start from upper boundary, i.e. descending order.

Note that hitLimit will limit the number of documents that are considered. This is a powerful optimisation that must be used with care, particularly in combination with other filters. The set of documents to be considered will be limited upfront by only selecting the N best according to the range query and the hitLimit annotation, for further query evaluation.

hitLimit is not exact, but "at least". In addition, it will only kick in if the attribute has fast-search. It will look up the upper or lower bound in the range in the dictionary and scan in ascending or descending order and select entries until it has satisfied hitLimit. You will get all documents for all the dictionary entries selected.

See the practical-search-performance-guide for an example.

Used in nearestNeighbor. When using an HNSW index, the optional hnsw.exploreAdditionalHits annotation can be used to tune how many extra nodes in the graph (in addition to totalTargetHits) should be explored before selecting the best hits. Using a greater number here gives better quality, but worse performance.

Unique ID used for e.g. connectivity.

Implicit term transformations (field defaults). If implicitTransforms is true, the settings for the field in the schema will be honored in term transforms, e.g. if the field has stemming, this term will be stemmed. If implicitTransforms is false, the search backend will receive the term exactly as written in the initial YQL expression. This is in other words a top level switch to turn off all other stemming, accent removal, Unicode normalizations and so on.

Attaches a symbolic name to this query item so that it can be referred to from ranking, see query item labeling.

The label is carried by single terms, or operators like and, or or nearestNeighbor. Sub-clauses inherit the label of their parent, but can override it.

The rank features taking a label are itemRawScore(label), closeness(label,name), distance(label,name), closest(field,label) and bm25(field: field, label: label). In addition, bm25_for_labels(field) returns one bm25 score per label.

Language setting for the linguistics handling of text and userInput, also see model.language in the query API reference.

Used by the UCA sort function. An identifier following unicode locale identifiers, e.g. en_US.

Used in fuzzy. An inclusive upper bound of edit distance between query and string attribute.

NFKC normalization.

Normalize casing of this term if it is the setting for this field.

Map of original: string, offset: int, length: int. The (sub-)string which produced this term. Default unset. Example:

origin: {original: "abc", offset: 1, length: 2}

Do prefix matching for this term, e.g. search for "word*".

Used in fuzzy. Number of characters that are considered frozen, so the fuzzy match will be performed with the suffix left.

Include this term for ranking calculation. Setting ranked to false can speed up query evaluation. Read more about schema reference. Example

A threshold in wand for the minimum score of hits to include as matches.

Significance value for text ranking features - see text matching and ranking.

Stem this term if it is the setting for this field.

• PRIMARY
• SECONDARY
• TERTIARY
• QUATERNARY
• IDENTICAL

Used by the UCA sort function. Default is PRIMARY, which only sorts on primary differentiating characteristics; this means that letters in uppercase/lowercase or with differences in accents only are considered equal.

Do suffix matching for this term, e.g. search for "*word".

Used with wand and weakAnd, where the default is 100, and with nearestNeighbor, where it has no default. This sets the wanted number of hits exposed to the first-phase ranking function in total over the content nodes evaluating the query (a group). If additional second phase ranking is used, do not set totalTargetHits less than the configured rank-profile's total-rerank-count.

See examples in nearest neighbor search.

Used with nearestNeighbor. Specifies the minimum target hits to produce in this nearest neighbor operator. The default value is 100. Exploring too little in a graph leads to bad quality, and this parameter protects against that when totalTargetHits leads to some node with little content otherwise getting a low targetHits.

Each content node resolves its per-node target hits as max(minTargetHits, ceil(totalTargetHits × share)), where share is the node's share of the active documents in the group serving the query - not across the whole cluster, since a query is dispatched to a single group. A node that has just joined the cluster, or is still receiving documents after a topology change, temporarily holds little content and would get too few hits from totalTargetHits alone without this floor.

Sets target hits per node. Prefer using totalTargetHits over this.

Use term position data for text ranking features such as nativeRank. This is term position, not to be confused with geo searches. Setting "usePositionData:false" can improve query performance.

Term weight, used in some text ranking features - see text matching and ranking.

where title contains ({weight:200}"heads")