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 heijden.pgn
     output out.pgn
     gamenumber 100 1000
     variations
     sort matchcount 2 5
    )
other filters

This CQL file will look in heijden.pgn for the games and write its output to out.pgn. It will start examining the 100th game of heijden.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 range
silent	silent	suppress all annotations added by CQL
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
metadata filter	year 2000 2010 player "Kasparyan"	Current game must match the specified metadata filter

output filename

If an output filename parameter is present then the output will be written to that file, which must end in the extension ".pgn". But if a the cql executable was invoked with the --output option, then the output will be written to the filename given by 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, the CQL will write the results to pinmates-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 --input is specified then games will be read from that filename.

silent

Do not print any CQL-generated annotations except for those generated by a comment filter. See silent documentation for more information on this filter.

matchcount range

If all the filters in the body of the CQL form match, then the position 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

Whether a game is output if sort matchcount range parameter is included is the same as if matchcount range were included without the prefatory sort. However, if sort is specified then the output games are sorted in descending order by the value of the matchcount (that is by the number of positions matched in that game.)

variations

If there variations parameter is specified then CQL will search in variations as well as in the mainline. In this case we sometimes say "variations is set." By default, CQL only searches mainline positions.