[ You are here: XTF -> Tag Reference -> crossQuery -> Query Parser Output Tags -> Query Tag ]

Query Tag

This tag is outermost tag in an XML query sent to the crossQuery servlet's search engine. It has the form:
<query indexPath        = "IndexDBLocation"
       style            = "ResultFormatterLocation"
       {sortDocsBy      = "ListOfMetaFields"}
       {startDoc        = "FirstDocToReturn"}
       {maxDocs         = "MaxDocsToReturn"}
       {termLimit       = "MaxTermsToAllow"}
       {workLimit       = "MaxWorkToAllow"}
       {maxContext      = "MaxContextChars"}
       {maxSnippets     = "SnippetsToOutput"}
       {termMode        = "TermMarkMode"}
       {field           = "FieldToSearch"}
       {normalizeScores = "TrueOrFalse"}
       {explainScores   = "TrueOrFalse"}>
 
    QueryElement
 
</query>
where
indexPath="IndexDBLocation" is the path to the Index Database to use when performing the search. If this path is not specified as an absolute path, it is assumed to be relative to the XTF base installation directory (i.e., XTF_HOME.)
style="ResultFormatterLocation" is the path to the Result Formatter stylesheet to use to display the results generated by the current query. If this path is not specified as an absolute path, it is assumed to be relative to the XTF base installation directory (i.e., XTF_HOME.)
sortDocsBy="ListOfMetaFields" is an optional attribute specifying a list of meta fields by which to sort the results. The list should consist of a quoted string containing one or more meta-field names, separated by commas. If multiple meta-fields are specified, the results are sorted first by the left-most meta-field, then sub-sorted by subsequent fields to produce the final output. Optionally, each meta-field name can be preceded by a plus sign (+) or a minus sign (-) to indicate whether the results for that field should be sorted in ascending or descending order. If no plus or minus sign is specified for a meta-field, then the results are sorted in ascending order by default. If this attribute not specified, documents are by default sorted in order of decreasing score (so the most "relevant" documents are first.) (Note: Meta tags to be used for sorting queries should also have an xtf:tokenize="no" attribute set, or sorting will produce unpredictable results.) (Compatibility note: This attribute was previously called "sortMetaFields", and this old name is still accepted to retain backward compatibility.)
startDoc="FirstDocToReturn" is an optional attribute specifying the ordinal number of the first matching document to pass on to the Result Formatter. If not specified, this attribute defaults to 1, meaning the first document that contains matches for the specified query.
maxDocs="MaxDocsToReturn" is an optional attribute specifying the number of matching documents to pass on to the Result Formatter. If not specified, this attribute defaults to 10, meaning that up to 10 documents with matches will be returned for the specified query. The special value "all" may be used to indicate that all matching documents should be returned.
termLimit="MaxTermsToAllow" is an optional attribute that limits the number of terms permitted in a query. If not specified, this attribute defaults to -1, meaning no limit is enforced. This attribute is used primarily to prevent wildcard expansions like <term>a*</term> from overloading the crossQuery servlet. If the query does in fact exceed the limit specified by this attribute, a TermLimit error is sent to the Error Generator stylesheet for the offending query.
workLimit="MaxWorkToAllow" is an optional attribute that limits the amount of "work" that may be performed in a query. If not specified, this attribute defaults to -1, meaning no limit is enforced. This attribute is used primarily to prevent queries from overloading the crossQuery servlet, which would adversely impact the responsiveness of the XTF system. If a query exceeds the work limit set by this attribute, a ExcessiveWork error is sent to the Error Generator stylesheet for the offending query. For the crossQuery servlet, one unit of "work" is equivalent to finding a single matching term in a single document. Experimentally, a value of 500,000 for this attribute seems to work well.
maxContext="MaxContextChars" identifies the size of a snippet to pass in the Result Formatter snippet tag. If not specified, this attribute defaults to 80 characters. Note that the context length is the total number of characters for the snippet, which includes both the matched text and the context text surrounding it.
maxSnippets="SnippetsToOutput" 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. Note that -1 is a special value. If maxSnippets is set to -1, it requests that all snippets for a document be returned. If the maxSnippets attribute is set by the <query> tag, any occurrences of the maxSnippets attribute set by the inner tags must match the value set by the <query> tag. Otherwise, an error will be generated. (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.)
termMode="TermMarkMode" is an optional parameter that specifies how terms should be marked in the search results. Valid values for this option are: "none": Do not mark matching terms anywhere in the search results. "hits": Mark matching terms in the search results only if they appear inside <hit> tags. "context": Mark matching terms in the search results only if they appear inside <snippet> or <hit> tags. "all": Mark matching terms in search results anywhere they occur. If not specified, the default value used is "hits". Note that when term marking is enabled, matching terms in the search results are placed inside <term> ... </term> tag sets.
field="FieldToSearch" is an optional parameter that identifies which field in the index to search. This can be set to text to indicate that the main text of the document should be searched, or it can name a meta-data field such as creator or subject. If child elements specify their own field attributes, their field name must agree with the parent element. (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 name is always used.)
normalizeScores="TrueOrFalse" is an optional parameter that can disable score normalization, the process that converts all document scores to be relative to the highest ranking document (which receives a score of 100). If set to no or false, the scores will be raw floating point numbers. The default, true or yes, will normalize scores to the range of 0..100, and round them to whole numbers. In the default XTF stylesheets, one can simply add ";normalizeScores=1" to the query URL, and the default Query Parser will set this attribute for you.
explainScores="TrueOrFalse" is an optional parameter that causes XTF to output a structured, detailed explanation of how the score for each document was calculated. This means that each Document Hit Tag in the query result will contain an Score Explanation Tag, which in turn contains other Score Explanation Tags describing how the components of that score. In the default XTF stylesheets, one can simply add ";explainScores=1" to the query URL, and the default Query Parser will set this attribute for you. This is an advanced feature, as XTF's scoring is fairly complex and can be confusing to those just starting out. For an overview of how XTF scores document hits, see the Scoring section of the document XTF Under the Hood. Note that if you enable this attribute, you should generally disable normalizeScores above, as the score explanations describe the non-normalized score for each document.

The primary purpose of the startDoc and maxDocs attributes is to allow search results to be split up into multiple pages by the Result Formatter. For example, to display the second page of 50 matching documents, the following query tag could be generated by a link on the current result page:
 <querystartDoc="51" maxDocs="50"></query>
The QueryElement specified within this tag identifies the query to be performed. This can be a term query tag, or a phrase, exact, and, or, orNear, near, range, resultData, spellcheck, or not tag.

Note that the Query Parser stylesheet can issue a single top-level error tag instead of a query tag if it encounters any errors.