Indexing

An index is an additional structure which is used to simplify or speed up access to data.

Indexes are typically created during node derivation and are held as derived data. They typically index the contents of a package.

Indexes can also be built as part of other processing. Code can create the index when it is not present, which means it will be reused until the data is next refreshed, at which point it will be updated. The index will add to data that is already there.

The built-in ScriptApplication.index() method creates indexes and writes them to a node's derived data. It is driven by an options block.

Example:

application.index({
  node:       context,
  type:       "target",
  memberType: "system.TAG_LIST",
  all:        "library.core.IndexAll",
  targets:    "library.core.TagIndex",
  include:    ["library.tags.MemberTypeTag","library.tags.TypeTag"],
  classify:   true
});

See the derivation script in All (library.core.IndexAll) for an example of typical usage.

The method returns true if it has worked, or false if there is an error in the parameters. If it returns false, the application error fields will be set.

Options

OptionDescription
node The node to be indexed. The default action, which is the only one currently supported, is that the package contents of this node will be indexed, and the indexes written to the derived data of this node.

The nodes to be indexed (in this case the package content) are known as the index set, and each node within the index set is known as an indexed node.
type The type of index being built. Currently the only supported value is "target", which is also the default value.
memberType The member type of the indexed nodes that will be examined.
all An output member type on the node to which will be written all the nodes in the index set will be written:
  • The value will be the value of the first member of the indexed node if present, or null if absent.
  • The scale will be the scale of the first member of the indexed node if present, or 0 if absent.
  • The target will be the indexed node.

If omitted, this output will not be written.
included An output member type on the node to which will be written all the nodes in the index set that match the selection criteria.
  • If the include option is set, the selection criteria is all the indexed nodes that have a target in the include list.
  • If the include option is not set, the selection criteria is all the indexed nodes that have a member.

The contents of the selected members are the same as for the "all" output, except that when an include list is used, the member chosen will be the first that matches any on the include list.
targets An output member type on the node to which will be written a list of the targets found on the selected indexed nodes. Only the target will be set.

The targets option can be used with the include option, in which case it will list those targets from the include list which were actually found.
excluded An output member type on the node to which will be written the nodes that would be in the all output but not the included output. The contents of the members is the same as for the all output. (If there is no include list, this will simply list the indexed nodes that do not have any members for the given member type).
include An array of targets to include in the index. This is used to limit the nodes to be indexed. If omitted, null or undefined, then all nodes are indexed. If empty (i.e. [] is passed), then this is considered valid. No members will be written to the included member type, but a member for each node in the index set will be written to the excluded member type. This behaviour may be useful, for example allowing the user to select a variable number of tags for indexing.
classify A boolean. Set to true to use each of the targets in the included indexed nodes as a member type on the node, and to write members from the indexed nodes to those member types, replacing the targets with the indexed nodes.

Set to false (the default) to not do this.

Notes

    • Nodes can be passed as strings, numbers or script nodes.
    • The all, included, targets or excluded options are optional. If they are omitted, the specified outputs are not written.
    • The index does not overwrite existing members. Indexes can therefore add to inherited member types.
    • Members are added in ascending name sequence. Sort order is not guaranteed if the output member types already contain members.
    • The user must have admin authority on the node to run the index. Derivation scripts run under the authority of the owner who is by default the creator of the node and who will have the necessary authority.
    • The index only reads the latest version of the package contents.
    • If the application object is in error before index() is called, index may fail unexpectedly.