Chess Query Language (CQL) is a structured query language which is designed to allow chess players and researchers to search for games, positions, problems, and studies in a quick and relatively easy manner.

The user specifies the items that they are looking for, and the database in which to search. After running, the query creates a file in Portable Game Notation (PGN) format that contains all the games or positions matching the query criteria.

The language is designed to be extremely flexible; for example, a user does not have to define exactly the position or theme that they are looking for, but can modify the query so that it will find similar results within certain parameters.

Items and themes that CQL can search for include, but are not limited to:

  • Player names
  • Date and location of games
  • Chess opening used
  • Certain moves orcombinations of moves
  • Certain pieces located on certain squares
  • Patterns of pieces in certain locations
  • Which pieces each side has left
  • Complex criteria such as safety or certain pawn structures.

Chess Query Language (CQL) was designed to allow researchers, authors, and players to search for games, problems, and studies that match specific themes.

You specify the theme you are looking for, and the database to look for them, in CQL. Then you run this CQL file using cql.exe . This creates a new PGN file that has all the games matching your theme.

CQL specifies a small but powerful set of primitives to define chess themes. CQL can find much more complex themes than any other chess program.

Users have searched for themes like stalemates with multiple pins; games in which the same position recurs but with the winning side missing just one piece; Nowotny and Grimshaw themes, games with some number of captures on a single square, games with a certain number of black and white passed pawns, and many more.

Questions or comments about CQL should be directed to . Feel free to ask for code to build themes you are interested in.


CQL was developed by Gady Costeff and Lewis Stiller. It is Copyright (c) 2003-2004 and is free.