Organize your CQL Queries with Chess Assistant


Before Chess Assistant 8 came on the scene, CQL users had to convert all the databases they wanted to search to PGN format. Regular users would have several such databases. Each query was stored in a textfile and bound to a specific database. So in order to apply the same query to several different databases it was necessary to make a copy of the textfile for each one and then modify them to refer to the correct database. In order to indicate what each query does, and which database it searches, one could try to encode that information in the filename. Unfortunately, six months later it was completely forgotten what that filename means. These problems were further compounded by the fact that one would probably have to generate several temporary PGN files in order to speed up complex searches. Of course each CQL textfile could be opened to examine the query itself and any comments that might be there, but that is not the fastest way to find that query you wrote many months ago. Other ways to search through a collection of CQL files can be suggested, but there is no getting away from the fact that this is a primitive way to keep track of your queries.

With regular use of CQL and a growing number of queries and databases a user will be unable to keep track of all his queries in this way.

This is all changed with Chess Assistant 8.1. 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.

This tutorial assumes some familiarity with CQL, although most of the text can be understood without previous CQL experience. For an introduction to Composite seach the Chess Assistant manual and the built-in help are recommended. Additional information about searching with Composite search is available on the CQLCompositeSearch page.

How does Chess Assistant help?

With Chess Assistant CQL queries can be quickly organized, much like a large pile of books would be classifed and then put into the shelves of a library where they can easily be found again.

In order to get started select Composite search from the Search menu to display the Condition dialog.
Composite Search Dialog
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. This serves as a good example of how a large collection of queries can be organized into a hierarchical structure in Chess Assistant. New sections can be added and each one can hold any number og queries.

Adding new sections

CQL queries can be organized by expanding the structure that comes pre-built with Chess Assistant. Let's add a new section that will be a placeholder for some of our queries. We'll add the new section below the existing ones. Right-click on the last section and select Add section from the shortcut menu as shown on the screenshot below.
Add new section
The Section name dialog will be displayed. Enter the name of the section. In this example we'll call the section "Checkmates".
Section name
After entering the name of the section, hit OK and the new section will be created. There is no limit to the number of sections that can be added.

Adding a new CQL query to a section

The new section that we created will hold our CQL queries that find different types of checkmate. Chess Assistant doesn't just store a CQL query by itself. It stores it with some useful information, such as a description, example diagram, region definition etc. Let's start by adding a simple search for a checkmate without any additional conditions. Right-click on the new "Checkmate" section in the Condition dialog and select Add characteristic from the shortcut menu. The Characteristic info dialog will be displayed. Enter a description in the Name for white text box (e.g. Checkmate) and type the query into the CQL query textbox. It already contains the default text, (match) which is the starting point for a new query. Modify it so it looks like this:

The dialog should now look something like this:
Add new query
Click on OK and the new query will be added to the section. The Condition dialog will be displayed again. You can continue adding more queries using the same procedure.

When you are done adding queries you have two options. Select a query that you want to run on the current dataset and click OK , or if you just wanted to add queries without running any of them, click on Cancel . In both cases you will get a warning saying Characteristic info is modified. Save changes? Of course you must click on Yes if you want to save your work.

Importing existing CQL queries

If you have written or collected CQL queries that you keep in textfiles you should use Chess Assistant's capability to import and categorize such queries. The procedure is almost the same as when adding a new query by the method described above. First you create a section for a collection of related queries, or use an existing section. Then you continue as described when adding a new query to a section. Only this time, instead of typing the query into the CQL query textbox, you import the textfile containing the query.

Let's say that we want to add another query to the Checkmate section. This time the query finds smothered mate and we type Smothered mate on the edge or in the center of the board in the Name for white text box. Next we have to import the file. Note the two icons on the top right above the CQL query text box.
Import a CQL file
The left one is for importing a CQL file, so that's the one we are interested in. When you push it the Load CQL file dialog opens, which is nothing but the familiar file open dialog with the file type preset to CQL files. Find the CQL file you want to import and click on Open . The CQL file is then imported into the CQL query textbox which will look something like this:
Old style CQL query
As mentioned before each CQL query is bound to a specific PGN database. In this case the query we imported was designed to search heijden.pgn. What we haven't mentioned is that the query also must specify where the output of the search should be stored. That's another PGN file and in this case it's out.pgn. Chess Assistant offers much more flexibility and these restrictions should simply be removed when importing old CQL files into Chess Assistant. So, the following lines should be deleted from the imported CQL script:
:pgn heijden.pgn
:output out.pgn

After that save the query as described above and remember to save the changes when asked!

Illustrative diagrams

Illustrative diagrams should always be added to Composite search queries. To add a diagram highlight the query in the Condition dialog and then press New example below the diagram on the right side of the dialog. This brings up the Position operations dialog which is the normal dialog in Chess Assistant for setting up positions.
New illustrative diagram
It should be mentioned that an EPD string can be pasted into the diagram by pressing Shift + Ins . When the position has been set up press OK to save the position as the new illustrative position for the CQL query. After that this position will be displayed whenever the query is selected in the Condition dialog.


Chess Assistant offers CQL users an excellent way to organize their queries, the flexibility to apply the same query to any database or dataset, and finally 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, including the Compound characteristic that can be accessed through the shortcut menu in the Condition dialog.

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