The persistent filter is used to indicate that a numeric variable, string variable, or set variable is persistent. The persistent filter consists of the word persistent followed by an assignent to a numeric variable:
  persistent x = 3
  persistent y += 1
The variable must not have been used non-persistently prior to the persistent assignment.

The persistent filter indicates that its variable is persistent, which means that:

  • the variable is initialized to 0, the empty string, or the empty set as appropriate;
  • the variable retains its value between games.

The values of all persistent variables are output to standard output after CQL has concluded processing all the games in the input PGN database.

persistent declaration without an assignment is no longer supported

In versions 6.0.2-6.0.5 of CQL, a persistent variable could also be declared without an assignment, e.g.:
  persistent x

As of CQL 6.1, this feature is no longer supported and will signal an error if used.

persistent quiet

If the persistent keyword is immediately followed by the quiet keyword, the end-of-game output is disabled for the applicable variable:
  persistent quiet X=""

This is important if reading in a file with readfile into a persistent string, for example.


Persistent variables are used in the persistent.cql example. That example matches no game, but when run on the HHdbVI endgame study database database, it produces output like this:
NumberGames: 93839
NumberStalemates: 14072
NumberUnderpromotions: 11759
NumberRookPromotions: 2383
NumberBishopPromotions: 1826
NumberKnightPromotions: 7550
NumberQueenPromotions: 46826
NumberPromotions: 58585
NumberEnpassants: 700
NumberCastles: 663
NumberMates: 16044
NumberWins: 59879
NumberWhiteWins: 59879
NumberDraws: 33960
NumberBlackWins: 0
NumberPositions: 1723184

Persistent strings are typically used for holding the contents of files read with readfile, or for more complex sharing of data between games. See also dictionary for this purpose.