tag query filters

The header of a game in PGN format contains a number of tag pairs. Each tag pair has a tag name and a tag value.

The tag value of many of the standard PGN tag names can be queried directly with a CQL filter, as shown in the following table:

tag name	filter name	command-line option	meaning
White	white	-white	white player
Black	black	-black	black player
Date	date	(see -year)	game start date
Event	event	-event	event name
Site	site	-site	site name
ECO	eco		Encyclopedia of Chess Openings code
EventDate	eventdate		event start date

Each of these built-in tag query filters, when used with no arguments, have as value the tag value of their corresponding tag name in the current game. For example, the value of

    event

is the tag value of the "Event" tag in the PGN header.

General tags and custom tags

Use the tag filter for accessing the value of tag names not in the above list.

Use of implicit search arguments with tag query filters

Each of these tag query filters are implicit search filters. This means that each takes a single optional quoted string as argument. The filter is true if this literal string occurs as a substring of the tag value for the corresponding tag name.

Thus

    player white "Kasparov"

is equivalent to the filter

    "Kasparov" in player white

and will match a position exactly when the string "Kasparov" is a substring (or equal to) the tag value of the "White" tag name in the PGN header. That, is, Kasparov is playing White.

Note that regular expression matching is not performed on implicit search arguments.

regular expression matching against tag values

To match a tag value against a regular expression, use ~~:

    player white ~~ "K.*v"
    event ~~ "W.* +Zee"
    player black ~~ "Fi[sch]+er"
    date ~~ "198\d\.10\..."

In more detail,

    player white ~~ "K.*v"

is an ~~ filter whose target is the filter player white and whose pattern is the quoted string "K.*v".

The value of the filter player white will be whatever is in the PGN header of the current game as the tag value of the tag pair whose tag name is "White", which is to say the name of the player playing White.

That value will then be searched for the regular expression "K.*v" which represents strings starting with a "K", following by 0 or more characters, and ending with a "v". If such a string is found in the the "White" tag value, then the filter will match; otherise it will not.

date and eventdate

The format of the tag value for the tag name "Date" or "EventDate" is:

    yyyy.mm.dd

where each of y, m and d are either digits or question marks and denote the year, month and day respectively. For example, the following are valid dates:

    1943.??.??
    2019.10.01

To get the year, month or day fields when present, use regular expressions:

    date ~~ "(\d{4})\.(\d{2})\.(\d{2})"
    Year = int \1 // same as year
    Month = int \2
    Day = int \3

CQL has a built in filter for year, that is Year in the example above.

The eventdate filter has the same syntax as date but retrieves the tag value of the EventDate tag:

    X=eventdate
    eventdate ~~ "19[6-9][0-9]"

Because of the structure of the Date field, one can sort games chronologically simply by sorting lexicographically on the date:

    sort "Date" date

This is using ordinary sort of a string value.

player, player white and player black

As shown in table of tag query filters, the value of player white is the tag value for the "White" tag name.

Likewise, value of player black in a given game is the value of the "Black" tag pair. When player is not followed by white, black, or a quoted string, its value is the concatenation of the values of player white, a newline, and player black:

      player
      ≡
      player white + \n + player black

Like player white and player black, the player filter is an implicit search filter: when followed by a quoted string, the filter is true when the quoted string is a literal substring of the value of the player filter:

      player "Kasparov"
      ≡
      player white "Kasparov" or player black "Kasparov"
      ≡
      "Kasparov" in player

flipcolor with player white and player black

As illustrated in the gameinfo.cql, the player filter works with flipcolor and can be used to find wins by a player:

  flipcolor
  {player white "Ivanchuk"
   result 1-0}

will find games that Ivanchuk wins (because flipcolor transforms both the player and the result, as they are both enclosed in a {...}.

command line options with tag query filters

Some of the tag query filters have a corresponding command line option, as listed in table of tag query filters. These options each interpret the command line argument following that option as an implicit search argument:

    cql -event Wijk -player Kasparov foo.cql
    cql -white Reti r.cql
    cql -white Fischer -black Spassky -year 1972 wc.cql

Of course, you can always use the general -cql command line argument to carry out such searches, but you might have to escape the quotes from your shell:

    cql -cql 'white~~ "Bog.*ov" ' in.cql

This escaping of the double quotes with single quotes should work on typical Mac and Unix shells, and Windows PowerShell, but not the DOS shell.