Additions:
This tutorial assumes some familiarity with CQL, although most of the text can be understood without previous CQL experience. For an introduction to Composite seach the Chess Assistant manual and the built-in help are recommended. Additional information about searching with Composite search is available on the CQLCompositeSearch page.
Chess Assistant comes with a large collection of pre-built queries that can be useful on their own or serve as examples and building blocks when you start writing your own queries. The pre-built queries are organized into nine sections, and each section contains several queries. This serves as a good example of how a large collection of queries can be organized into a hierarchical structure in Chess Assistant. New sections can be added and each one can hold any number og queries.
~~(position
~~:mate)
If you have written or collected CQL queries that you keep in textfiles you should use Chess Assistant's capability to import and categorize such queries. The procedure is almost the same as when adding a new query by the method described above. First you create a section for a collection of related queries, or use an existing section. Then you continue as described when adding a new query to a section. Only this time, instead of typing the query into the //CQL query// textbox, you import the textfile containing the query.
Deletions:
This tutorial assumes some familiarity with CQL, although most of the text can be understood without previous CQL experience. For an introduction to Composite seach the Chess Assistant manual and the built-in help are recommended. Additional information about Composite search is available on the CQLCompositeSearch page.
As you can see Chess Assistant comes with a large collection of pre-built queries that can be useful on their own or serve as examples and building blocks when you start writing your own queries. The pre-built queries are organized into nine sections, and each section contains several queries. This serves as a good example of how a large collection of queries can be organized into a hierarchical structure. An unlimited number of new sections can be added and each one can hold any number og queries.
~ (position :mate)
If you have written or collected CQL queries that you keep in textfiles you should use Chess Assistant's capability to import and categorize such queries. The procedure is the same as described above. First you create a section for a collection of related queries, or use an existing section. Then you continue as described when adding a new query to a section. Only this time, instead of typing the query into the //CQL query// textbox, you import the textfile containing the query.
Additions:
Before Chess Assistant 8 came on the scene, CQL users had to convert all the databases they wanted to search to PGN format. Regular users would have several such databases. Each query was stored in a textfile and bound to a specific database. So in order to apply the same query to several different databases it was necessary to make a copy of the textfile for each one and then modify them to refer to the correct database. In order to indicate what each query does, and which database it searches, one could try to encode that information in the filename. Unfortunately, six months later it was completely forgotten what that filename means. These problems were further compounded by the fact that one would probably have to generate several temporary PGN files in order to speed up complex searches. Of course each CQL textfile could be opened to examine the query itself and any comments that might be there, but that is not the fastest way to find that query you wrote many months ago. Other ways to search through a collection of CQL files can be suggested, but there is no getting away from the fact that this is a primitive way to keep track of your queries.
This is all changed with Chess Assistant 8.1. Chess Assistant allows you to organize your whole collection of queries into a neat structure, so you can quickly find any query you may be looking for. Each query is identified by a description and you can even attach an illustrative chessboard diagram, which greatly facilitates the usage of this feature.
This tutorial assumes some familiarity with CQL, although most of the text can be understood without previous CQL experience. For an introduction to Composite seach the Chess Assistant manual and the built-in help are recommended. Additional information about Composite search is available on the CQLCompositeSearch page.
With Chess Assistant CQL queries can be quickly organized, much like a large pile of books would be classifed and then put into the shelves of a library where they can easily be found again.
Deletions:
Before Chess Assistant 8 came on the scene, CQL users had to convert all the databases they wanted to search to PGN format. Regular users would have several such databases. Each query was stored in a textfile and bound to a specific database. So in order to apply the same query to several different databases it was necessary to make a copy of the textfile for each one and then modify them to refer to the correct database. In order to indicate what each query does, and which database it searches, you could try to encode that information in the filename. Unfortunately, six months later you will have no idea what that filename means. These problems were further compounded by the fact that you would probably have to generate several temporary PGN files in order to speed up complex searches. Of course you could open each CQL textfile and have a look at the contents and any comments you might have put in there, but that is not the fastest way to find that query you wrote many months ago. Other ways to search through a collection of CQL files can be suggested, but there is no getting away from the fact that this is a primitive way to keep track of your queries.
With Chess Assistant you can quickly organize all your CQL queries, much like a large pile of books would be classifed and then put into the shelves of a library where they can easily be found again.
Additions:
It should be mentioned that an EPD string can be pasted into the diagram by pressing #% Shift #% + #% Ins #%. When the position has been set up press #% OK #% to save the position as the new illustrative position for the CQL query. After that this position will be displayed whenever the query is selected in the //Condition// dialog.
Deletions:
It should be mentioned that an EPD string can be pasted into the diagram by pressing #% Shift #% + #% Ins #%. When the position has been set up press #% OK #% to save the position as the new illustrative position for the CQL query.
Additions:
Illustrative diagrams should always be added to Composite search queries. To add a diagram highlight the query in the //Condition// dialog and then press #% New example #% below the diagram on the right side of the dialog. This brings up the //Position operations// dialog which is the normal dialog in Chess Assistant for setting up positions.
It should be mentioned that an EPD string can be pasted into the diagram by pressing #% Shift #% + #% Ins #%. When the position has been set up press #% OK #% to save the position as the new illustrative position for the CQL query.
Deletions:
Illustrative diagrams should always be added to Composite search queries. To add a diagram highlight the query in the //Condition// dialog and then press #% New example #% below the diagram on the right side of the dialog.
Additions:
====Illustrative diagrams====
Illustrative diagrams should always be added to Composite search queries. To add a diagram highlight the query in the //Condition// dialog and then press #% New example #% below the diagram on the right side of the dialog.
{{image class="center" alt="New illustrative diagram" title="New illustrative diagram" url="images/CQL-NewDiagram.gif"}}
Deletions:
====Advanced topics====
This section is strictly for advanced users who have a good understanding of both XML and CQL.
Additions:
Before Chess Assistant 8 came on the scene, CQL users had to convert all the databases they wanted to search to PGN format. Regular users would have several such databases. Each query was stored in a textfile and bound to a specific database. So in order to apply the same query to several different databases it was necessary to make a copy of the textfile for each one and then modify them to refer to the correct database. In order to indicate what each query does, and which database it searches, you could try to encode that information in the filename. Unfortunately, six months later you will have no idea what that filename means. These problems were further compounded by the fact that you would probably have to generate several temporary PGN files in order to speed up complex searches. Of course you could open each CQL textfile and have a look at the contents and any comments you might have put in there, but that is not the fastest way to find that query you wrote many months ago. Other ways to search through a collection of CQL files can be suggested, but there is no getting away from the fact that this is a primitive way to keep track of your queries.
With Chess Assistant you can quickly organize all your CQL queries, much like a large pile of books would be classifed and then put into the shelves of a library where they can easily be found again.
In order to get started select //Composite search// from the //Search// menu to display the //Condition// dialog.
As you can see Chess Assistant comes with a large collection of pre-built queries that can be useful on their own or serve as examples and building blocks when you start writing your own queries. The pre-built queries are organized into nine sections, and each section contains several queries. This serves as a good example of how a large collection of queries can be organized into a hierarchical structure. An unlimited number of new sections can be added and each one can hold any number og queries.
The new section that we created will hold our CQL queries that find different types of checkmate. Chess Assistant doesn't just store a CQL query by itself. It stores it with some useful information, such as a description, example diagram, region definition etc. Let's start by adding a simple search for a checkmate without any additional conditions. Right-click on the new "Checkmate" section in the //Condition// dialog and select //Add characteristic// from the shortcut menu. The //Characteristic info// dialog will be displayed. Enter a description in the //Name for white// text box (e.g. Checkmate) and type the query into the //CQL query// textbox. It already contains the default text, ##(match)## which is the starting point for a new query. Modify it so it looks like this:
Click on #% OK #% and the new query will be added to the section. The //Condition// dialog will be displayed again. You can continue adding more queries using the same procedure.
When you are done adding queries you have two options. Select a query that you want to run on the current dataset and click #% OK #%, or if you just wanted to add queries without running any of them, click on #% Cancel #%. In both cases you will get a warning saying //Characteristic info is modified. Save changes?// Of course you must click on #% Yes #% if you want to save your work.
If you have written or collected CQL queries that you keep in textfiles you should use Chess Assistant's capability to import and categorize such queries. The procedure is the same as described above. First you create a section for a collection of related queries, or use an existing section. Then you continue as described when adding a new query to a section. Only this time, instead of typing the query into the //CQL query// textbox, you import the textfile containing the query.
Let's say that we want to add another query to the //Checkmate// section. This time the query finds smothered mate and we type //Smothered mate on the edge or in the center of the board// in the //Name for white// text box. Next we have to import the file. Note the two icons on the top right above the //CQL query// text box.
The left one is for importing a CQL file, so that's the one we are interested in. When you push it the //Load CQL file// dialog opens, which is nothing but the familiar file open dialog with the file type preset to CQL files. Find the CQL file you want to import and click on #% Open #%. The CQL file is then imported into the //CQL query// textbox which will look something like this:
As mentioned before each CQL query is bound to a specific PGN database. In this case the query we imported was designed to search ##heijden.pgn##. What we haven't mentioned is that the query also must specify where the output of the search should be stored. That's another PGN file and in this case it's ##out.pgn##. Chess Assistant offers much more flexibility and these restrictions should simply be removed when importing old CQL files into Chess Assistant. So, the following lines should be deleted from the imported CQL script:
Deletions:
CQL is an extremely powerful query language for searching chess databases. All the different types of searches that are possible with modern chess database systems can be done with CQL. That is, however, just a starting point for CQL which offers so much more power and types of searches that previously were impossible.
Chess Assistant, starting with version 8, offers all the power of CQL in an integrated environment. This implementation brings several advantages, including:
~1) CQL queries can be run on any type of database that Chess Assistant can handle, instead of only PGN databases.
~1) CQL queries are not bound to a specific database. Define the query once and then apply it to any selection of games (dataset) from any database.
~1) The result of a CQL query is displayed as a list of all the matching games with markers showing the exact position(s) that matched the query. Browsing through the resulting list of games will automatically display the first matching position in each game.
~1) When examining the matching positions a diagram with automatically generated graphical annotations highlights the features that match the query.
~1) Chess Assistant allows you to organize your whole collection of queries into a neat structure, so you can quickly find any query you may be looking for. Each query is identified by a description and you can even attach an example chessboard diagram, which greatly facilitates the usage of this feature.
Although each of these points warrants a much more detailed description, only the last one will be explored further here. This will not teach you how to write CQL queries, and some familiarity with CQL is assumed, although most of the following text can be understood without previous CQL experience.
====Where is my query?====
Before Chess Assistant 8 came on the scene, CQL users had to convert all the databases they wanted to search to PGN format. Regular users would have several such databases. Each query in the original, standalone CQL is stored in a textfile and bound to a specific database. So if you wanted to apply the same query to several different databases you would have to make a copy of the textfile for each one and then modify them to refer to the correct database. In order to indicate what each query does, and which database it searches, you could try to encode that information in the filename. Unfortunately, six months later you will have no idea what that filename means.
These problems were further compounded by the fact that you would probably have to generate several temporary PGN files in order to speed up complex searches. Of course you could open each CQL textfile and have a look at the contents and any comments you might have put in there, but that is not the fastest way to find that query you wrote many months ago. Other ways to search through a collection of CQL files can be suggested, but there is no getting away from the fact that this is a primitive way to keep track of your queries.
With Chess Assistant you can quickly organize all your CQL queries, much like a large pile of books would be classifed and then put into the shelves of a library where they can easily be found again. In order to get started select //Composite search// from the //Search// menu to display the //Condition// dialog. Note that unlike other types of searches in Chess Assistant a dataset must be selected before Composite search or CQL search can be performed.
As you can see Chess Assistant comes with a large collection of pre-built queries that can be useful on their own or serve as examples and building blocks when you start writing your own queries. The pre-built queries are organized into nine sections, and each section contains several queries.
In the dialog above a query has been highlighted. This is query number 15 in section 2, King's position. It's index is therfore 2.15 and the description of the query is "King has one move". The diagram illustrates that situation. The white king, the object of this query, is marked with a red rectange. All squares around it, except one, are attacked by enemy pieces. Those squares are marked with a green X. The only square that the king can move to is c1 and that square is marked with a green rectangle. Obviously, a diagram like this is very helpful when searching for queries and understanding their purpose.
When defining a new query an example position can be set up by pushing #% New example #%.
The //Side// drop-down list allows you to define which side the selected condition refers to. It will be explained in more detail later.
CQL queries in Chess Assistant can also accept a parameter for certain material conditions in the query. It is controlled by the //Quantity// spin boxes (from and to).
When #% Region #% is pushed the diagram displays the region of the board that applies to the query. This advanced feature was primarily introduced for use in the pre-built queries that come with Chess Assistant. Region definition is not a standard CQL feature and cannot be used in user-defined queries (although advanced users can get around that limitation).
When a characteristic has a region definition it can be used to limit the location of some or all the pieces, but the precise meaning of a region depends the query. The following diagram shows a region that is composed of the e-h files. This could, for instance, be used to limit the location of the white king to that region of the board.
{{image class="center" alt="Composite Search Region" title="Composite Search Region" url="images/CQL-Region.jpg"}}
The region can be altered by clicking (include) and right-clicking (exclude) on a square:
~Click: The square
~#% Shift #% + Click: The file
~#% Ctrl #% + Click: The rank
~#% Alt #% + Click: The diagonal parallel to the main diagonal (a1-h8)
~#% Alt #% + #% Shift #% + Click: The diagonal parallel to the a8-h1 diagonal
~#% Ctrl #% + #% Shift #% + Click: All squares that a rook could move to on an empty board.
~#% Ctrl #% + #% Alt #% + #% Shift #% + Click: Both diagonals
The new section that we created will hold our CQL queries that find different types of checkmate. Chess Assistant doesn't just store a CQL query by itself. It stores it with some useful information, such as a description, example diagram, region definition etc. Such a package is called a //characteristic// in Chess Assistant. So we want to add a characteristic to the section we just created. Let's start by adding a simple search for a checkmate without any additional conditions. Right-click on the new section in the //Condition// dialog and select //Add characteristic// from the shortcut menu. The //Characteristic info// dialog will be displayed. Enter a description in the //Name for white// text box (e.g. Checkmate) and type the query into the //CQL query// textbox. It already contains the default text, ##(match)## which is the starting point for a new query. Modify it so it looks like this:
Click on #% OK #% and this new characteristic will be added to the section. The //Condition// dialog will be displayed again. You can continue adding more characteristics using the same procedure.
When you are done adding characteristics you have two options. Select a characteristic containing a query that you want to run on the current dataset and click #% OK #%, or if you just want to add characteristics without running a query, click on #% Cancel #%. In both cases you will get a warning saying //Characteristic info is modified. Save changes?// Of course you must click on #% Yes #% if you want to save your work.
If you have written or collected CQL queries that you keep in textfiles you should use Chess Assistant's capability to import and categorize such queries. The procedure is the same as described above. First you create a section for a collection of related queries, or use an existing section. Then you continue as described when adding a new query to a section. Only this time, instead of typing the query into the //CQL query// textbox, you import the textfile containing the query. Let's say that we want to add another query to the //Checkmate// section. This time the query finds smothered mate and we type //Smothered mate on the edge or in the center of the board// in the //Name for white// text box. Next we have to import the file. Note the two icons on the top right above the //CQL query// text box.
The left one is for importing a CQL file, so that's the one we are interested in. When you push it the //Load CQL file// dialog opens, which is nothing but the familiar file open dialog with the file type preset to CQL files. Find the file you want to import and click on #% Open #%. The CQL file is then imported into the //CQL query// textbox which will look something like this:
As mentioned before each CQL query is bound to a specific PGN database. In this case the query we imported was designed to search ##heijden.pgn##. What we haven't mentioned is that the query also must specify where the output of the search should be stored. That's another PGN file and in this case it's ##out.pgn##. Chess Assistant offers much more flexibility (as mentioned before!) and these restrictions should simply be removed when importing old CQL files into Chess Assistant. So, the following lines should be deleted from the imported CQL script:
Those who are familiar with CQL will note that the smothered mate query only looks for positions where black is checkmated:
##:mate :btm##
Here ##:mate## tells CQL to look for a checkmate position and ##:btm## adds that it must be black's turn to move. What if we wanted instead to look for positions where white has been checkmated? In the past, before Chess Assistant 8, the only way to handle that situation was to modify the query, change ##:btm## to ##:wtm## and a few more changes would be needed to make the query work correctly. Then the query would be saved and run again. And if you wanted to find smothered mate regardless of which side won a third version of the query would be needed. Here, once more, Chess Assistant helps to reduce the multiplicity of essentially the same query. Instead of three different queries only one is needed, and we can use the query we have already entered without any changes. The trick is to use the //Side// drop-down list box to instruct Chess Assistant to switch colors or to run the query for both black and white:
~//White//: Run the query "as is"
~//Black//: Switch colors
~//Any//: This option combines //White// and //Black// and the search is performed for both sides.
Note that the //Quantity// fields offer users another way to reduce the number of queries needed to accomplish certain related searches.
Additions:
~1) CQL queries are not bound to a specific database. Define the query once and then apply it to any selection of games (dataset) from any database.
~1) The result of a CQL query is displayed as a list of all the matching games with markers showing the exact position(s) that matched the query. Browsing through the resulting list of games will automatically display the first matching position in each game.
~1) When examining the matching positions a diagram with automatically generated graphical annotations highlights the features that match the query.
Before Chess Assistant 8 came on the scene, CQL users had to convert all the databases they wanted to search to PGN format. Regular users would have several such databases. Each query in the original, standalone CQL is stored in a textfile and bound to a specific database. So if you wanted to apply the same query to several different databases you would have to make a copy of the textfile for each one and then modify them to refer to the correct database. In order to indicate what each query does, and which database it searches, you could try to encode that information in the filename. Unfortunately, six months later you will have no idea what that filename means.
With Chess Assistant you can quickly organize all your CQL queries, much like a large pile of books would be classifed and then put into the shelves of a library where they can easily be found again. In order to get started select //Composite search// from the //Search// menu to display the //Condition// dialog. Note that unlike other types of searches in Chess Assistant a dataset must be selected before Composite search or CQL search can be performed.
The new section that we created will hold our CQL queries that find different types of checkmate. Chess Assistant doesn't just store a CQL query by itself. It stores it with some useful information, such as a description, example diagram, region definition etc. Such a package is called a //characteristic// in Chess Assistant. So we want to add a characteristic to the section we just created. Let's start by adding a simple search for a checkmate without any additional conditions. Right-click on the new section in the //Condition// dialog and select //Add characteristic// from the shortcut menu. The //Characteristic info// dialog will be displayed. Enter a description in the //Name for white// text box (e.g. Checkmate) and type the query into the //CQL query// textbox. It already contains the default text, ##(match)## which is the starting point for a new query. Modify it so it looks like this:
~ (position :mate)
Click on #% OK #% and this new characteristic will be added to the section. The //Condition// dialog will be displayed again. You can continue adding more characteristics using the same procedure.
When you are done adding characteristics you have two options. Select a characteristic containing a query that you want to run on the current dataset and click #% OK #%, or if you just want to add characteristics without running a query, click on #% Cancel #%. In both cases you will get a warning saying //Characteristic info is modified. Save changes?// Of course you must click on #% Yes #% if you want to save your work.
If you have written or collected CQL queries that you keep in textfiles you should use Chess Assistant's capability to import and categorize such queries. The procedure is the same as described above. First you create a section for a collection of related queries, or use an existing section. Then you continue as described when adding a new query to a section. Only this time, instead of typing the query into the //CQL query// textbox, you import the textfile containing the query. Let's say that we want to add another query to the //Checkmate// section. This time the query finds smothered mate and we type //Smothered mate on the edge or in the center of the board// in the //Name for white// text box. Next we have to import the file. Note the two icons on the top right above the //CQL query// text box.
As mentioned before each CQL query is bound to a specific PGN database. In this case the query we imported was designed to search ##heijden.pgn##. What we haven't mentioned is that the query also must specify where the output of the search should be stored. That's another PGN file and in this case it's ##out.pgn##. Chess Assistant offers much more flexibility (as mentioned before!) and these restrictions should simply be removed when importing old CQL files into Chess Assistant. So, the following lines should be deleted from the imported CQL script:
Here ##:mate## tells CQL to look for a checkmate position and ##:btm## adds that it must be black's turn to move. What if we wanted instead to look for positions where white has been checkmated? In the past, before Chess Assistant 8, the only way to handle that situation was to modify the query, change ##:btm## to ##:wtm## and a few more changes would be needed to make the query work correctly. Then the query would be saved and run again. And if you wanted to find smothered mate regardless of which side won a third version of the query would be needed. Here, once more, Chess Assistant helps to reduce the multiplicity of essentially the same query. Instead of three different queries only one is needed, and we can use the query we have already entered without any changes. The trick is to use the //Side// drop-down list box to instruct Chess Assistant to switch colors or to run the query for both black and white:
This section is strictly for advanced users who have a good understanding of both XML and CQL.
Deletions:
~1) CQL queries are not bound to a specific database. Define the query once and then apply it to any open database or a selection of games (dataset) from a database.
~1) Malformed PGN files may cause the standalone CQL to crash. After years of parsing PGN files in all shapes and sizes it is very unlikely that an error in a PGN file would slip through Chess Assistant's parsing routines.
~1) The result of a CQL query is displayed as a list of all the matching games with markers showing the exact position(s) that matched the query.
~1) Browsing through the resulting list of games will automatically display the first matching position in each game.
~1) When examining the matching positions a diagram with automatically generated graphical annotations highlights the features of the position that match the query.
Before Chess Assistant 8 came on the scene, CQL users had to convert all the databases they wanted to search to PGN format. Regular users would have several such databases. Each query in the original, standalone CQL is stored in a textfile and bound to a specific database. So if you wanted to apply the same query to several different databases you would have to make a copy of the textfile for each one and then modify them to refer to the correct database. In order to indicate what each query does, and which database it searches, you would try to encode that information in the filename. Unfortunately, six months later you will have no idea what that filename means.
With Chess Assistant you can quickly organize all your CQL queries, much like a large pile of books would be classifed and then put into the shelves of a library where they can easily be found again. In order to get started select //Composite search// from the //Search// menu. Note that unlike other types of searches in Chess Assistant a dataset must be selected before Composite search or CQL search can be performed.
The new section that we created will hold our CQL queries that find different types of checkmate. Chess Assistant doesn't just store the CQL queries, it packs it in with some useful information, such as a description, example diagram, region definition etc. Such a package is called a //characteristic// in Chess Assistant. So we want to add a characteristic to the section we just created. Let's start by adding a simple search for a checkmate without any additional conditions. Right-click on the new section in the //Condition// dialog and select //Add characteristic// from the shortcut menu. The //Characteristic info// dialog will be displayed. Enter a description in the //Name for white// text box (e.d. Checkmate) and type the query into the //CQL query// textbox. It already contains the default text, ##(match)## which is the starting point for a new query. Modify it so it looks like this:
~ (position
~ :mate)
Click on #% OK #% and this new query will be added to the section. The //Condition// dialog will be displayed again. You can continue adding more characteristics using the same procedure.
When you are done adding characteristics you have two options. Select a query that you want to run on the current dataset and click #% OK #%, or if you just want to add characteristics without running any of them, click on #% Cancel #%.
In both cases you will get a warning saying //Characteristic info is modified. Save changes?// Of course you must click on #% Yes #% if you want to save your work.
If you have written or collected CQL queries that you keep in textfiles you should use Chess Assistant's capability to import and categorize such queries. The procedure is the same as described above. First you create a section for a collection of related queries, or use an existing section. Then you continue as described when adding a new query to a section. Only this time, instead of typing the query into the //CQL query// textbox, you import the textfile where you keep your query. Let's say that we want to add another query to the //Checkmate// section. This time the query finds smothered mate and we type //Smothered mate on the edge or in the center of the board// in the //Name for white// text box. Next we have to import the file. Note the two icons on the top right above the //CQL query// text box.
As mentioned before each CQL query is bound to a specific PGN database. In this case the query we imported was designed to search ##heijden.pgn##. What we haven't mentioned mentioned is that the query also must specify where the output of the search should be stored. That's another PGN file and in this case it's ##out.pgn##. Chess Assistant offers much more flexibility (as mentioned before!) and these restrictions should simply be removed when importing old CQL files into Chess Assistant. So, the following lines should be deleted from the imported CQL script:
Here ##:mate## tells CQL to look for a checkmate position and ##:btm## adds that it must be black's turn to move. What if we wanted instead to look for positions where white has been checkmated? In the past, before Chess Assistant 8, the only way to handle that situation would be to modify the query, change ##:btm## to ##:wtm## and a few more changes would be needed to make the query work correctly. Then the query would be saved and run again. And if you wanted to find smothered mate regardless of which side won a third version of the query would be needed. Here, once more, Chess Assistant helps to reduce the multiplicity of essentially the same query. Instead of three different queries only one is needed, and we can use the query we have already entered without any changes. The trick is to use the //Side// drop-down list box to instruct Chess Assistant to switch colors or to run the query for both black and white:
Additions:
With Chess Assistant you can quickly organize all your CQL queries, much like a large pile of books would be classifed and then put into the shelves of a library where they can easily be found again. In order to get started select //Composite search// from the //Search// menu. Note that unlike other types of searches in Chess Assistant a dataset must be selected before Composite search or CQL search can be performed.
When #% Region #% is pushed the diagram displays the region of the board that applies to the query. This advanced feature was primarily introduced for use in the pre-built queries that come with Chess Assistant. Region definition is not a standard CQL feature and cannot be used in user-defined queries (although advanced users can get around that limitation).
When a characteristic has a region definition it can be used to limit the location of some or all the pieces, but the precise meaning of a region depends the query. The following diagram shows a region that is composed of the e-h files. This could, for instance, be used to limit the location of the white king to that region of the board.
Click on #% OK #% and this new query will be added to the section. The //Condition// dialog will be displayed again. You can continue adding more characteristics using the same procedure.
When you are done adding characteristics you have two options. Select a query that you want to run on the current dataset and click #% OK #%, or if you just want to add characteristics without running any of them, click on #% Cancel #%.
In both cases you will get a warning saying //Characteristic info is modified. Save changes?// Of course you must click on #% Yes #% if you want to save your work.
====Importing existing CQL queries====
====Advanced topics====
Deletions:
With Chess Assistant you can quickly organize all your CQL queries, much like a large pile of books would be classifed and then put into the shelves of a library where they can easily be found again.
In order to get started select //Composite search// from the //Search// menu.
When #% Region #% is pushed the diagram displays the region of the board that applies to the query. The region can be used to limit the location of some or all the pieces that are defined in the query. The following diagram shows a region that is composed of the e-h files. This could, for instance, be used to limit the location of the white king to that region of the board.
Click on #% OK #% and this new query will be added to the section. The //Condition// dialog will be displayed again and when you click on #% OK #% you will get a warning saying //Characteristic info is modified. Save changes?//. Of course you must click on #% Yes #% if you want to save your work. When you have done that the search will be performed on the current dataset.
====Categorizing existing CQL queries====
Additions:
~1) The result of a CQL query is displayed as a list of all the matching games with markers showing the exact position(s) that matched the query.
These problems were further compounded by the fact that you would probably have to generate several temporary PGN files in order to speed up complex searches. Of course you could open each CQL textfile and have a look at the contents and any comments you might have put in there, but that is not the fastest way to find that query you wrote many months ago. Other ways to search through a collection of CQL files can be suggested, but there is no getting away from the fact that this is a primitive way to keep track of your queries.
In order to get started select //Composite search// from the //Search// menu.
As you can see Chess Assistant comes with a large collection of pre-built queries that can be useful on their own or serve as examples and building blocks when you start writing your own queries. The pre-built queries are organized into nine sections, and each section contains several queries.
In the dialog above a query has been highlighted. This is query number 15 in section 2, King's position. It's index is therfore 2.15 and the description of the query is "King has one move". The diagram illustrates that situation. The white king, the object of this query, is marked with a red rectange. All squares around it, except one, are attacked by enemy pieces. Those squares are marked with a green X. The only square that the king can move to is c1 and that square is marked with a green rectangle. Obviously, a diagram like this is very helpful when searching for queries and understanding their purpose.
The //Side// drop-down list allows you to define which side the selected condition refers to. It will be explained in more detail later.
CQL queries in Chess Assistant can also accept a parameter for certain material conditions in the query. It is controlled by the //Quantity// spin boxes (from and to).
Click on #% OK #% and this new query will be added to the section. The //Condition// dialog will be displayed again and when you click on #% OK #% you will get a warning saying //Characteristic info is modified. Save changes?//. Of course you must click on #% Yes #% if you want to save your work. When you have done that the search will be performed on the current dataset.
If you have written or collected CQL queries that you keep in textfiles you should use Chess Assistant's capability to import and categorize such queries. The procedure is the same as described above. First you create a section for a collection of related queries, or use an existing section. Then you continue as described when adding a new query to a section. Only this time, instead of typing the query into the //CQL query// textbox, you import the textfile where you keep your query. Let's say that we want to add another query to the //Checkmate// section. This time the query finds smothered mate and we type //Smothered mate on the edge or in the center of the board// in the //Name for white// text box. Next we have to import the file. Note the two icons on the top right above the //CQL query// text box.
The left one is for importing a CQL file, so that's the one we are interested in. When you push it the //Load CQL file// dialog opens, which is nothing but the familiar file open dialog with the file type preset to CQL files. Find the file you want to import and click on #% Open #%. The CQL file is then imported into the //CQL query// textbox which will look something like this:
As mentioned before each CQL query is bound to a specific PGN database. In this case the query we imported was designed to search ##heijden.pgn##. What we haven't mentioned mentioned is that the query also must specify where the output of the search should be stored. That's another PGN file and in this case it's ##out.pgn##. Chess Assistant offers much more flexibility (as mentioned before!) and these restrictions should simply be removed when importing old CQL files into Chess Assistant. So, the following lines should be deleted from the imported CQL script:
Here ##:mate## tells CQL to look for a checkmate position and ##:btm## adds that it must be black's turn to move. What if we wanted instead to look for positions where white has been checkmated? In the past, before Chess Assistant 8, the only way to handle that situation would be to modify the query, change ##:btm## to ##:wtm## and a few more changes would be needed to make the query work correctly. Then the query would be saved and run again. And if you wanted to find smothered mate regardless of which side won a third version of the query would be needed. Here, once more, Chess Assistant helps to reduce the multiplicity of essentially the same query. Instead of three different queries only one is needed, and we can use the query we have already entered without any changes. The trick is to use the //Side// drop-down list box to instruct Chess Assistant to switch colors or to run the query for both black and white:
Note that the //Quantity// fields offer users another way to reduce the number of queries needed to accomplish certain related searches.
Chess Assistant offers CQL users an excellent way to organize their queries, the flexibility to apply the same query to any database or dataset, and finally reduces the number of queries needed to perform related tasks. Besides what has been described above, there are other powerful options that CQL users should explore in Chess Assistant, including the //Compound characteristic// that can be accessed through the shortcut menu in the //Condition// dialog.
Deletions:
~1) The result of the CQL query is displayed as a list of all the matching games with markers displaying the exact position(s) that matched the query.
These problems were further compounded by the fact that you would probably have to generate several temporary PGN files in order to speed up complex searches. Of course you could simply open each CQL textfile and have a look at the contents and any comments you might have put in there, but that is not the fastest way to find that query you wrote many months ago. Other ways to search through a collection of CQL files can be suggested, but there is no getting away from the fact that this is a primitive way to keep track of your queries.
In order to get started select "Composite search" from the "Search" menu.
As you can see Chess Assistant comes with a large collection of pre-built queries that can be useful on their own or serve as examples and building blocks when you start writing your own queries. The pre-built queries are organized into nine sectionhttp://www.hornid.com/Wikka/3rdparty/plugins/wikiedit/images/h2.gif
Heading 2s, and each section contains several queries.
In the dialog above a query has been highlighted. This is query number 15 in section 2, King's position. It's index is therfore 2.15 and the description of the query is "King has one move". The diagram illustrates that situation. The white king, the object of this query, is marked with a red rectange. All squares around it, except one, are attacked by enemy pieces. Those squares are marked with a green X. The only square that the king can move to is c1 and that square is marked with a green rectangle.
The Side drop-down list allows you to define which side the selected condition refers to.
CQL queries in Chess Assistant can also accept a parameter for certain material conditions in the query. It is controlled by the Quantity spinner boxes (from and to).
Click on #% OK #% and this new query will be added to the section. The //Condition// dialog will be displayed again and when you click on #% OK #% you will get a warning saying //Characteristic info is modified. Save changes?//. Of cours you must click on #% Yes #% if you want to save your work. When you have done that the search will be performed on the current dataset.
If you have written or collected CQL queries that you keep in textfiles you should use Chess Assistant's capability to import and categorize such queries. The procedure is the same as described above. First you create a section for a collection of related queries, or use an existing section. Then you continue as described when adding a new query to a section. Only this time, instead of typing the query into the //CQL query// textbox, you import the textfile where you keep your query. Let's say that we want to add another query to the //Checkmate// section. This time the query finds smothered mate and we type //Smothered mate on the edge or in the center of the board// in the //Name for white// text box. Next we import the file. Note the two icons on the top right above the //CQL query// text box.
The left one is for importing a CQL file, so that's the one we are interested in. When you push it the //Load CQL file// dialog opens, which is nothing but the familiar file open dialog with the file type preset to CQL files. Find the file you want to import and click on #% Open #%. The CQL file is then imported into the //CQL query// textbox which will then look something like this:
As mentioned before each CQL query is bound to a specific PGN database. In this case the query we imported was designed to search ##heijden.pgn##. What we haven't mentioned mentioned is that the query also must specify where the output of the search should be stored. That's another PGN file and in this case it's ##out.pgn##. Chess Assistant offers much more flexibility (as mentioned before!) and these restrictions should simply be removed when imorting old CQL files into Chess Assistant. So, the following lines should be deleted from the imported CQL script:
Here ##:mate## tells CQL to look for a checkmate position and ##:btm## adds that it must be black's turn to move. What if we wanted instead to look for positions where white has been checkmated? In the past, before Chess Assistant 8, the only way to handle that situation would be to modify the query, change ##:btm## to ##:wtm## and a few more changes would be needed to make the query work correctly. Then the query would be saved and run again. And if you wanted to find smothered mate regardless of which side won a third version of the query would be needed. Here, once more, Chess Assistant helps to reduce the multiplicity of essentially the same query. Instead of three different queries only one is needed, and we can use the query we have already entered without any changes. The trick is to use the //Side// drop-down box to instruct Chess Assistant to switch colors or to run the query for both black and white:
Note that the //Quantity// fields offer users another way to reduce the number of queries needed to accomplish certain tasks.
Chess Assistant offers CQL users an excellent way to organize their queries, flexibility in applying the same query to any database or dataset, and finally reduces the number of queries needed to perform related tasks. Besides what has been described above, there are other powerful options that CQL users should explore in Chess Assistant, including the //Compound characteristic// that can be accessed through the shortcut menu in the //Condition// dialog.
Additions:
Note that the //Quantity// fields offer users another way to reduce the number of queries needed to accomplish certain tasks.
====Conclusion====
Chess Assistant offers CQL users an excellent way to organize their queries, flexibility in applying the same query to any database or dataset, and finally reduces the number of queries needed to perform related tasks. Besides what has been described above, there are other powerful options that CQL users should explore in Chess Assistant, including the //Compound characteristic// that can be accessed through the shortcut menu in the //Condition// dialog.
CQL is a wonderful tool on its own, but Chess Assistant adds the query organization tools and convenience that all long term users of CQL will appreciate.
Deletions:
Those who are familiar with CQL will note that the CQL query
Additions:
Those who are familiar with CQL will note that the CQL query
When defining a new query an example position can be set up by pushing #% New example #%.
When #% Region #% is pushed the diagram displays the region of the board that applies to the query. The region can be used to limit the location of some or all the pieces that are defined in the query. The following diagram shows a region that is composed of the e-h files. This could, for instance, be used to limit the location of the white king to that region of the board.
~#% Shift #% + Click: The file
~#% Ctrl #% + Click: The rank
~#% Alt #% + Click: The diagonal parallel to the main diagonal (a1-h8)
~#% Alt #% + #% Shift #% + Click: The diagonal parallel to the a8-h1 diagonal
~#% Ctrl #% + #% Shift #% + Click: All squares that a rook could move to on an empty board.
~#% Ctrl #% + #% Alt #% + #% Shift #% + Click: Both diagonals
After entering the name of the section, hit #% OK #% and the new section will be created. There is no limit to the number of sections that can be added.
====Adding a new CQL query to a section====
The new section that we created will hold our CQL queries that find different types of checkmate. Chess Assistant doesn't just store the CQL queries, it packs it in with some useful information, such as a description, example diagram, region definition etc. Such a package is called a //characteristic// in Chess Assistant. So we want to add a characteristic to the section we just created. Let's start by adding a simple search for a checkmate without any additional conditions. Right-click on the new section in the //Condition// dialog and select //Add characteristic// from the shortcut menu. The //Characteristic info// dialog will be displayed. Enter a description in the //Name for white// text box (e.d. Checkmate) and type the query into the //CQL query// textbox. It already contains the default text, ##(match)## which is the starting point for a new query. Modify it so it looks like this:
~##(match
~ (position
~ :mate)
~)##
The dialog should now look something like this:
{{image class="center" alt="Add new query" title="Add new query" url="images/CQL-CharacteristicInfo.gif"}}
Click on #% OK #% and this new query will be added to the section. The //Condition// dialog will be displayed again and when you click on #% OK #% you will get a warning saying //Characteristic info is modified. Save changes?//. Of cours you must click on #% Yes #% if you want to save your work. When you have done that the search will be performed on the current dataset.
====Categorizing existing CQL queries====
If you have written or collected CQL queries that you keep in textfiles you should use Chess Assistant's capability to import and categorize such queries. The procedure is the same as described above. First you create a section for a collection of related queries, or use an existing section. Then you continue as described when adding a new query to a section. Only this time, instead of typing the query into the //CQL query// textbox, you import the textfile where you keep your query. Let's say that we want to add another query to the //Checkmate// section. This time the query finds smothered mate and we type //Smothered mate on the edge or in the center of the board// in the //Name for white// text box. Next we import the file. Note the two icons on the top right above the //CQL query// text box.
{{image class="center" alt="Import a CQL file" title="Import a CQL file" url="images/CQL-ImportCQL.gif"}}
The left one is for importing a CQL file, so that's the one we are interested in. When you push it the //Load CQL file// dialog opens, which is nothing but the familiar file open dialog with the file type preset to CQL files. Find the file you want to import and click on #% Open #%. The CQL file is then imported into the //CQL query// textbox which will then look something like this:
{{image class="center" alt="Old style CQL query" title="Old style CQL query" url="images/CQL-OldstyleQuery.gif"}}
As mentioned before each CQL query is bound to a specific PGN database. In this case the query we imported was designed to search ##heijden.pgn##. What we haven't mentioned mentioned is that the query also must specify where the output of the search should be stored. That's another PGN file and in this case it's ##out.pgn##. Chess Assistant offers much more flexibility (as mentioned before!) and these restrictions should simply be removed when imorting old CQL files into Chess Assistant. So, the following lines should be deleted from the imported CQL script:
## :pgn heijden.pgn
:output out.pgn##
After that save the query as described above and remember to save the changes when asked!
Those who are familiar with CQL will note that the smothered mate query only looks for positions where black is checkmated:
##:mate :btm##
Here ##:mate## tells CQL to look for a checkmate position and ##:btm## adds that it must be black's turn to move. What if we wanted instead to look for positions where white has been checkmated? In the past, before Chess Assistant 8, the only way to handle that situation would be to modify the query, change ##:btm## to ##:wtm## and a few more changes would be needed to make the query work correctly. Then the query would be saved and run again. And if you wanted to find smothered mate regardless of which side won a third version of the query would be needed. Here, once more, Chess Assistant helps to reduce the multiplicity of essentially the same query. Instead of three different queries only one is needed, and we can use the query we have already entered without any changes. The trick is to use the //Side// drop-down box to instruct Chess Assistant to switch colors or to run the query for both black and white:
~//White//: Run the query "as is"
~//Black//: Switch colors
~//Any//: This option combines //White// and //Black// and the search is performed for both sides.
Deletions:
When defining a new query an example position can be set up by pushing #%New example#%.
When #%Region#% is pushed the diagram displays the region of the board that applies to the query. The region can be used to limit the location of some or all the pieces that are defined in the query. The following diagram shows a region that is composed of the e-h files. This could, for instance, be used to limit the location of the white king to that region of the board.
~#%Shift#% + Click: The file
~#%Ctrl#% + Click: The rank
~#%Alt#% + Click: The diagonal parallel to the main diagonal (a1-h8)
~#%Alt#% + #%Shift#% + Click: The diagonal parallel to the a8-h1 diagonal
~#%Ctrl#% + #%Shift#% + Click: All squares that a rook could move to on an empty board.
~#%Ctrl#% + #%Alt#% + #%Shift#% + Click: Both diagonals
After entering the name of the section, hit #%OK#% and the new section will be created. There is no limit to the number of sections that can be added.
====Adding a new query to a section====
The new section that we created will hold our CQL queries that find different types of checkmate. Chess Assistant doesn't just store the CQL queries, it packs it in with some useful information, such as a description, example diagram, region definition etc. Such a package is called a //characteristic// in Chess Assistant. So we want to add a characteristic to the section we just created. Let's start by adding a simple search for a checkmate without any additional conditions. Right-click on the new section in the //Condition// dialog and select //Add characteristic// from the shortcut menu. The //Characteristic info// dialog will be displayed. Enter a descriptoin in the //Name for white// text box (e.d. Checkmate) and type the query into the //CQL query// textbox after erasing the default text //(match)//.
Additions:
After entering the name of the section, hit #%OK#% and the new section will be created. There is no limit to the number of sections that can be added.
====Adding a new query to a section====
The new section that we created will hold our CQL queries that find different types of checkmate. Chess Assistant doesn't just store the CQL queries, it packs it in with some useful information, such as a description, example diagram, region definition etc. Such a package is called a //characteristic// in Chess Assistant. So we want to add a characteristic to the section we just created. Let's start by adding a simple search for a checkmate without any additional conditions. Right-click on the new section in the //Condition// dialog and select //Add characteristic// from the shortcut menu. The //Characteristic info// dialog will be displayed. Enter a descriptoin in the //Name for white// text box (e.d. Checkmate) and type the query into the //CQL query// textbox after erasing the default text //(match)//.
Deletions:
After entering the name of the section, hit #%OK#% and the new section will be created.
Additions:
The //Section name// dialog will be displayed. Enter the name of the section. In this example we'll call the section "Checkmates".
{{image class="center" alt="Section name" title="Section name" url="images/CQL-SectionName.gif"}}
After entering the name of the section, hit #%OK#% and the new section will be created.
Additions:
====Adding new sections====
CQL queries can be organized by expanding the structure that comes pre-built with Chess Assistant. Let's add a new section that will be a placeholder for some of our queries. We'll add the new section below the existing ones. Right-click on the last section and select //Add section// from the shortcut menu as shown on the screenshot below.
Deletions:
====Organizing your existing queries====
If you already have a collection of CQL queries you can organize them by expanding the structure that comes pre-built with Chess Assistant.
Additions:
As you can see Chess Assistant comes with a large collection of pre-built queries that can be useful on their own or serve as examples and building blocks when you start writing your own queries. The pre-built queries are organized into nine sectionhttp://www.hornid.com/Wikka/3rdparty/plugins/wikiedit/images/h2.gif
Heading 2s, and each section contains several queries.
====Organizing your existing queries====
If you already have a collection of CQL queries you can organize them by expanding the structure that comes pre-built with Chess Assistant.
{{image class="center" alt="Add new section" title="Add new section" url="images/CQL-NewSection.gif"}}
Deletions:
As you can see Chess Assistant comes with a large collection of pre-built queries that can be useful on their own or serve as examples and building blocks when you start writing your own queries. The pre-built queries are organized into nine sections, and each section contains several queries.
Additions:
Before Chess Assistant 8 came on the scene, CQL users had to convert all the databases they wanted to search to PGN format. Regular users would have several such databases. Each query in the original, standalone CQL is stored in a textfile and bound to a specific database. So if you wanted to apply the same query to several different databases you would have to make a copy of the textfile for each one and then modify them to refer to the correct database. In order to indicate what each query does, and which database it searches, you would try to encode that information in the filename. Unfortunately, six months later you will have no idea what that filename means.
With regular use of CQL and a growing number of queries and databases a user will be unable to keep track of all his queries in this way.
====How does Chess Assistant help?====
Deletions:
Before Chess Assistant 8 came on the scene, CQL users had to convert all the databases they wanted to search to PGN format. Regular users would have several such databases. Each query in the original, standalone CQL is stored in a textfile and bound to a specific database. So if you wanted to apply the same query to three different databases you would have to make three copies of the textfile then modify them to refer to the correct database. The only indication what each query does, and which database it searches, would somehow have to be encoded in the filename. Unfortunately, six months later you will have no idea what that filename means.
With regular use of CQL and a growing number of queries and databases a user will be unable to keep track of all his queries.
====How is Chess Assistant different?====
Additions:
In the dialog above a query has been highlighted. This is query number 15 in section 2, King's position. It's index is therfore 2.15 and the description of the query is "King has one move". The diagram illustrates that situation. The white king, the object of this query, is marked with a red rectange. All squares around it, except one, are attacked by enemy pieces. Those squares are marked with a green X. The only square that the king can move to is c1 and that square is marked with a green rectangle.
Deletions:
In the dialog above a query has been highlighted. This is query number 15 in section 2, King's position. It's index is therfore 2.15 and the description of the query is "King has one move". The diagram illustrates that situation. All squares around the white king, except one, are attacked by enemy pieces. Those squares are marked with a green X. The only square that the king can move to is c1 and that square is marked with a green rectangle.
Additions:
Before Chess Assistant 8 came on the scene, CQL users had to convert all the databases they wanted to search to PGN format. Regular users would have several such databases. Each query in the original, standalone CQL is stored in a textfile and bound to a specific database. So if you wanted to apply the same query to three different databases you would have to make three copies of the textfile then modify them to refer to the correct database. The only indication what each query does, and which database it searches, would somehow have to be encoded in the filename. Unfortunately, six months later you will have no idea what that filename means.
These problems were further compounded by the fact that you would probably have to generate several temporary PGN files in order to speed up complex searches. Of course you could simply open each CQL textfile and have a look at the contents and any comments you might have put in there, but that is not the fastest way to find that query you wrote many months ago. Other ways to search through a collection of CQL files can be suggested, but there is no getting away from the fact that this is a primitive way to keep track of your queries.
Deletions:
Before Chess Assistant 8 came on the scene, CQL users had to convert all the databases they wanted to search to PGN format. Regular users would have several such databases. Each query in the original, standalone CQL is stored in a textfile and bound to a specific database. So if you wanted to apply the same query to three different databases you would have to make three copies of the textfile then modify them to refer to the correct database. The only indication what each query does, and which database it searches, would somehow have to be encoded in the filename. Unfortunately, six months later you will have no idea what that filename means. These problems were further compounded by the fact that you would probably have to generate several temporary PGN files in order to speed up complex searches. Of course you could simply open each CQL textfile and have a look at the contents and any comments you might have put in there, but that is not the fastest way to find that query you wrote many months ago. Other ways to search through a collection of CQL files can be suggested, but there is no getting away from the fact that this is a primitive way to keep track of your queries.
Additions:
Before Chess Assistant 8 came on the scene, CQL users had to convert all the databases they wanted to search to PGN format. Regular users would have several such databases. Each query in the original, standalone CQL is stored in a textfile and bound to a specific database. So if you wanted to apply the same query to three different databases you would have to make three copies of the textfile then modify them to refer to the correct database. The only indication what each query does, and which database it searches, would somehow have to be encoded in the filename. Unfortunately, six months later you will have no idea what that filename means. These problems were further compounded by the fact that you would probably have to generate several temporary PGN files in order to speed up complex searches. Of course you could simply open each CQL textfile and have a look at the contents and any comments you might have put in there, but that is not the fastest way to find that query you wrote many months ago. Other ways to search through a collection of CQL files can be suggested, but there is no getting away from the fact that this is a primitive way to keep track of your queries.
With regular use of CQL and a growing number of queries and databases a user will be unable to keep track of all his queries.
Deletions:
Before Chess Assistant 8 came on the scene, CQL users had to convert all the databases they wanted to search to PGN format. Regular users would have several such databases. Each query in the original, standalone CQL is stored in a textfile and bound to a specific database. So if you wanted to apply the same query to three different databases you would have to make three copies of the textfile then modify them to refer to the correct database. The only indication about what each query does and to which database it applies would somehow have to be encoded in the filename. Unfortunately, six months later you will have no idea what that filename means. These problems were further compounded by the fact that you would probably have to generate several temporary PGN files in order to speed up complex searches. Of course you could simply open each CQL textfile and have a look at the contents and any comments you might have put in there, but that is not the fastest way to find that query you wrote many months ago. Other ways to search through a collection of CQL files can be suggested, but there is no getting away from the fact that this is a primitive way to keep track of your queries.
With regular use of CQL and a growing number of queries a user will be unable to keep track of all his queries.