Altium Query
Courtland Boland
Underlying Altium Designer's Schematic and PCB editors is a powerful query engine. By entering queries into this engine you can logically scope precisely those objects you require. A query is a string you enter using specific keywords and syntax, which will return the targeted objects.
Queries are primarily defined in a Filter panel, but are also used to define scoping for PCB design rules. As you build your knowledge of the Query Language, and the functions, keywords and syntax available, you will be able to type expressions directly. However, until that level of confidence is built, the Query Helper can be a beneficial crutch on which to lean! Providing an editing window in which to 'build' an expression, the Query Helper contains a full listing of query functions/keywords and related controls, as well as a handy syntax checker.
The vastness of the Query Language may seem a little daunting to begin with, but over time you will learn to appreciate its power - building a set of favorite query expressions with which to target common sets of objects (and committing them to muscle memory). And to quickly get up to speed, information is available for each of the query functions. 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 page within the documentation.
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.
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.
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.
The SCH Filter panel allows you to construct filters through the creation of logical queries. A defined filter can then be applied to the active schematic document or all open schematic documents, allowing you to select and edit multiple objects with greater accuracy and efficiency.
The central region of the panel allows you to construct filters through the entry of logical queries. You can type a query directly into the field. As you type, a prompt list of possible keywords will appear as an aid.
The Query Helper is available to provide aid in the creation of queries. This function can be very useful if you are unsure of the syntax of a query or the possible keywords that you may want to use. To use the Query Helper, click the Helper button to open the Query Helper dialog. The underlying Query Engine analyzes the document and lists all available objects along with generic keywords for use in queries.
Use the top section of the dialog to compose a query expression, using the available SCH Functions and System Functions. The middle section of the dialog provides a range of operators for use when constructing an expression. Use the Check Syntax button to verify that an expression is syntactically correct.
Before application of the query, it is best to define how you want the result of the filtering to appear visually in the design workspace. The Objects passing/not passing the filter regions of the panel provides various options that collectively form the highlight controls for permanent filtering.
The options available in the Objects passing the filter area allow you to control the visual display in the workspace of all objects that fall under the scope and match the specific query expression of the filter:
The options available in the Objects not passing the filter area allow you to control the visual display in the workspace of all objects that do not fall under the scope and/or do not match the specific query expression of the filter:
Any combination of these options can be enabled. For example, you might want to have all filtered objects that fall under the scope of your query to be zoomed, centered and selected in the design editor window, while also applying masking to take away the clutter of other design objects.
To clear the currently-applied filter from within the panel, clear the entry for the query expression in the panel then either click the Apply button or press Enter. All objects in the design workspace will become fully visible and available for selection/editing.
Keep in mind that the content of the History list is common to (and can be populated from) both the SCH Filter and the SCHLIB Filter panel. 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.
The SCHLIB Filter panel allows you to construct filters through the creation of logical queries. A defined filter can then be applied to the active schematic library component or all components in the active schematic library, which allows you to select and edit multiple objects with greater accuracy and efficiency. The visual display of objects can be specified based on those that match the search criteria of the filter and those that do not.
Along with the prompt list, the panel also offers the Query Helper facility to provide aid in the creation of queries. This facility can be very useful if you are unsure of the syntax of a query or the possible keywords that you may want to use. To use the Query Helper, click the Helper button to open the Query Helper dialog. The underlying Query Engine analyzes the document and lists all available objects, along with generic keywords for use in queries.
Use the top section of the dialog to compose a query expression using the available SCH Functions and System Functions. The middle region of the dialog provides a range of operators for use when constructing an expression. Use the Check Syntax button to verify that an expression is syntactically correct.
When the expression for the query has been defined as required, click OK to load the query into the central region of the SCHLIB Filter panel. Apply the filter using the Apply button.
Before application of the query in the SCHLIB Filter panel, it is best to define how you want the result of the filtering to appear visually in the design editor workspace. The right-hand region of the panel provides various options that collectively form the highlight controls for permanent filtering.
The Objects passing the filter options allow you to control how all objects that fall under the scope and match the specific query expression of the filter will be visually displayed in the workspace.
Conversely, the Objects not passing the filter options allow you to control how all objects that do not fall under the scope and/or match the specific query expression of the filter will be visually displayed in the workspace.
To clear the currently-applied filter from within the panel, clear (select and delete) the query expression in the central region of the panel then either click the Apply button or press Enter. All objects in the design workspace will be restored to full visibility and be available for selection/editing.
Keep in mind that the content of both the Favorites and History lists is common to (and can be populated from) both the SCHLIB Filter and the SCH Filter panel. 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.
The PCB Filter panel provides controls to construct filters through the creation of logical queries. A defined filter can then be applied to the active PCB, allowing you to select and edit multiple objects with great accuracy and efficiency.
Panels can be configured to be floating in the editor space or docked to sides of the screen. If the PCB Filter panel is currently in a group of panels, use the PCB Filter tab located at the bottom of the panels to bring it to the front.
The PCB Filter panel is composed of three regions. The first two are selectable list areas that collectively define the scope of the filtering: Object and Layer.
The main region of the panel provides controls for quickly building simple filter expressions targeting any combination of objects. Object types are arranged in an 'object matrix', categorized in accordance with being net objects (Net), component objects (Comp), or free objects (Free). The following core object list is replicated across these three groups:
The Text object is available as part of the Comp and Free groupings, however, since this object type is not net-aware, it is not part of the Net grouping. In addition, the Free grouping also includes: Component, Component Body, Room, and Polygon.
93ddb68554