Query Builder

Now reading version 17.1. For the latest, read: Query Builder for version 22
Applies to Altium Designer versions: 15.1, 16.0, 16.1, 17.0 and 17.1

The Query Builder dialog as accessed through the PCB Filter panel and the PCB Rules and Constraints Editor dialog (back) and as accessed through the PCB Editor (front).
The Query Builder dialog as accessed through the PCB Filter panel and the PCB Rules and Constraints Editor dialog (back) and as accessed through the PCB Editor (front).

Summary

The Query Builder dialog enables you to create a query for targeting specific objects in the design document, by simple construction of a string of ANDed and/or ORed conditions. The dialog can be accessed from a number of places within Altium Designer; certain options may differ depending on how the dialog is accessed.

For more information about Query Language, click here. For more information about Query Functions, click here.

Access

The dialog can be accessed in the following ways:

  • From the PCB Filter panel, click the Builder button to access this dialog.
  • From the PCB Rules and Constraints Editor dialog, in each specific design rule, click Query Builder (if it exists).
  • From the PCB Editor, select Edit » Build Query from the toolbar.
  • From the PCB Editor, right-click and Build Query from the context menu.

Options/Controls

Left Section

  • Condition Type/Operator - The left-hand section of the dialog is where you specify the condition(s) required to target the set of objects needed. Initially the entry in the Condition Type/Operator column will be Add first condition. Clicking once on this entry will reveal a drop-down list of condition types. The list is sensitive to wherever the dialog was launched from. For example, if you right-clicked on a component in the design and entered the Query Builder, the condition types will only reflect those relevant to a component object. Similarly, if you are building a query for a particular design rule within the PCB Rules And Constraints Editor dialog, the condition list will only reflect condition types possible for that particular rule type.
  • Condition Value - Choose the first condition and click in the Condition Value column to access a drop-down list of possible values for that condition type. As you define a condition in the left-hand section of the dialog, a preview of the currently built query is shown in the right-hand section.

Continue to 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 and select the required operator. The preview of the query will update accordingly.

Right Section

The right and left arrow buttons at the top of the dialog allow you to essentially add and remove brackets around the presently selected condition (increasing and decreasing indent). This allows you to create precedence for certain logically ANDed or logically ORed conditions. For example, consider the following built query:

Show Level

Use the Show Level drop-down at the top-left of the dialog to control the visual display of levels in your structured string of conditions. This essentially expands/collapses the display of brackets. Adding brackets creates a new level. You can display levels 1-5. For any further levels added, use the Show All Levels option. Alternatively, click on the expand (+) or contract (-) symbols to show the next level(s) or hide the current level (and all levels below) respectively. The + and - buttons at the top of the dialog can be used to expand or collapse the selected condition.

Use the up and down arrow buttons at the top of the dialog to move a selected condition in the query string being built. For a condition that has sub-levels (ie. a bracketed condition), any condition in the level structure can be moved. When levels are expanded, a condition can be moved down or up through the levels. When levels are collapsed, a condition will be moved over the level structure.

To delete a condition, select it and click the delete button at the top of the dialog (red cross), or use the Delete key.

Bottom Section

When accessed through directly from the PCB Editor (either through the right-click menu or via the toolbar), the bottom section of the dialog contains controls related to identifying and selecting objects on the PCB which match your query and saving.

  • Zoom Matching - Zoom the display to a window that encompasses all found objects in the workspace that match the search criteria.
  • Select Matched - Select all found objects matching the search criteria.
  • Clear Existing - Clear any existing selection or editing mask before performing the search. Uncheck this option if doing successive searches and it is desirable for the results to accumulate.
  • Create Expression -The query expression will be saved to the List panel where it can be re-used.
  • Normal/Mask/Dim - This dropdown provides you with the following options for visibly contrasting filtered and unfiltered objects within the design editor window:
    • Normal - Filtered objects are highlighted, however, the appearance of unfiltered objects remains unchanged.
    • Mask - Filtered objects will appear visible in the design editor window, with all other objects being made monochrome. When this option is applied, unfiltered objects will be unavailable for selection or editing.
    • Dim - Filtered objects will appear visible in the design editor window, with all other objects retaining their colors, but being shaded.
The effectiveness of masking and dimming is determined by the Highlighting Options set on the PCB Editor - Display page of the Preferences dialog. Controls for adjusting masking and dimming are accessed from the Mask Level button (bottom right of the design editor window).
  • Run Inspector - If enabled, the Inspector panel appears with the filtered objects and can be used to make changes to these objects.

Tips

The Query Builder (Building Query from Board dialog) 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 and choosing the required new condition from the available entries in the drop-down list. Again, the preview of the query will update accordingly.

The currently selected condition or logical operator in the left side of the dialog is visually confirmed in the preview section of the dialog by the entry appearing in red text.

Use Ctrl + Up Arrow and Ctrl + Down Arrow keyboard shortcuts to move the selected condition entry up or down in the structure respectively. 
Use Ctrl + Right Arrow and Ctrl + Left Arrow keyboard shortcuts to increase or decrease indent at the selected position in the structure (add/remove brackets) respectively.

Note

The features available depend on your level of Altium Designer Software Subscription.