CQL: The Chess Query Language (version 6.2 beta 2)

Note: This is a prototype. It is not fully documented and has bugs. See New CQL 6.2 features for more detailed information and links about this release.

See CQL 6.1 documentation for CQL 6.1 documentation

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: Greek gift sacrifice

Suppose you are looking for Greek gift sacrifices, where White sacrifices a bishop for a pawn on h7 and follows up with ♘g5+ , as in
Edgar Colle - John James O'Hanlon 1930, before 12 Bxh7+
(found from CQL file: greekgift.cql)
.

You can find these in your database by running 

cql -i sample.pgn examples/greekgift.cql

Here, sample.pgn is the file of games to search. The pattern specifying Greek gift is in the file greekgift.cql: 

  ⊢ ♗×♟h7 check
    ♚×h7
    ♘――g5 check

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

  • ⊢ introduces a sequence of moves
  • ♗×♟h7 means that a white bishop captures on a black pawn on h7
  • check means that one side is in check.
  • ♚×h7 means that the black king captures on h7
  • ♘――g5 check means that the white knight moves to g5, giving check.

If you wanted to search for black Greek gifts too, just insert the glyph ⬓ before the ⊢ symbol: 

  ⬓ ⊢♗×♟h7...

⬓, or flipcolor means to allow the colors to be reversed. (You can always find the ASCII equivalent for a symbol by hovering over it in this documentation).

If you wanted to include queenside Greek gifts, insert the flip, or ✵ symbol: 

  ✵⬓ ⊢ ♗×♟h7...

If you wanted to allow any number of moves by non-♚ pieces after the king recaptures and before the knight giving check, you can use regular expressions: 

  ✵⬓ ⊢ ♗×♟h7 check
      ♚×h7
     ~♚――*
      ♘――g5 check

Here, ~♚ denotes the squares other than the black king's, so ~♚―― denotes a move by any piece other than the black king. The * at the end means to repeat 0 or more times, as in string regular expressions.

In general, move sequences in CQL can be augmented with board rotations, reflections, and shifts. Regular expressions can be applied directly to move sequences to allow for more complex patterns.

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

CQL 6.1 compatibility

CQL 6.2 is generally back-compatible with CQL 6.1. Users of CQL 6.1 who do not want to use new CQL 6.2 features can continue to rely on CQL 6.1 language documentation while using the CQL 6.2 executable.

Additional 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 .

VisualCQL

VisualCQL is a Windows GUI that we recommend for most users who run CQL on Windows. VisualCQL was developed by Emil Vlasák and supports the new Unicode characters in a clear and easy-to-use manner.

CQLi

CQLi, written by Robert Gamble, is a high-quality, efficient and robust implementation of the CQL 6.1 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.2 beta 2

Credits

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