CQL Field Module
Confluence 5.9 and later
Purpose of this module
The CQL Field Module allows plugins to extend the Confluence Query Language to add additional fields.Field Modules interact with other plugin modules, to produce v2 search queries which map to Lucene queries using a Search Query Mapper Module Lucene Index that has been extracted with an Extractor Module.
CQL Field Modules also provide UI support capabilities, allowing fields added by plugins to be presented to users via the UI in components of the application built on top of CQL, for example in the search screen.
- For more information about plugins in general, read Confluence Plugin Guide.
- For an introduction to writing your own plugins, read Writing Confluence Plugins.
CQL Field declaration
Here's an example
atlassian-plugin.xml declaring a new CQL field:
the class attribute defines the field handler implementation class. This class must extend
com.atlassian.querylang.fields.BaseFieldHandlerand implement one of:
- the ui-support declaration provides information to allow Confluence to render the new field in the UI:
- The value-type attribute specifies the data type of the new field.
- The i18n-key attribute specifies a key which will be used to provide translated labels for your field when it is presented in the UI.
- An optional data-uri attribute to allow the plugin to specify string values which will be used to populate the UI.
Supported UI Value Types
||"With Title" Field|
||"Of Type" Field|
||"Created Date" Field|
||"In Space" Field|
||"Mentioning User" Field|
|string||"Status" Field, used in conjuction with a data-uri, see Adding a field to CQL|
CQL Field types
The field types determine the syntax of the value and the operations that can be used in an expression. Field handlers must implement at least one of four interfaces, however there are some existing helper classes that provide partial implementation.
|Field type||Supported operations||Interface|
|Text||=, !=, IN, NOT IN, ~, !~||
|Equality||=, !=, IN, NOT IN||
|DateRange||=, !=, >, >=, <, <=||
|Number||=, !=, >, >=, <, <=||
An example Field Handler implementation
Here's an example Field Handler implementation.
Returns the name of the field that this handler handles, this field name will be used in CQL expressions.
Returns true if this field supports being part of an ORDER BY clause. If this is true, the handler must implement the buildOrder method.
Returns a FieldMetaData object describing the CQL field. Metadata includes a flag to indicate if the field is an alias of another field, and if the field has UI support.
Builds and returns a FieldOrder object which is used to sort search results. The FieldOrder object contains the name of the field to which the order applies and an OrderDirection either ascending or descending. If the field does not support ordering, BaseFieldHandler provides an appropriate default implementation.
The BaseFieldHandler class provides a partial FieldHandler implementation from which others should be extended. It implements both the FieldHandler interface as well as the SubFieldHandlerProvider interface which allows for the definition of CQL subfields for example user.fullname = 'Joe Bloggs', user.userkey = 'jbloggs'
The interfaces for each of the field types (Text, Equality, DateTime and Numeric) define a build method which accepts as arguments an ExpressionData object as well as either a single value or Iterable of values. The method returns a V2SearchQueryWrapper object, which as the name suggests, is an object designed to wrap a V2 Search Query and the object and determines which data is queried from the index and returned as CQL search results when a field is used.
Returns the CQL operator used in the query, allowing the FieldHandler to return the appropriate V2 Search Query Wrapped object based on the operator. For example, the CQL query "space = 'MYSPACE'", will yield a result of EQUALS when the EqualityExpressionData.getOperator method is called.