CQL Parameters

A CQL file begins with the word cql followed by a sequence of CQL parameters enclosed in parentheses. The allowed parameters determine which games CQL matches, whether and how the output is sorted, and where the output will be printed. An example of a complicated set of parameters beginning a CQL file is in this file: 
cql (input hhdbvi.pgn
     output out.pgn
     gamenumber 100 1000
     variations
     sort matchcount 2 5
    )
other filters
This CQL file will look in hhdbvi.pgn for the games and write its output to out.pgn. It will start examining the 100th game of hhdbvi.pgn and will stop after it has examined game 1000 of that file. It will look in the variations. It will only output games with between 2 and 5 matched positions. It will sort the output by the number of positions that match the filters in its body.

The allowed parameters of the CQL file are these:
parameter name example meaning
output filename output foo.pgn specifies the output file where CQL writes results
input filename input mega.pgn specifies the input PGN file from which CQL reads games
matchcount range matchcount 3 1000 number of matched positions must lie in the range
gamenumber range gamenumber 1 10 Only examine games with game number in the range
result result 1-0
result 1/2-1/2
result 0-1		 specify result of game
silent silent suppress all annotations added by CQL including user comments
quiet quiet suppress automatically generated comments except for header comments
sort matchcount range sort matchcount 3 1000 like matchcount range but output is sorted by matchcount
variations variations search in variations as well as in the mainline
matchstring quoted_string matchstring "Turton theme" set the comment output at matched position

output filename

If an output filename parameter is present, then the PGN output will be written to the file filename, which must end in the extension .pgn.

If the cql executable was invoked with the -o (or -output) option, then the output will be written to the filename specified on the command line after that option.

If neither an output parameter nor an output option was specified then the output will be written to the file cqlfilename-out.pgn, where cqlfilename is the name of the CQL file itself without any path prefix or extension.

For example, if the name of the .cql file is pins.cql and if no output file is specified within the CQL script or on the command line, then CQL will write the results to pins-out.pgn.

input filename

If an input filename parameter is present then the games are read from the file filename which must end in the extension .pgn. If the command line option -i (or -input) is specified then games will be read from filename that follows the -i command line option.

The filename can be enclosed in quotation marks, which is sometimes useful if it contains embedded spaces.

matchcount range

If all the filters in the body of the CQL filter match a position, then the body is said to match the position.

Each time its body matches a position, CQL increments the value of an internal variable named matchcount.

When CQL is finished playing through the game, CQL checks the value of matchcount.

Ordinarily, whenever matchcount is greater than 0, then the game itself is said to match the CQL form. When that happens, CQL outputs the game, together with some annotations, to its output file. (Recall that the output file can be specified as a CQL parameter inside the CQL file, or as a command line argument, or if not specified is the name of the input CQL file with -out.pgn appended.).

If the matchcount parameter is specified, however, then the game is output only if the value of the matchcount variable lies within the range argument (which can include 0).

sort matchcount range

sort matchtcount range will select the exact same games as matchcount range, but it will sort these games in descending order of the number of matched positions in the game.

variations

If the variations parameter is specified then CQL will search in variations as well as in the mainline. This includes not only the main search loop of CQL, but also other filters that can traverse the game tree, like move, line, find, and echo.

If the variations parameter is specified, we sometimes say "variations is set." By default, CQL only searches mainline positions.

The variations parameter can be overriden by the -mainline command line option; or it can just be specified on the command line by using -variations.