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

Facet Query Tag

This tag specifies a facet for which to count hits and form groups, and optionally to gather document hits. This tag has the form:
<facet field               = "FieldName"
       {select             = "GroupsToSelect"}
       {sortGroupsBy       = "SortKind"}
       {sortDocsBy         = "ListOfMetaFields"}
       {includeEmptyGroups = "YesOrNo"} />
where
field="FieldName" is a required attribute that identifies which meta-data field in the index for which to count and build groups. (Note: Meta tags to be used for faceted queries should also have an xtf:tokenize="no" attribute set, or sorting will produce unpredictable results.)
select="GroupsToSelect" is an optional attribute specifying a subset of groups to select and return in the query result. For maximum flexibility, this specification is made using a special language that resembles XPath to some extent. It allows selecting groups by name or position in the list, and supports various operations on hierarchical meta-data. See examples below. If this attribute is not specified, it defaults to: *
sortGroupsBy="TotalDocsOrValue" is an optional attribute telling XTF the order in which to sort groups. If set to "totalDocs", groups will be sorted in decreasing order of the total number of documents per group. If set to "value", groups will be sorted in increasing order by the value (i.e. name) of the facet group. If set to "maxDocScore", groups will be sorted in decreasing order by their relevance score (relevance judged in relation to the main query.) If this attribute is not specified, it defaults to "totalDocs."
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 leftmost 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 is 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 should also have an xtf:tokenize="no" attribute set, or sorting will produce unpredictable results.)
includeEmptyGroups="YesOrNo" is an optional attribute that specifies whether to include empty groups in the results. If set to "yes", empty groups will be included. If set to "no" they will be excluded. If this attribute is not specified, it defaults to "no."

The <facet> tag enables counting and grouping for a single meta-data field. First, XTF scans the index and forms a table of all the possible values of that field. Then the query is performed as normal, as each document hit is encountered, XTF looks up that document's value in the table and increments the count for it. If enabled in the selection specification, a list of the document hits for each value is also accumulated.

After the counting is completed, XTF sorts them, removes empty groups if enabled, and then applies the group selection specification (from the select attribute) to decide which groups to send to the Result Formatter stylesheet. For more information on the selection process, see the Group Selection section of the XTF Programmer's Guide. The final selected groups will appear within a Facet Result tag in the results.
Note that only one facet query is allowed per meta-data field. Trying to specify more than one will result in an error message.

Some examples of the select attribute:
*[1-5]                   Politics#all        **[topChoices]
US::Berkeley#all|US::*   History#all|**[selected][page(size=5)]
For more information, refer to the Group Selection section of the XTF Programmer's Guide.