Chess Query Language (CQL)

Introduction

When working with large chess PGN databases, finding what you want can be a difficult task, but that is where a tool like Chess Query Language (CQL) can prove very useful. All you need is a chess PGN database (like Millionbase, TWIC, or your own Chess.com archive of games you've played), your favorite text editor (mine is Notepad++), and some experience/knowledge of using the command line and writing scripts. CQL comes with a bunch of sample .CQL scripts for you to look at. CQL was originally written to aid chess puzzle writers, but has also proven useful to researchers, authors, and players. 

Setting Up

Step 1: Open your folder where you intend to work with CQL and extract your zipped copy of CQL to it. There will be a lot of files but you can safely move everything from the zip file but cql.exe into a sub folder. 

Step 2: Place a copy of your PGN into the same folder as cql.exe

Step 3: Choose a .cql from the samples or write your own and place it in the main folder alongside cql.exe and your PGN database.

Step4a (Optional): If you intend to use the command line to work with CQL and are on Windows, I would make a copy of cmd.exe and keep it in the cql folder to save time on navigating to your CQL folder.

Step4b (Optional): Alternatively, you could use the VisualCQL instead of the command line, but I find the command line faster.

Basic Usage - Running CQL

Once you have a PGN database, CQL.exe, a .cql script, and your choice of command line or VisualCQL setup in your cql folder, you are ready to start using the program.

Step 1: Edit your chosen .cql script

Open your chosen .cql script in your favorite text editor.

Step 2: Find the :pgn tag and change it to the exact name of the pgn database you want to search, otherwise cql won't find it. (TIP: if you work with several different pgn files, consider commenting out the :pgn tag with ;; and write a new one below it. That way you can switch between them without retyping them each time.)

Step 3: Check that the file name in the :output tag is what you want it to be. It will create a PGN with this name or overwrite it if it exists already, so it is very important to rename the file it creates before running the script if you want to keep a copy of the previous results.

Step 4: Save your changes and open your command prompt. Once you are in the cql folder, type " cql.exe NameOfYourScriptHere.cql " and hit enter. If there were no errors, CQL will begin searching your chosen PGN database and creating the PGN database with the games that matched your criteria in the script. You can close this window at any time to stop the process early if you need to.

Step 5: Open your result PGN database in your favorite PGN database viewer. Each game will have an annotation at the beginning stating the number this game had in the original database, and depending on the script you used, there will be another annotation with the word MATCH somewhere in the game. Click on the move with that comment and you will see an example of what you were looking.

Step 6: If there are some non-examples in the results, then you will need to clarify the search criteria in your script. When writing a new script, this sometimes takes trial and error.