Wiki source code of Design of the CQL query module
Last modified by superadmin on 2026/10/14 18:25
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | For the design of the CQL module as a whole, see [[Design of the CQL module>>doc:documentation.extensions.dev.cql.design.WebHome]]. | ||
| 2 | |||
| 3 | == General considerations == | ||
| 4 | |||
| 5 | In Confluence, CQL is tightly connected to its search feature. One can typically perform an advanced search using a CQL query. CQL fields typically looks like fields indexed by something like something like Lucene / Solr or Elastic Search, as opposed like a SQL / hibernate database, which would be typically lower level. [[Atlassian documentation>>url:https://developer.atlassian.com/server/confluence/advanced-searching-using-cql/]] hints at Lucene: | ||
| 6 | |||
| 7 | > You can use the CONTAINS operator to use Lucene's text-searching features when performing searches on these | ||
| 8 | |||
| 9 | Luckily, XWiki is quite similar to Confluence in being written in Java and using a similar architecture especially when it comes to search. In XWiki, we use Solr, which is backed by Lucene. | ||
| 10 | |||
| 11 | Consequently, we chose to implement CQL support with a conversion to Solr expression, which is likely similar to what Confluence does as well. The main difficulty is that we obviously don't use the same indexed document schema, and we don't even have the same fields or the same exact concepts (see [[xwiki:documentation.extensions.admin.confluence.xwiki-equivalence.WebHome]] for more information on this), so the conversion is not straightforward. We don't have a 1:1 mapping between CQL fields and fields we have in XWiki's Solr indexed documents. Fortunately, it's close enough for the more used features. | ||
| 12 | |||
| 13 | == The CQL query executor == | ||
| 14 | |||
| 15 | The CQL Query module [[implements ##org.xwiki.query.QueryExecutor## with the name ##cql##>>url:https://github.com/xwiki-contrib/cql/blob/master/query/src/main/java/org/xwiki/contrib/cql/query/internal/CQLQueryExecutor.java]], which makes it possible to instanciate a ##org.xwiki.query.Query## object with a ##cql## type and a cql expression and execute this query like any other query or any supported type. | ||
| 16 | |||
| 17 | This query executor: | ||
| 18 | |||
| 19 | 1. parses the query using the [[AQL parser>>doc:documentation.extensions.dev.cql.aql-parser.WebHome]] (see its [[design>>doc:documentation.extensions.dev.cql.aql-parser.design.WebHome]]) | ||
| 20 | 1. converts the resulting abstract syntax tree to a Solr query | ||
| 21 | 1. executes the Solr query. | ||
| 22 | |||
| 23 | For the end user, executing a CQL query is exactly like executing a Solr query, notably with the same kind of results. | ||
| 24 | |||
| 25 | == The CQL to Solr conversion == | ||
| 26 | |||
| 27 | The CQL to Solr conversion is done by the [[##CQLToSolrQueryConverter##>>url:https://github.com/xwiki-contrib/cql/blob/master/query/src/main/java/org/xwiki/contrib/cql/query/converters/CQLToSolrQueryConverter.java]] component. The general idea is that this component and all the components implementing [[##CQLToSolrAtomConverter##>>url:https://github.com/xwiki-contrib/cql/blob/master/query/src/main/java/org/xwiki/contrib/cql/query/converters/CQLToSolrAtomConverter.java]] has a ##convertToSolr## method that returns a solr sub-expression for each AQL AST node type that can be converted to a solr sub-expression. | ||
| 28 | |||
| 29 | It was decided to make the conversion modular and extensible because CQL itself can be extended in Confluence: Confluence plugins can add fields that can be queried from CQL. Making the conversion modular on our side allows XWiki extensions that would implement the features of such CQL plugins to also "make the CQL part work". | ||
| 30 | |||
| 31 | Basically, extensions can implement their own [[##CQLToSolrAtomConverter##>>url:https://github.com/xwiki-contrib/cql/blob/master/query/src/main/java/org/xwiki/contrib/cql/query/converters/CQLToSolrAtomConverter.java]], typically by extending [[##DefaultCQLToSolrAtomConverter##>>https://github.com/xwiki-contrib/cql/blob/master/query/src/main/java/org/xwiki/contrib/cql/query/converters/internal/AbstractIdCQLToSolrAtomConverter.java]] which makes this work way easier. | ||
| 32 | |||
| 33 | To see how this works in practice, please see [[Query>>doc:documentation.extensions.dev.cql.query.WebHome]]. |
