FAQ

1. Can I use CQL to search full chess games?
Yes. Version 6 in particular has performance enhancements (including threading) that make searching large chess databases of full chess games (that is, competitive over the board chess as contrasted with composed studies) much quicker than in prior versions. CQL also has some language enhancements targeted at full chess games, like pawn structure filters, fen support, and command line programming.

To use CQL with a database of games, you have to convert the database to PGN format first (sometimes it is nontrivial to convert a large database of chessgames in a proprietary format to PGN). If you are using CQL to search competitive chess games, you can ignore any documentation that talks about variations. In such chess games, the variations are rarely as important or as fully specified as in a study. You should likewise disregard any of the examples that use the variations keyword in the CQL header: these do not apply to ordinary chess games.

2. Is the source available?
Yes. Email us for the most recent source version.
3. What is the source license?
CQL is built using the PGN parser written by Shane Hudson, licensed under GPL 2, which is part of the SCID chess database chess database system. All code not in the subdirectory orig is licensed under an MIT license. The sample database is extracted from the Heijden database and is used with permission.

If you are doing something interesting with CQL, or using it for publication, we'd like to hear from you.

4. I need help writing CQL code
CQL 6 has many new features. Moreover CQL 6 is targeted more towards programmers than previous versions were. Thus, we are happy to help you with writing CQL code; just email us.
5. I've found a bug in CQL or a documentation error
Email us at costeff at gmail.com. For bugs, please include the CQL version and build (these are printed when CQL is run), as well as the platform (Windows, Mac or Linux).
6. I am using a transform (e.g. flipcolor, shift, flip) and getting strange results.
Most of the time this is because transforms only apply to the succeeding filter. For example,

flipcolor
           wtm
           N attacks r

will only match a position where a white knight is attacking a black rook. To get positions where a side could capture a rook of the opposing color with a knight, use

flipcolor
          {wtm
           N attacks r}

See the discussion of precedence for more information.

7. Why am I'm getting an error message about unknown character?
CQL files (files with the .cql extension) only handle ASCII characters. Don't confuse the -->, which is made up of three ASCII characters, with the unicode →. Likewise, don't confuse the - symbol with the Unicode — .
8. Why doesn't shift horizontal seem to work?
Because CQL interprets shift horizontal as two different filters, shift followed by horizontal. You probably want to use shifthorizontal instead.
9. Why am I am getting an error message about an attempt to access unbound variable?
This is usually because you are trying to use a variable outside the scope of the piece or square or echo filter that defines it. For example,

 square x in A
  x attacks k
  q attacks x

will yield an error because the x in q attacks x is outside the scope of the square filter, which is internally interpreted like this:

 {square x in A       
   {x attacks k}}
 q attacks x

Note that this is a change from prior versions of CQL, for which the square filter read all successive filters. Now, square and piece just apply to the single following filter (x attacks k in this case).

There is more discussion of this issue here.

10. How can I search for studies with a specific number of pieces?
See the == example for a discussion using the QQqq.cql CQL file to find a study (Elkies 1993) with specific material (two queens against two queens).
11. Is there a GUI?
No, but there is some support in this version for a GUI mode that we hope will make it easier for other developers to write a GUI.
12. Can I use CQL to search chess problems?
It can, but not well. CQL does not handle fairy specifications or nonstandard rules. Even for direct mates, the biggest obstacle is that there is no standard PGN database of problems that corresponds to the Heijden database of studies.
13. How can I get a database of studies to use with CQL?
We recommend the Heijden database of endgame studies for use with CQL.
14. How can I find pins?
Use the pin filter.
15. Can I find zugzwangs with CQL?
You can find a zugzwang in the sense of an endgame study: a position in which having the side to move worsens the result from the point of view of the player with the move, assuming both positions are included in the PGN file. In full chess, "zugzwang" is often used informally to mean a position in which having the move only delays the result, and CQL cannot search for these directly in a typical full chess game.
16. What do I need to get started with CQL?
You need a PGN file of chess games or chess studies; a program to view PGN files; and a text editor to write CQL code. You also need to be able to run CQL from a console, such as PowerShell(Windows) or the shell (Linux/Mac).