Introduction to the Query Language

Underlying Altium Designer's schematic and PCB editors is a powerful query engine. By entering queries into this engine you can filter down to find and edit precisely those objects you require.

Perhaps the greatest challenge when working on a complex electronics design is managing the large number of design objects. From the components, net labels and text strings on the schematic sheets, through to the hundreds of components and tens of thousands of track objects that make up the routing on the PCB, as the designer you need to be able to access, review and edit these objects.
Like most Windows application you can of course double-click on an object and edit its properties. This is fine for a single object, but not something you would like to do if you need to edit the stroke width for the 300+ component designator strings, or change the annular ring for all the vias on the PCB. For this you need to access multiple objects simultaneously - to inspect them, to edit them, or apply a PCB design rule to them. Ideally you should be able to access different types of objects simultaneously too - the query-based filtering system lets you do precisely this.
Figure 1 shows a diagram of the Altium Designer filtering system, you can see how the Query Engine is used control the Filter Engine, allowing you to exactly control what objects are returned.

What is a Query?

The powerful data filtering and editing system in Altium Designer lets you instruct the software to return you a specified set of objects. This instruction is entered in the form of a Query. A query is a string you enter using specific keywords and syntax, which will return the targeted objects. What you do with those objects is up to you. Perhaps you want to highlight them, dimming out all other objects. Or perhaps you want to browse or sort their properties, and modify specific attributes that they all share. There are a number of places where you can apply a query but command central is the Filter panel, as shown in Figure 2. Press F12 to display/hide the Filter panel.

Note the controls on either side of the Filter panel, these are used to define which objects the query will be applied to, and how to handle the objects that pass the query as well as those that fail.

Where are the Query Results?

So you have written a query in the Filter panel, now how do you access the objects returned by your query? There are three ways that objects can be accessed and edited in the Altium Designer environment.
Graphically - after applying a filter the default behavior is to mask (fade and make non-editable) all objects that failed the query, leaving only those that passed. This mode is excellent for locating and reviewing objects in the workspace. Since the masked objects are not editable, commands like Ctrl+A (select all) only apply to the objects returned by the query.
List panel - the List panel (Shift+F12) is a spreadsheet-like view into your design data. By default it displays all design objects, once a filter has been applied it displays only the objects returned by the query. The List has standard spreadsheet-like behaviors for sorting and selecting, allowing you to edit single or multiple cells directly. Note that the top of the List panel has a number of controls, press F1 when the cursor is over the panel for help with these controls and other general panel behavior.
Inspector panel- where the List presents the objects' properties in a table, the Inspector collates the common attributes of the selected objects into a single column. Note the total number of selected objects is displayed at the bottom of the panel. After editing the value in a cell press Enter to apply the change. Press F1 when the cursor is over the Inspector panel for more information.

Building your Query Writing Skills

How can you learn to write queries? Like anything new, it take practice. Altium Designer includes valuable resources for learning the query language. The first is a set of example queries that are included as part of the installation. The second is a group of tools that generate queries based on your input. The third is the Query Helper, which lists all query keywords and helps you build up a query. The final source in learning the query language is in the online help.

Example and Favorite Queries

Both the schematic and PCB editors come with a set of pre-packaged example queries. To try these, press the Y shortcut key to display the Filter popup menu, where you can select the Examples sub-menu. When you select an entry in the menu the query behind that filter is applied (press Shift+C to clear it). To view the actual query behind one of the examples look in the History list after applying it, you can access this list in the Filter popup menu too.
You can also keep favorite queries and re-use them later. Favorites are stored in the Expression Manager dialog - there are a number of ways to access this dialog, via the Favorites button in the Filter panel, or by selecting the Organize Favorites menu entry after pressing the Y shortcut key. The great thing about favorites is that they are automatically displayed in the Filter menu, giving you instant access to up to ten favorite queries.

Query Building Tools

Perhaps the easiest way to write a query is to get Altium Designer to write it for you! There are two ways of doing this, using the Find Similar Objects dialog, or the Query Builder.

Find Similar Objects dialog

When you use the Find Similar Objects dialog it generates a query to find the required objects. If the Create Expression option is enabled then that query will be displayed in the Filter panel. This is an excellent technique for learning different query keywords.
The Find Similar Objects dialog appears when you right-click on any unmasked object in your design document and select Find Similar Objects from the context menu. The idea with this dialog is that it lets you find objects similar to the one your right-clicked on, where you define which of the object's attributes that must be the same (or different) for a match.
Suppose for example you wanted to change all GND pads in your design. You could right-clicking on one such pad, choose Find Similar Objects, then change the Net field from Any (the default setting) to Same. All of the GND pads will be selected when you Apply from this dialog, and if the Select Matching option is enabled you can use the Inspector to make the change across the entire selection. If the Create Expression option is enabled in the Find Similar Objects dialog then the following query would appear in the Filter panel:
(ObjectKind = 'Pad') And (Net = 'GND')

The Query Builder

The PCB editor also includes a dedicated Query Builder. This tool lets you build complex queries by choosing test conditions from drop-down lists. An advantage of the Query Builder is that it lets you create a query that targets different kinds of objects, for example Figure 6 shows the Builder being used to create a query that targets both pads and vias on the -12V net.
The Query Builder can be launched from a number of places. Click the Builder button in the Filter panel to build a query and the string loaded into the panel. Click the Builder button when you are editing a design rule to build a query that defines which objects this rule must apply to.
You can also call up the Builder directly in the design workspace, either by pressing the Shift+B shortcut keys, or right-clicking in the workspace and choosing Build Query from the context menu. When you run the Builder in the workspace it will look different from when it is run from the Filter panel or Rules dialog, in the workspace it applies the query immediately so it includes display-type controls, whereas from the Filter panel or Rules dialog it creates the query string instead.
Note also that the right-click option is context sensitive, the options available will change depending on what object you right-clicked on. Running the Builder from the Design Rules dialog is also context sensitive, it will only give you options that are suitable for that rule kind.

Query Helper

The next step in building your query-writing skills is to use the Query Helper. Accessed via the Helper button in the Filter panel, the Query Helper includes a query editing box at the top, syntax buttons like And and Or in the mid-region of the dialog, as well as a complete list of all query keywords below that.
Browse through the different categories of available keywords for the one you want. Use the Mask field if you are not sure what the exact keyword is. For example, in the schematic editor's Query Helper, entering* para in the Mask field will show you the dozen or so keywords that apply to parameters specifically, while* par will pick up keywords for both parameters and parts. Note that the Mask field works on both the keyword name field and the description field, so it can be the quickest way to find possible keywords.
If you press F1 when a keyword is highlighted or the cursor is within a keyword you have typed in, an online help description for that keyword will open. This is the most valuable resource for learning the basic behavior of each query keyword. Here you will learn the nuances of that keyword, such as keywords that return children objects, parent objects or both.

Where to Now?

Queries may seem intimidating at first, but your efforts to learn them will pay off with the improved productivity that they bring. They provide a powerful method of accessing objects in your design.