xsl:key
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.
Category: declaration
Content: sequence-constructor
Permitted parent elements:
xsl:package
; xsl:stylesheet
; xsl:transform
Attributes
|
| Name of the key. |
|
| Pattern defining the set of nodes to which
the key applies. For example, if |
|
| Expression to determine the value of the key,
evaluated for each matched element. If the expression returns a sequence of
nodes, then the typed value of each node in this sequence acts as a key value.
For example, if |
|
| Implemented since Saxon 9.7. If the key
specifier returns a sequence of atomic values, then this attribute determines
whether each value is treated as an individual key (when
|
|
| The name of a collating sequence, used when comparing strings. If present it must be a collation URI recognized by Saxon: see Sorting and collations. |
Saxon availability
Available in XSLT 1.0 and later versions. Available in all Saxon editions. Available for all platforms.
Notes on the Saxon implementation
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 ability to define composite keys is new in XSLT 3.0 and is implemented since
Saxon 9.7. (In Saxon 9.6, using the attribute composite="yes"
generated an error.)
The Saxon-EE optimizer will automatically create additional keys where these appear to be useful.
Saxon provides an extension function saxon:key-map() which returns a map
giving access to the index constructed using xsl:key.
Details
Note that:
-
Keys are not unique: the same value may identify many different nodes
-
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
-
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.