CQL Function Module
Confluence 5.9 and later
Purpose of this module
The CQL Function Module allows plugins to add additional functions to CQL.
Functions provide a way for values within a CQL query to be calculated at runtime. Consider the space keyword in CQL, which can be used to query content that exists in a particular space. This in itself may not seem powerful, but when combined with the favouriteSpaces function, "space = favouriteSpaces()", it provides a way to find all of the content that exists in a user's favourite spaces.
It's important to note that CQL functions can only provide values to a query; most importantly, they can't be used to process the results.
CQL functions can take arguments. These arguments must take the form of simple string values.
- For more information about plugins in general, read Confluence Plugin Guide
- For an introduction to writing your own plugins, read Writing Confluence Plugins
CQL Function declaration
Here is an example
atlassian-plugin.xml declaring a new CQL function:
The class attribute defines the function implementation class. This class must implement:
CQL Function types
CQL works by first expanding functions and then evaluating the expanded statement to return a set of results. For this reason, there are two types of CQL functions which can be implemented.
Single value query functions
Single value query functions return a single String value upon being expanded. So
Single value query function implementations should extend from the
Multi value query functions
Multi value query functions return a number of String values upon being expanded. So
Multi value query function implementations should extend from the
An example CQL Function implementation
Returns the number of arguments accepted by the Query Function. For example, the NowFunction has a paramCount of 1, and it accepts a single argument, "created = now('-1w')" :
The invoke method of a given Query Function class is called when a CQL statement is executed containing that Query Function.
Accepts as arguments a List of String objects params, which are the parameters passed into the Query Function in the CQL statement being executed, as well as an EvaluationContext object context. The method should return an Iterable of String values which will be the values that the Query Function will be transformed into, appearing within the parenthesis following the IN clause in the CQL statement being executed.
As above, accepts as arguments a list of params and a context object. The method should return a single String value which will be the value that the Query Function will be tranformed into, appearing as a single quoted value following the = operator in the CQL statement being executed.
The class definition of the object that is passed as the context argument to the invoke method of a Query Function.
Provides Confluence specific contextual information to a Query Function. Contains a method to optionally provide the space, contentId and contentType context that the CQL search is being executed in. If the function relies on a piece of contextual information that is not present, it should throw an InvalidFunctionQueryException. For example the invoke method of the currentSpace() function requires that the current space be present in the evaluation context.