Search In: Doc:Documentation: Altium Designer
Altium DesignerAltium 365Altium MCAD CoDesignerAltium CircuitMakerCompany DashboardAltium On-Prem Enterprise ServerAltium Infrastructure Server
Ver: Version: 25
252423222120.220.120.0
Close
Search Search on Documentation

Working with the Query Language

Created: August 30, 2024 | Updated: August 30, 2024 | Applies to versions: 24 and 25
 

What is a Query?

Perhaps the greatest challenge when working on a complex electronics design is managing a large number of design objects. From the components, net labels and text strings on the schematic sheets to the hundreds of components and tracks that make up the routing on the PCB,  you need to be able to access, review and edit those objects. Like most Windows applications, you can double-click on an object and edit its properties. This is fine for a single object, but not something you want to do if you need to edit 300+ component designator strings or change all the vias on the PCB. For these kinds of updates, you need to access multiple objects simultaneously. 

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.

The powerful data filtering and editing system in Altium Designer lets you instruct the software to return 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 and dim out all other objects, or perhaps you want to browse or sort their properties and modify specific attributes they all share.

There are a number of places where you can apply a query but command central are the Filter panels shown in the images below. Press F12 to display/hide the Filter panel.

The PCB Filter and SCH Filter panels with queriesThe PCB Filter and SCH Filter panels with queries

The PCBLIB Filter and SCHLIB Filter panels with queries
The PCBLIB Filter and SCHLIB Filter panels with queries

The controls in the panel are used to define to which objects the query will be applied and how to handle the objects that pass the query, as well as those that fail.

Where Are the Query Results?

Now that you have written a query in the Filter panel, how do you access the objects returned by your query? There are two 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 but once a filter has been applied, it displays only the objects returned by the query. The List panel has standard spreadsheet-like behaviors for sorting and selecting, allowing you to edit single or multiple cells directly. 

The PCB List panel and SCH List panel display the results from the PSB/SCH queries in the previous section.The PCB List panel and SCH List panel display the results from the PSB/SCH queries in the previous section.

Highlighting Options

Whenever a query is applied (or the data filtering feature is otherwise used), each object within the target document becomes a member of that filtering action's results. However, how the objects in the results and the objects that are not in the results are subsequently displayed depends upon the highlighting option(s) selected in the Filter panel. There are three different highlighting options available and the options are totally independent of one another, so you can select one, two or all.

Zoom

When the Zoom option is enabled when the query is applied, the view of the target document is updated to display the region occupied by all of the objects that are in the results. Whether or not each remaining object is displayed in the updated view depends upon its location relative to that region, so each of those objects can end up being totally displayed, or partially displayed, or not even displayed at all. 

This option is often selected in conjunction with one or both of the other options. If the Mask option has not been enabled, objects that are not in the results will still be displayed in the graphical view if they are located within the updated boundaries. At first glance, selecting this option by itself might seem pointless, but there could be times when you want to update the graphical view so that this encompasses particular objects, while not changing the selected state or masked state of any of the document's objects.

Select

When the Select option is enabled, all of the objects that are in the results are in the selected state, while all of the remaining objects are not selected. Selected objects are displayed in a more distinctive manner as non-selected objects.

If the Select option is selected when the current query is applied, all of the objects which are members of the result set subsequently acquire a selected state, while all of the remaining objects (which are not members of the result set) acquire an unselected state instead. This option would typically be selected just prior to global editing procedures because only those objects which are currently selected have their properties updated at the time. But there are other occasions when the Select option can be useful, such as when particular objects are to be moved, copied or deleted.

Mask

The Mask highlighting option determines the updated masked property of objects in the target document. When selected, all of the objects that are in the results are masked, while all of the remaining objects are unmasked. The main aspect of masked objects is that they and their properties are not capable of being edited. (Masked objects are displayed as dimmed in the list view, but are not displayed in the list view unless the all objects option is currently selected in the List panel.) The main aspect of masked objects is that the object and its properties are not capable of being edited.

The Query Builder

The PCB editor includes a dedicated Query Builder dialog. This dialog allows you to 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.

The 'Building Query' dialog (part of the 'Query Builder' feature) assists those who are less experienced in specifying queries; a query is automatically generated whose contents correspond to the conditions specified by the designer.

The left-hand section in this dialog contains controls, whose purpose is to assist the designer in the task of specifying what properties are required for each of the document's objects to be returned by the query generated by this dialog. As each of those conditions is specified or edited, the contents of the corresponding query are updated and displayed in the dialog's right-hand section. If this dialog is then closed by clicking on its OK (or Apply) button, either the associated query will then be applied, or its contents will then be copied back to the Filter panel (depending upon how this dialog was invoked in the first instance).

The Query Builder dialog can be launched from the following places (as shown in the image below):

  • From the PCB Filter panel, click the Query Builder button to build a query and to load the string into the panel.
  • From the PCB Rules and Constraints Editor dialog, click the Builder button to build a query that defines to which objects this rule applies. 

When the Query Builder dialog is accessed from the PCB Rules and Constraints Editor dialog, it will display options that are suitable only for that rule kind.

The image below shows the Query Builder dialog being used to create a query that targets both pads and vias on the 5V net.

The Query Builder dialog
The Query Builder dialog

  • Add further conditions to narrow down your target set of design objects as required. Conditions can be ANDed or ORed together. The default logical operator is AND.
  • To change the logical operator between conditions, click on the AND or OR entry in the Condition Type/Operator column then select the required operator. The preview of the query will update accordingly.
  • The Query Builder dialog (Building Query from Board ) is a simpler method of constructing a query using sensitive condition types and values that only allow you to build using relevant 'building blocks.' For advanced query construction with full keyword specification and operator syntax use the Query Helper dialog.
  • You can adjust any condition in your query string at any time by clicking on the entry for that condition in the Condition Type/Operator column then choosing the required new condition from the available entries in the drop-down list. The preview of the query will update accordingly.
  • Use Ctrl+Up Arrow and Ctrl+Down Arrow keyboard shortcuts to move the selected condition entry up or down in the structure. 
  • Use Ctrl+Right Arrow and Ctrl+Left Arrow keyboard shortcuts to increase or decrease the indent at the selected position in the structure (add/remove brackets).

The Query Helper

The next step in building your query-writing skills is to use the Query Helper dialog. The Query Helper dialog includes a Query box in which you can enter the desired query, while also using the syntax buttons below the Query field (e.g., And, Or, <, Not,  Like, etc.,) as well as a complete list of all query keywords in the Categories field.

The 'Query Helper' dialog provides assistance for designers who want to specify their own queries. A brief description is provided for each keyword that is listed, but the online help can be accessed by pressing the F1 key while a keyword is highlighted. That invokes the Altium Designer Documentation Library dialog, which provides details of which objects within a document are returned by the highlighted keyword, how to use that keyword, and one or more examples of its usage.

The dialog can be accessed in the following ways:

  • Click the Helper button in the Filter panel.

PCB Filter panel access

SCH Filter panel access

The Helper button is available after clicking Advanced in the File-based Libraries Search dialog.

File-based Libraries Search dialog accessFile-based Libraries Search dialog access

Use the Query section at the top of the dialog to compose a query expression, using the available functions. In the text box, you can review and/or further edit the search expression. Type directly into the text box to edit the search expression. To search for specific keywords to add, begin typing. While you are typing, the dialog will offer a drop down menu of available keywords that match the text you have written so far. Click a keyword to auto-finish typing your selection. If the desired keyword is highlight, pressing Enter will also auto-finish your selection.

Browse through the 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 *har in the Mask field will find keywords that apply specifically to harnesses, as shown in the image below. 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 entered, documentation for that keyword will open. This is the most valuable resource for learning the basic behavior of each query keyword.

Double-click a keyword in the grid to add it to the query at the current cursor position.

The middle region of the dialog includes syntax buttons that provide a range of operators for use when constructing an expression. For more information on the individual function of each syntax button, visit the Logical Query Expression Operators section below. Use the Check Syntax button (bottom left of the dialog) to verify that an expression is syntactically correct.

Historical Queries

As you enter and apply a new query from a filter panel (SCH Filter / SCHLIB Filter, PCB Filter / PCBLIB Filter), it will be added to a query history list. Click the History button on the panel to access this list. The Expression Manager dialog opens with the History tab active.

The History tab of the Expression Manager dialog provides a listing of query expressions used in the past. Here, an example of historical queries for the Schematic is shown. Hover the mouse over the image to see a similar example list for the PCB.The History tab of the Expression Manager dialog provides a listing of query expressions used in the past. Here, an example of historical queries for the Schematic is shown. Hover the mouse over the image to see a similar example list for the PCB.

To use a historical query from the list, either select its entry and click on the Apply Expression button or double-click on the entry directly. The dialog will close and the expression for the query will be loaded into the central region of the relevant filter panel.

A historical query can be added to the list of favorite queries by selecting its entry and clicking the Add To Favorites button. Use the Clear History button if you want to 'flush' the history list.

Up to nine of the most recently used query expressions from the list will be available for use from the filter panel's right-click History sub-menu.

Note that the content of the History list is common to (and accessible from) the filter panels in a design domain (SCH Filter / SCHLIB Filter in the Schematic editing domain; PCB Filter / PCBLIB Filter in the PCB editing domain). Some query expressions may not return results when used in the Schematic Editor, especially if they have been created to target objects that are available within the Schematic Library Editor only.

Favorite Queries

Any defined query may be added to a list of favorite queries in two ways:

  • Click the Add To Favorites button or right-click in the main Query Expression region and choose the Add to Favorites command from the context menu to add the query expression currently defined in the central region of the active filter panel.
  • Select a historical query entry on the History tab of the Expression Manager dialog, then click the Add To Favorites button.

Favorite query expressions are stored to, and managed from, the Favorites tab of the Expression Manager dialog. Access can be made by using the Favorites button on a filter panel (SCH Filter / SCHLIB Filter, PCB Filter / PCBLIB Filter) or by right-clicking in the main Query Expression region of a filter panel, and choosing the Organize Favorites command from the context menu. From the design space, the dialog can be accessed by using the Y shortcut key, then selecting Organize Favorites from the pop-up filtering menu.

Access a listing of your favorite queries from the editor's filter panel or from the design space, using the filtering pop-up menu.Access a listing of your favorite queries from the editor's filter panel or from the design space, using the filtering pop-up menu.

When a query expression is added to the Favorites list, it is assigned a unique name. By default, a generic name is assigned - Favorite_n - where n is the next available unused number. The name for an entry can be changed at any stage by using one of the following methods:

  • Selecting the query entry then clicking the Rename button.
  • Selecting the query entry then choosing the Edit command from the right-click menu.
  • Selecting the query entry then clicking again within the Name field.

In each case, type the new name as required then click outside the Name field to effect the change.

To edit a favorite query expression select its entry in the list, then click the Edit button (or right-click and choose Edit from the context menu). The Edit Favorite dialog will open. Use the dialog to modify the name of the favorite, change the expression itself, and also determine how design objects are handled (both those that pass the filter and those that don't).

Modify an existing favorite query using the Edit Favorite dialog, shown here for Schematic (left) and PCB (right).Modify an existing favorite query using the Edit Favorite dialog, shown here for Schematic (left) and PCB (right).

To remove a query from the Favorites list, select its entry in the list then either click the Remove button or choose the Remove command from the right-click menu. A dialog will appear requesting confirmation of the removal.

Note that the content of the Favorites list is common to (and accessible from) the filter panels in a design domain (SCH Filter / SCHLIB Filter in the Schematic editing domain; PCB Filter / PCBLIB Filter in the PCB editing domain). Some query expressions may not return results when used in the Schematic Editor, especially if they have been created to target objects that are available within the Schematic Library Editor only.

Using Favorite Queries

There are three ways in which to use your favorite queries:

  1. From the Favorites tab of the Expression Manager dialog - either select its entry then click on the Apply Expression button or double-click on its entry. The dialog will close and the expression for the query will be loaded into the central region of the relevant filter panel.

  2. From the top of the filter panel's right-click menu (up to ten of the most recently added query expressions to the Favorites list are available).

  3. From the design space's filtering pop-up menu (press Y) - up to ten favorite query expressions are listed at the top of the menu. The chosen query expression will be loaded into the central region of the relevant filter panel.

You also can define a shortcut key for a favorite by customizing the Filter menu. For more information on customizing the Altium Designer environment, see Configuring and Customizing Altium Designer.

Using Pre-packaged Examples

Both the schematic and PCB editors come with a set of pre-packaged example queries. These examples are available from the filtering menu - accessed either by right-clicking in the expression region of the filter panel, or by using the Y shortcut key in the design space. Hover over Examples to view the sub-menu.

When you select an entry in the sub-menu, the query behind that filter is applied. To view the actual query behind one of the examples, look in the History list after applying it. You also can access this list in the filtering pop-up menu.

To clear the filtering, press Shift+C in the design space or right-click in the design space and select the Clear Filter command in the context menu.

Query Building Tools

Perhaps the easiest way to write a query is to have Altium Designer write it for you! You can do this by using either the Find Similar Objects dialog or the Query Builder dialog.

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, that query will be displayed in the Filter panel. This is an excellent technique for learning different query keywords.

The Find Similar Objects dialog opens when you right-click on any unmasked object in your design document then select Find Similar Objects from the context menu.

Left image: PCB version; right image: SCH versionLeft image: PCB version; right image: SCH version

This dialog allows you to find objects similar to the one on which you right-clicked, then define which of the object's attributes that must be the same (or different) for a match. Suppose you wanted to change all GND pads in your design. You could right-click 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 click Apply in the dialog. If the Create Expression option is enabled, the following query would appear in the Filter panel: (ObjectKind = 'Pad') And (Net = 'GND').

As an example from a schematic, you can change the Color property of all Power Objects having a particular Text property (e.g. 'GND') within a document to the same value. For example, from a PCB, you can change the Hole Size property of all vias having a particular Via Diameter property within a document to the same value.

For more information about using the Find Similar Objects dialog, refer to Using Find Similar Objects Tools.

Clear Existing Option

Enable the Clear Existing option to clear any existing selection or editing mask before applying the search. Disable this option if you are performing successive searches and it is desirable for the results to accumulate.

Filter Toolbar

The Filter Toolbar is provided for PCB documents and allows you to mask all of the objects within a document except for those having a specified property, or for those forming part of a specified component. The right-most field of the toolbar is used to specify the contents of a query. You can enter the query in the field or you can use the drop-down to select from recent queries (one that exists in the query History list). It is not possible to specify which options to use when queries are applied from the Filter Toolbar and in all cases, any previous query is cleared, and the Mask and Zoom options are then used with the current query. To use query options, use the Filter panel, Query Builder dialog, Query Helper dialog, or Find Similar Objects dialog.

  • If the board is unrouted, the logical connections associated with the chosen net will become visible when the filter is applied. If the board is routed, the routed track associated with the chosen net will become visible when the filter is applied.
  • With masking applied, all objects not under the filter scope will be unavailable for selection/editing. The extent of the masking applied can be manually adjusted using the Masked Objects slider bar accessed in the Mask and Dim Settings section on the View Options tab of the View Configuration panel.
  • You can manually clear an existing (and applied) filter at any time by using the Shift+C keyboard shortcut or by clicking the  button on the Filter toolbar.

Logical Query Expression Operators

Below is a summary of the operators that can be used when defining logical query expressions with the query language.

Arithmetic Operators

Operator Description Example
+ Addition operator NetPinCount + NetViaCount
- Subtraction operator ArcStopAngle - ArcStartAngle
* Multiplication operator PadXSize_BottomLayer * PadYSize_BottomLayer
/ Division operator HoleDiameter / ViaDiameter
Div Integral division operator Color Div 65536
This calculates Color divided by 65536 and the fractional part of the result is discarded
Mod Modulus operator Color Mod 256
This calculates the remainder when Color is divided by 256, without determining the fractional part of the result

Logical Operators

Operator Description Example
And Logical AND operator IsPad And OnMultiLayer
To be returned, an object has to be a pad, and reside on the Multi-Layer layer
&& Logical AND operator
(lower precedence)		 IsPad && OnMultiLayer
To be returned, an object has to be a pad, and reside on the Multi-Layer layer
Or Logical OR operator IsPad Or IsVia
To be returned, an object has to either be a pad, or a via
|| Logical OR operator
(lower precedence)		 IsPad || IsVia
To be returned, an object has to either be a pad, or a via
Xor Logical EXCLUSIVE OR operator OnMultiLayer Xor (HoleDiameter <> 0)
To be returned, an object has to either be on the Multi-Layer layer and have a Hole Diameter that is zero, or not
be on the Multi-Layer layer and have a Hole Diameter that is not zero.
Not Logical NOT operator Not OnMultiLayer
To be returned, an object has to not be on the Multi-Layer layer

Comparison Operators

Operator Description Example
< Less Than operator HoleDiameter < 40
To be returned, an object has to have a Hole Diameter which is less than 40
<= Less Than Or Equal To operator HoleDiameter <= 40
To be returned, an object has to have a Hole Diameter which is less than, or equal to 40
>= Greater Than Or Equal To operator HoleDiameter >= 40
To be returned, an object has to have a Hole Diameter which is greater than, or equal to 40
> Greater Than operator HoleDiameter > 40
To be returned, an object has to have a Hole Diameter which is greater than 40
<> Not Equal To operator HoleDiameter <> 40
To be returned, an object has to have a Hole Diameter which is not equal to 40
= Equal To operator HoleDiameter = 40
To be returned, an object has to have a Hole Diameter which is equal to 40
Between...And... Inclusive range operator HoleDiameter Between 30 And 50
To be returned, an object has to have a Hole Diameter that is greater than, or equal to 30, and
less than, or equal to 50.
Like Like operator Name Like 'ADDR?*'
This returns objects having a Name property whose associated (text) string begins with ADDR and
which contains at least one more character

Wild Card Characters

Wild Card characters permit the provision of strings which are not exactly specified. These characters are typically used in conjunction with other characters, resulting in the provision of strings which are partially specified. A few exceptional keywords can accept string parameters that are not exactly specified, but for the most part, strings can only contain Wild Card characters when these are being compared by the Like operator.

Operator Description Example
? This can be replaced by a single character of any type Footprint Like 'DIP1?'
This returns objects which have a Footprint property of DIP10, or DIP12, or DIP14, etc.
* This can be replaced by any number of characters, each of which can be of any type Footprint Like 'SIP*'
This returns objects which have a Footprint property of SIP1, or SIP12, or SIP216, etc. (Any objects having a Footprint property of SIP are also returned, because '*' can also be replaced by no characters)

Boolean Strings

Operator Description Example
True This affirms the meaning of a Keyword IsPad = True
To be returned, an object has to be a pad
False This negates the meaning of a Keyword IsVia = False
To be returned, an object has to not be a via

Round Brackets and Order of Precedence

It is worthwhile taking a look at the order of precedence in place for the operators used in logical Query expressions. After all, without such knowledge, an expression may not target the objects required.

Round brackets have the highest precedence within an order of precedence that has been defined for the various operators, and which determines how queries are interpreted by the software (whenever the user has not provided round brackets). The sequence of this order, from highest to lowest, is as follows:

  1. Round brackets ()
  2. Not
  3. ^, *, /, Div, Mod, And
  4. +, -, Or, Xor
  5. =, <>, <, >, <=, >=
  6. &&, ||
This order of precedence is similar to that used in Pascal-type languages. Ambiguities are resolved by working from left to right. Round brackets are evaluated from inside to outside and equal levels are evaluated left to right.
It is highly advisable to use round brackets whenever there is any possibility, whatsoever, that the query might not be correctly interpreted. Generous usage of round brackets removes doubt and makes the resulting queries easier to read by others.

Global System Query Functions

Global system query functions shown in the Query Helper dialog
Global system query functions shown in the Query Helper dialog

This section details the query language keywords available in the schematic, PCB, and library documents in Altium Designer. For help on a specific query keyword, use the following collapsible sections or highlight (or click inside) any given keyword - in the Query Helper, a Filter panel, or the Query field of a PCB design rule - and press F1 to access its section right away.

For details about query language keywords available in specific editors and tools in Altium Designer, refer to the following pages:

Arithmetic Functions

Trigonometry Functions

Exponential and Logarithmic Functions

Aggregate Functions

System Functions

If you find an issue, select the text/image and pressCtrl + Enterto send us your feedback.
Note

The features available depend on your Altium product access level. Compare features included in the various levels of Altium Designer Software Subscription and functionality delivered through applications provided by the Altium 365 platform.

If you don’t see a discussed feature in your software, contact Altium Sales to find out more.

Content