Composite search in Chess Assistant is based on CQL (Chess Query Language). CQL is an extremely powerful query language designed for searching chess databases. All the different types of searches that are possible in modern chess database systems can be done with CQL. That is, however, just a starting point for CQL which offers so much more power and types of searches that previously were impossible.
Chess Assistant, starting with version 8, offers all the power of CQL in an integrated environment. This implementation brings several advantages, including:
  1. CQL queries can be run on any type of database that Chess Assistant can handle, instead of only PGN databases.
  2. CQL queries are not bound to a specific database. Define the query once and then apply it to any selection of games (dataset) from any database.
  3. The result of a CQL query is displayed as a list of all the matching games with markers showing the exact position(s) that matched the query. Browsing through the resulting list of games will automatically display the first matching position in each game.
  4. When examining the matching positions a diagram with automatically generated graphical annotations highlights the features that match the query.
  5. Chess Assistant allows you to organize your whole collection of queries into a neat structure, so you can quickly find any query you may be looking for. Each query is identified by a description and you can even attach an illustrative chessboard diagram, which greatly facilitates the usage of this feature.

The organization of CQL queries into a hierarchical structure is accomplished through Composite search, which at the same time offers several convenient features for managing and running CQL queries. This tutorial describes how to use Composite search in Chess Assistant based on previously defined queries. It goes into more details than the Chess Assistant manual and the built-in help, which are highly recommended as an introduction to Composite search.

This tutorial will not teach you how to write CQL queries, and some familiarity with CQL is assumed, although most of the following text can be understood without previous CQL experience.

Composite search overview

Composite search stores CQL queries with some useful information, such as a description, example diagram, region definition etc.

Select Composite search from the Search menu to display the Condition dialog. Note that unlike other types of searches in Chess Assistant a dataset must be selected before Composite search or CQL search can be performed.
Composite Search Dialog
The Condition dialog is the control center for Composite search. Here the user can quickly browse through a systematically organized collection of queries with the aid of a hierarchical structure, textual descriptions and diagrams with graphical annotations.

On the left side of the dialog the existing queries are categorized in a hierarchical structure. As you can see, Chess Assistant comes with a large collection of pre-built queries that can be useful on their own or serve as examples and building blocks when you start writing your own queries. The pre-built queries are organized into nine sections, and each section contains several queries.

In the dialog above a query has been highlighted. This is query number 15 in section 2, King's position. It's index is therfore 2.15 and the description of the query is "King has one move". The diagram illustrates that situation. The white king, the object of this query, is marked with a red rectange. All squares around it, except one, are attacked by enemy pieces. Those squares are marked with a green X. The only square that the king can move to is c1 and that square is marked with a green border. Obviously, a diagram like this is very helpful when searching for queries and understanding their purpose.

The Side drop-down list allows you to define which side the selected condition refers to. It will be explained in more detail later.

Pre-defined CQL queries in Chess Assistant can also accept a parameter for certain material conditions in the query. It is controlled by the Quantity spin boxes (from and to).

The example diagram position can be modified by pushing New example .

When Region is selected the diagram displays the region of the board that applies to the query. This advanced feature was primarily introduced for use in the pre-built queries that come with Chess Assistant.


Before using Composite search the dataset to be searched must be selected. Then open the Condition dialog by choosing Composite search from the Search menu.

The simplest way to use Composite search is to select a query in the Condition dialog and click OK to start searching, but there are also ways to modify the search by setting the different parameters that are offered in Composite search.


It is important to realize that the pre-built queries in Composite search do not search for the given condition for both sides. For instance one of the pre-built queries searches for positions with a protected passed pawn. If that query is run in the simple way described above it will only return games where white has a protected passed pawn. The same applies to other queries, but when in doubt the illustrative diagrams will help.

What if you wanted instead to look for positions where the search condition is applied to the black side? In the past, before Chess Assistant 8, the only way to handle that situation was to modify the query. Then the query would be saved and run again. And if you wanted to apply the search condition to both black and white a third version of the query would be needed. Here, Chess Assistant helps to reduce the multiplicity of essentially the same query. Instead of three different queries only one is needed. The trick is to use the Side drop-down list box to instruct Chess Assistant to switch colors or to run the query for black and white simultaneously:
White: Run the query "as is"
Black: Switch colors
Any: This option combines White and Black and the search is performed for both sides.


The Quantity fields offer users another way to reduce the number of queries needed to accomplish certain related searches. When Quantity does not apply to a query it is grayed out. If it is active it means that the query accepts quantity as a parameter that affects the search condition.

Let's take a simple example. In the Controlling center and periphery section of the pre-built queries choose 9.12. Weak square occupied by enemy piece. If run with the default settings this query will find all games containing positions with 1-10 weak squares in white's camp that are occupied by enemy pieces. Let's change the to spin box of the Quantity parameter to 2. This means that we will be searching for positions with at least two weak squares occupied by black pieces. Of course we can also change the Side to Any to perform the search for both black and white. Note that in this case the query does not search for a total of 2 or more weak squares on the board. Instead it finds all positions where either black or white has at least 2 weak squares occupied by enemy pieces. That excludes position where, for instance, white has tone weak square and black one weak square, both occupied by enemy pieces.


When a query has a region definition it can be used to limit the location of some or all the pieces, but the precise meaning of a region depends on implementation details of the query. To see the currently define region for a query click on Region below the board. The region button is only displayed for those queries that use a region.

The following diagram shows a region that is composed of the e-h files. This could, for instance, be used to restrict the location of the white king to that region of the board.
Composite Search Region
The region can be altered by clicking (include) and right-clicking (exclude) on a square:
Click: The square
Shift + Click: The file
Ctrl + Click: The rank
Alt + Click: The diagonal parallel to the main diagonal (a1-h8)
Alt + Shift + Click: The diagonal parallel to the a8-h1 diagonal
Ctrl + Shift + Click: All squares that a rook could move to on an empty board.
Ctrl + Alt + Shift + Click: Both diagonals

Note that some of the pre-built queries don't have a region definition, while others may limit the allowed selection to either ranks or files. In some cases a query depends on a fixed, predefined region and changing it would produce unpredictable results. In such cases the query author may have disallowed any modification to the region.

Start searching

After the query has been selected and the parameters have been adjusted as needed its time to run the query by clicking on the OK button in the Condition dialog. Note that CQL searched can take a much longer time than other types of searches in Chess Assistant. When running a query you haven't tried before it makes good sense to test it first on a small dataset and use the duration to estimate how long it would take to run on a larger collection of games.

A composite search can be interrupted at any time by clicking on Cancel in the message box that is displayed while the search is in progress. The progress indicator in the message box always shows the elapsed time for the search and the estimated total time which will help you to decide if it is necessary to interrupt the search.
Composite Search Progress Indicator
If the search is interrupted before it is finished it will display the games found so far, which can be quite useful.


Chess Assistant offers users the flexibility to apply the same query to any database or dataset, and reduces the number of queries needed to perform related tasks. Besides what has been described above, there are other powerful options that CQL users should explore in Chess Assistant, such as adding new queries and defining their own queries.

CQL is a wonderful tool on its own, but Chess Assistant adds the query organization tools and convenience that all long term users of CQL will appreciate.
Valid XHTML :: Valid CSS: :: Powered by WikkaWiki