CQL: The Chess Query Language (version 6.0 beta 3)

What is CQL?

Chess Query Language (CQL) searches for user-defined patterns and themes 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 -cql "btm mate _ attackedby k == 8"

Here, sample.pgn is the file of games to search. The pattern specifying mirror mate is in the quoted string following the -cql option. (Usually the pattern is in a separate file.)

The meaning of the terms in the pattern are:

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


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


The current version of CQL is CQL 6.0 (beta 3). CQL 5.2, the previous major release, is here.


CQL was developed by Gady Costeff and Lewis Stiller. It is copyright (c) 2003-2019 and is free. It uses SCID code by Shane Hudson to parse the PGN files.