CQL: The Chess Query Language (version 6.1)

What is CQL?

Chess Query Language (CQL) searches for user-defined patterns in chess games and studies.

To use CQL

• first, define the pattern you are looking for in the CQL language;
• second, run cql specifying that pattern.

CQL will output a new file that contains all the games in the input file that match your pattern.

Quick intro: mirror mates

Suppose the pattern you are looking for is mirror mates, where the mated king is surrounded by empty squares: Arestov 2013, after 10. h8=N#
(found from CQL file: mirrormate.cql)

You can find these by running

cql -i sample.pgn examples/mirrormate.cql

Here, sample.pgn is the file of games to search. The pattern specifying mirror mate is in the file mirrormate.cql.

The meaning of the terms in the pattern specified in mirrormate.cql are:

• btm means black to move;
• mate means checkmate;
• _ means empty square;
• attackedby means attacked by.
• k is the black king.
• _ attackedby k is the set of empty squares adjacent to the black king.
• _ attackedby k == 8 means this set has 8 squares in it
• flipcolor means to repeat the search with colors interchanged.

Click on the examples tab in the sidebar for more examples.

Additional documentation

Additional contributed documentation (currently in draft form) is available at documentation . Documentation for CQLi also includes new documentation of CQL itself.

The EG discusses CQL in a number of columns, particularly by Emil Vlasàk.

Downloads

CQL may be downloaded here. Questions or comments about CQL should be directed to costeff at the domain gmail.com .

CQLi

CQLi, written by Robert Gamble, is a high-quality, efficient and robust implementation of the CQL 6 language. CQLi also has a number of new features that CQL 6 does not support, including support for "imaginary" positions that do not occur in the game tree; Unicode; and communication with external programs. CQLi is extremely well-architected and accurate, and typically runs much faster than CQL. (Much of CQL 6 was tested and debugged by testing it against earlier versions of CQLi).

Version

The current version of CQL is CQL 6.1 (build 9.362).

Credits

CQL was initially developed by Gady Costeff and Lewis Stiller. It is copyright (c) 2003-2021 and is free. It uses SCID code by Shane Hudson to parse the PGN files. Robert Gamble contributed extensive design, implementation, and testing assistance.