cts.aggregate

cts.aggregatectsaggregate

/apidoc/8.0/cts:aggregate.xml

Executes a user-defined extension aggregate function against a value lexicon or n-way co-occurence of multiple value lexicons. Value lexicons are implemented using range indexes; consequently this function requires a range index for each lexicon specified in the function. If a specified range index does not exist an error is raised. If the "ordered" or "proximity=" option is specified, the range index must have range value positions set to true, otherwise an error is raised.

The path to the native plugin library containing the implementation of the user-defined extension aggregate.

native-plugin

String

The name of an aggregate function in $native-plugin.

aggregate-name

String

A sequence of references to range indexes. The first range index specified in this or any other aggregate function cannot be of type "nullable".

range-indexes

cts.reference[]

A sequence containing the arguments for the aggregate function. A map can be used to pass in multiple sequences of arguments.

argument

ValueIterator

options. The default is ().

Options include:

"any"

Co-occurrences from any fragment should be included.

"document"

Co-occurrences from document fragments should be included.

"properties"

Co-occurrences from properties fragments should be included.

"locks"

Co-occurrences from locks fragments should be included.

"fragment-frequency"

Frequency should be the number of fragments with an included co-occurrences. This option is used with cts:frequency.

"item-frequency"

Frequency should be the number of occurences of an included co-occurrence. This option is used with cts:frequency.

"ordered"

Include co-occurrences only when the value from the first lexicon appears before the value from the second lexicon. Requires that word positions be enabled for both lexicons.

"proximity=N"

Include co-occurrences only when the values appear within N words of each other. Requires that word positions be enabled for both lexicons.

"checked"

Word positions should be checked when resolving the query.

"unchecked"

Word positions should not be checked when resolving the query.

"too-many-positions-error"

If too much memory is needed to perform positions calculations to check whether a document matches a query, return an XDMP-TOOMANYPOSITIONS error, instead of accepting the document as a match.

"concurrent"

Perform the work concurrently in another thread. This is a hint to the query optimizer to help parallelize the lexicon work, allowing the calling query to continue performing other work while the lexicon processing occurs. This is especially useful in cases where multiple lexicon calls occur in the same query (for example, resolving many facets in a single query).

options

String[]

Only include co-occurrences in fragments selected by the cts:query, and compute frequencies from this set of included co-occurrences. The co-occurrences do not need to match the query, but they must occur in fragments selected by the query. The fragments are not filtered to ensure they match the query, but instead selected in the same manner as "unfiltered" cts:search operations. If a string is entered, the string is treated as a cts:word-query of the specified string.

query

cts.query?

A sequence of IDs of forests to which the search will be constrained. An empty sequence means to search all forests in the database. The default is ().

forest-ids

String[]

ValueIterator

Only one of "fragment-frequency" or "item-frequency" may be specified in the options parameter. If neither "fragment-frequency" nor "item-frequency" is specified, then the default is "fragment-frequency".

Only one of "any", "document", "properties", or "locks" may be specified in the options parameter. If none of "any", "document", "properties", or "locks" are specified and there is a $query parameter, then the default is "document". If there is no $query parameter then the default is "any".

Only one of the "checked" or "unchecked" options may be specified in the options parameter. If neither "checked" nor "unchecked" are specified, then the default is "checked".

For details, see Using Aggregate User-Defined Functions in the Search Developer's Guide.

//    This query assumes an element range index is configured
//    in the database for the 'Amount' element and that a plugin module 
//    installed under native/samplePlugin contains a UDF named "myAvg".

cts.aggregate("native/samplePlugin, "myAvg",
  cts.elementReference(xs.QName("Amount"), "type=decimal"),
  null, ["fragment-frequency","concurrent"]);

=> 1410.23914666667