xsl:key

The xsl:key element is used at the top level of the stylesheet to declare an attribute, or other value, that may be used as a key to identify nodes using the key() function within an expression. Each xsl:key definition declares a named key, which must match the name of the key used in the key() function.

The set of nodes to which the key applies is defined by a pattern in the match attribute: for example, if match="ACT|SCENE" then every ACT element and every SCENE element is indexed by this key.

The value of the key, for each of these matched elements, is determined by the use attribute. This is an expression, which is evaluated for each matched element. If the expression returns a node-set, the typed value of each node in this node-set acts as a key value. For example, if use="AUTHOR", then each AUTHOR child of the matched element supplies one key value.

Note that:

  1. Keys are not unique: the same value may identify many different nodes

  2. Keys are multi-valued: each matched node may have several (zero or more) values of the key, any one of which may be used to locate that node

  3. Keys can only be used to identify nodes within a single XML document: the key() function will return nodes that are in the same document as the current node.

All three attributes, name, match, and use, are mandatory.

The optional collation attribute can be used when comparing strings.

A key declaration does not apply to any particular source document; in principle, it applies to every document. Saxon builds an index for a particular document the first time the key() function is used to search that document. The Saxon implementation goes to some lengths to ensure that when the same stylesheet is applied repeatedly to the same source document (perhaps a lookup document used in many transformations), the key is only built once. The memory used by a key is freed as soon as either the source document or the stylesheet are garbage-collected.

The Saxon-EE optimizer will automatically create additional keys where these appear to be useful.