[ You are here:
XTF ->
Tag Reference ->
crossQuery ->
Query Parser Output Tags -> Near Search Tag ]
Near Search Tag
This tag defines a search where all of the sub-terms or clauses must be in a document,
and within a specified distance of each other for a match to be made. This tag has the form:
<near slop = "MaxMatchDistance"
{field = "FieldName"}
{maxSnippets = "SnippetsToOutput"}
{boost = "BoostValue"}>
Term | Clause
Term | Clause
…
{OptionalSectionTypeQuery}
</near>
where
slop="MaxMatchDistance" |
is a measure of the "nearness" of the terms or clauses specified. See the discussion of slop values below. |
field="FieldName" |
is an optional attribute that identifies which field in the index to search. Often this attribute is set to text to indicate that the main text of the document should be searched. It can also be set to the name of a meta field such as author or subject. It should be mentioned that the field name specified by a <near> tag must match the field name set by any tags that contain it. Otherwise, an error will be generated. If no parent tags specify a field name, any field name can be used by the <near> tag. Similarly, any tags within a <near> tag must either specify the same field name as the near clause, or specify no field name at all. Otherwise, an error will be generated. (Note: Allowing nested copies of the field attribute doesn't serve a purpose other than to make it easier to write docReqParser.xsl stylesheets in a uniform way. Effectively, the outermost field value is always used.) |
maxSnippets="SnippetsToOutput" |
is an optional attribute that identifies the number of snippets to pass on to the Result Formatter stylesheet for display. A snippet is defined as the matching text found in a document for a particular query, along with some additional text around it for context. The amount of context displayed for each match is defined by the maxContext attribute. If not specified this attribute defaults to 3, meaning snippets for the top three matches for a document are returned. Also, this attribute can be set to -1, meaning all the snippets for a document are returned. As with the field attribute, if the maxSnippets attribute appears in any containing tags, the value set for it in the <near> tag must match the value set in the containing tags. Otherwise, an error will be generated. Similarly, any occurrences of the maxSnippets attribute in tags within the <near> tag must have the same value as their containing tags. (Note: Allowing nested copies of the maxSnippets attribute doesn't serve a purpose other than to make it easier to write docReqParser.xsl stylesheets in a uniform way. Effectively, the outermost maxSnippets value is always used.) |
boost="BoostValue" |
is an optional attribute that specifies a relevance boost multiplier for this clause in the query. Boost values higher than 1.0 increase the relevance of a clause, while boost values between 0.0 and 1.0 decrease the relevance of a clause. Boost values less than zero will generate an error. Note that boost values multiply. That is, if tags within an <near> tag have boost attributes, their individual boost values will be multiplied by the boost set for the containing <near> tag. |
A slop value for a potential match is accumulated as follows:
- A potential match is found when all the items specified in the near tag are found in a document. Initially, the accumulated slop for this potential match is set to zero.
- Next the accumulated slop is incremented by one for each word in the potential match that doesn't appear in near tag.
- Finally, the accumulated slop is incremented by one each time a word specified in the near tag appears out of order in the document. If the final accumulated slop exceeds the value set by the slop attribute of the near tag, the potential match is ignored. Note that setting the slop value for the near tag to zero effectively produces an exact phrase search, and is in fact how the phrase tag is implemented internally.
Within the near tag, Term is a
term tag, and Clause is a
phrase,
exact,
and,
or,
orNear,
near,
range,
resultData, or
not tag.
It should also be noted that, when applied to the "text" field, if the value specified for the slop attribute exceeds the maximum proximity for the index being used, the maximum proximity value will be used instead. There is no limit on the slop attribute when applied to meta-data fields.
If the field is "text", a
Section Type sub-query may optionally appear, restricting this query to particular sections of a document based on section types added by the
Pre-Filter stylesheet at index time.