Query Editor

The Query Editor is the window where you build a query in Simplebim. A query is a set of rules that picks objects out of the model — all walls whose Fire Rating is REI 60, everything on the third storey that is load bearing, every space whose name starts with "Office" — and it is how tools, dataflow steps and settings dialogs are told which objects to work on.

This article is about the editor: what the buttons, lists and boxes do and how to read the feedback it gives you. One of the rule types, Expression, opens the Expression Editor; that editor has its own article, Expression Editor, and what you can write in it is covered in Writing Expressions in Simplebim.

Where You Find the Query Editor

You do not open the Query Editor from a menu. It opens from a query setting in a configuration. Tools, dataflow steps and settings dialogs are configured with a list of settings, and a setting that takes a query shows two buttons.

Edit Query opens the Query Editor for this setting. While the setting has no query yet, the button reads Edit Query (empty).

Preview runs the query that is stored in the setting and selects the matching objects in the model, without opening the editor. Only shown while a model is open.

Click Edit Query. The editor opens in place of the list you came from, in the same window. A path at the top tells you where you are, for example

Query: Add or Modify Group

and two buttons, Apply Changes and Discard Changes, take you back. See Keeping or Discarding Your Changes.

The editor works on the model that is open: the property names, object classes, groups and values it offers in its lists all come from that model. Open the model you want to query before you open the editor.

The Editor at a Glance.

From top to bottom the editor has these parts:

Combination selector — a drop-down with All, Any and Advanced. Decides how the rules are combined.
Logic box — shows how the rules are combined, for example A AND B AND C. Read-only for All and Any; this is where you write your own logic when Advanced is chosen.
Preview — runs the query as it is now and selects the matching objects in the model.
The rules — one row per rule, lettered A, B, C … in the order they were added.
Add or Copy Rules — the button below the last rule. Opens the list of rule types.

Each rule row has the same frame around its own controls.

The letter at the left edge is the rule's identifier. It is also a check box: tick it to select the rule for copying.

The header shows the name of the rule type — Text Property, Object Class and so on.

× at the right end of the header removes the rule.

The rule's controls are below the header: the property, operator and value boxes described under The Rule Types.

How a Query Works

Every rule is a yes/no test on one object. A Text Property rule asks does this object's Name contain "wall"?, an Object Class rule asks is this object a wall or a slab?.
The combination decides how many rules an object has to pass. With All it has to pass every rule, with Any at least one, and with Advanced whatever logic you write, for example A AND (B OR C).
The query is run against the objects currently in the model. Objects that are filtered out of the model are not listed in the editor's value lists and are not selected by Preview.
A query can have at most 24 rules, lettered A to X. Trying to add a 25th shows Rule count exceeded. Maximum number of rules is 24.

The Query Editor does not run anything by itself. It builds the query; the tool or dialog you came from runs it when it needs the objects. Preview is the exception — it runs the query right away so you can see what it would select.

Adding a Rule

Click Add or Copy Rules below the rules and pick a rule type from the list that drops down. Each entry adds a rule that tests whether the object…

Add Object Class Rule — is one of the chosen object classes — walls, doors, spaces, storeys …

Add Object Group Rule — belongs to a group.

Add Text Property Rule — has a text property that equals, contains, starts with … a value.

Add Yes/No Property Rule — has a yes/no property set to Yes, to No, or left empty.

Add Number Property Rule — has a decimal number property that is equal to, greater than … a value.

Add Whole Number Property Rule — the same, for whole-number properties.

Add Measure Property Rule — has a measurement — a length, an area, a volume — that compares to a value in a unit of your choice.

Add Date Property Rule — has a date property that compares to a date.

Add Date and Time Property Rule — the same, for properties with a date and a time.

Add Time Of Day Property Rule — the same, for time-only properties.

Add Expression Rule — makes an expression give true.

The list also has Copy Selected Rules at the top, but only while at least one rule's letter is ticked. See Copying and Removing Rules.

The new rule appears at the end of the rules with the next free letter, and the list closes.

Which rule type to pick depends on the kind of data the property holds, not on how it looks. A door width stored as a measurement needs a Measure Property rule; a fire rating stored as text needs a Text Property rule, even when the text is 60. If you cannot find a property in a rule's property list, you have probably picked the wrong kind of rule — see Choosing the Property.

The Rule Types

Object Class

One drop-down list with check boxes. The list is in two groups:

Elements — walls, slabs, doors, pipes and every other building element class that has objects in the model, in alphabetical order.
Containers — Project, Site, Building, Building Storey and Space, when they are in the model.

Tick every class you want. An object passes the rule when it is any one of the ticked classes. Ticking a group heading ticks the whole group, and clearing it clears the whole group.

Only classes that actually have objects in the model are listed. To include a class that is not in the model — say, because the query will later run on other models — click the list button at the right end of the box and type the class names, one per line. Classes that are not in the model show up under a third heading, Not in Model, and are dropped from the list again when you untick them.

Ticking classes in an Object Class rule also narrows the other rules when the combination is All. See Object Class Rules Narrow the Other Rules.

Object Group

One box with the hint Select or type group name. Drop it down to pick one of the groups that have objects in the model, or start typing — the list narrows to the names that contain what you typed. You can also type the name of a group that does not exist yet; the rule then matches nothing until it does.

An object passes the rule when it belongs to the group. A saved query that refers to several groups at once shows them as one entry, List (3 items), and passes objects that belong to any of them.

Text Property

From left to right: the property, the operator, the case button and the value. The object passes when the property…

Equals — is exactly the value.

Contains — contains the value anywhere.

Starts With — begins with the value.

Ends With — ends with the value.

Like — matches a pattern with wildcards: ? stands for one character, * for any number of characters, # for one digit and [abc] for one of the listed characters. Basic Wall* matches every name that starts with Basic Wall.

Match — matches a regular expression.

Not Equal, Not Contains, Not Starts With, Not Ends With, Not Like, Not Match — the opposite of the operator above.

Three things about how the comparison is made:

Capitalisation is ignored unless you press the case button between the operator and the value. The button's icon changes to show that the comparison is now exact.
The Not… operators also pass objects that do not have the property at all. Name Not Contains "wall" selects the objects whose name lacks wall and the objects that have no name.
An empty value has a meaning. Equals with an empty value selects the objects whose property is empty or missing, and Not Equal with an empty value selects the objects that have any value at all. Contains, Starts With, Ends With, Like and Match never match an empty value.

The value box lists every distinct value the property has in the model. You can also type a value, compare against a whole list of values, or drop a name onto the box; all of that is described in Choosing the Value. With a list of values, Equals, Contains and the other positive operators pass an object that matches any of the values; the Not… operators pass an object that matches none of them.

Yes/No Property

The property and a value with three choices. The object passes when the property…

Yes — is Yes.

No — is No.

<no value> — has no value.

There is no operator to choose; the rule is always is equal to.

Number Property and Whole Number Property

The property, the operator and the value. The two rule types are the same apart from the properties they list: a Whole Number Property rule lists the properties that hold whole numbers, a Number Property rule those that hold decimal numbers. The object passes when the property is…

= — equal to the value.

≠ — different from the value — objects without a value pass too.

> ≥ < ≤ — greater than, at least, less than, at most the value — objects without a value never pass.

Write decimals with a dot: 3.5. The value box lists the values the property has in the model, and you can type your own or compare against a list of values, see Choosing the Value. With a list, = passes an object that equals any of the values, ≠ one that equals none, and the four relational operators pass an object only when the comparison holds against every value in the list.

Measure Property

The property, the operator, the value and the unit. The operators are the same as for a number property. The value is a single number; type it or pick one of the values the property has in the model.

The unit list fills in when you pick the property: it offers every unit of that property's kind — all length units for a length, all area units for an area — with the unit the model uses already selected. The value you type is read in the unit shown, and an object's measurement is converted to that unit before it is compared, so Height > 3 m and Height > 3000 mm select the same objects.

Measurements are rarely exactly equal to a round number. = and ≠ compare the numbers as they are, so for measured values ≥ and ≤, or a pair of > and < rules, are usually what you want.

Date, Date and Time, and Time of Day Property

The property, the operator and the value. The three rule types differ in the properties they list, in the operators they offer and in how the value is entered.

= ≠ > ≥ < ≤ — available for Date, Date and Time, and Time of Day.

Exists / Not Exists — the property has / does not have a value; the value box is ignored. Available for Date, Date and Time, and Time of Day.

Same Week, Same Month, Same Quarter, Same Year — in the same calendar week, month, quarter or year as the value. Available for Date, and Date and Time.

Same Hour, Same Day — available for Date and Time only.

The value box lists the values the property has in the model. You can also type a value, in the short date and time format of your Windows settings, or use the buttons at the right end of the box:

the calendar button (Date, Date and Time) opens a calendar to pick the date;
the clock button (Date and Time, Time of Day) opens a time editor with spin buttons; confirm with its OK button or cancel with its ×.

Every operator except Exists and Not Exists needs a value. If you leave the value empty, the rule quietly becomes Not Exists when the query is built and selects the objects that have no value. Check the value box if a date rule selects the wrong objects.

Expression

One box, with an fx button at its right end. Click fx to open the Expression Editor in place of the Query Editor; when you apply or discard there, you come back to the query with the expression in the box.

An expression in a query has to answer true or false — the object passes when the answer is true. [Length {mm}] > 8000 is a valid rule, [Length {mm}] is not, and the Expression Editor refuses it. The expression can use every property of every object in the model. See the Expression Editor article for the editor and Writing Expressions in Simplebim for what you can write.

Use an Expression rule for the tests the other rules cannot express: comparing two properties with each other, arithmetic, several conditions on one property, and so on. For a plain comparison with a value, the typed rules are easier to read and faster.

Choosing the Property

The Text, Yes/No, Number, Whole Number, Measure, Date, Date and Time and Time of Day rules all start with the same property list. Drop it down and pick a property, or start typing — the list suggests the names that match.

The list is not a list of every property in the model. It holds the properties that:

are of the kind the rule tests — text properties in a Text Property rule, lengths and areas in a Measure Property rule, and so on;
hold a single value per object. Properties that hold a list of values cannot be queried;
exist on objects that are currently in the model, and — when the combination is All and the query has Object Class rules — on objects of the ticked classes. See Object Class Rules Narrow the Other Rules.

When two properties have the same name but come from different property sets, both are listed with the property set in square brackets, for example Fire Rating [Pset_WallCommon] and Fire Rating [Pset_DoorCommon], so you can tell them apart.

When you open a saved query whose property is not in the model that is open, the property name is added to the list and selected, so nothing is lost. The rule selects nothing until it is run on a model that has the property.

Choosing the Value

The value box of a Text, Number, Whole Number and Measure rule works the same way:

Pick from the list. The box lists every distinct value that the chosen property has in the model, sorted. While no property is chosen, it lists the values of all properties of that kind. When there is exactly one value, it is selected for you.
Type a value. Anything you type is used as it is, whether or not it is in the list.
Compare against a list of values (Text, Number and Whole Number rules). Click the list button at the right end of the box. The List Editor opens in place of the Query Editor: type one value per line, or drag objects, classes or groups into it, and click Apply Changes. Back in the rule, the box reads List (5 items). Empty lines and duplicates are dropped, and spaces at the ends of a line are trimmed.
Drag and drop (Text rules). Drop an object class, a group or a group category from a palette onto the box and its name becomes the value.

What a list of values means is explained under each rule type: for Equals, Contains and the other positive text operators, and for =, an object passes when it matches any value; for the Not… operators and ≠ when it matches none; for >, ≥, < and ≤ the comparison has to hold against every value.

Object Class Rules Narrow the Other Rules

When the combination is All, the classes ticked in the query's Object Class rules narrow what the other rules offer:

the property lists only show properties that exist on objects of those classes;
the value lists only show values that objects of those classes have.

This is what makes the lists usable in a large model: tick Wall in an Object Class rule and a Text Property rule below it offers wall properties and wall values, not every text in the model.

The narrowing follows the Object Class rules as you edit them — tick another class and the lists grow, remove the Object Class rule and they go back to the whole model. A property you had already chosen stays chosen even when it is no longer in the narrowed list.

With Any or Advanced there is no narrowing, because an object can then pass the query without being one of the ticked classes. The lists show the whole model.

The narrowing only changes what the lists offer. It does not change what the rule tests — a Text Property rule still tests every object it is applied to.

Combining the Rules: All, Any and Advanced

The combination selector at the top left decides how the rules are put together, and the logic box next to it shows the result.

All — the logic box shows A AND B AND C. An object is selected when it passes every rule.

Any — the logic box shows A OR B OR C. An object is selected when it passes at least one rule.

Advanced — the logic box shows whatever you write. An object is selected when it passes the logic you wrote.

With All and Any the logic box is read-only and is rewritten for you whenever a rule is added or removed. With Advanced the box becomes editable and keeps the text it had, so the quickest way to write A AND (B OR C) is to set up the three rules under All, switch to Advanced and add the brackets.

Switching back from Advanced to All or Any throws your logic away and rewrites the box.

When you open a saved query, the editor picks the choice that fits it: All or Any for a flat query, Advanced — with the logic reconstructed in the box — for a query with nested logic.

Writing Advanced Logic

With the combination set to Advanced, write the logic in the logic box using the rules' letters, the words AND and OR, and brackets:

A AND B
A OR B OR C
A AND (B OR C)
(A AND B) OR (C AND D)
A AND NOT B          ← not allowed: there is no NOT

The rules of the little language:

Letters name rules. Only the letters of rules that exist are allowed. Small letters work the same as capitals, and so do and and or.
Put spaces around AND and OR. A AND B is right; AAND B is read as a rule called AAND. Brackets do not need spaces: (A AND B)OR C is fine.
AND binds tighter than OR. A OR B AND C means A OR (B AND C). When in doubt, use brackets.
There is no NOT. To exclude objects, use a rule with a negative operator — Not Contains, ≠, Not Exists — instead.
A rule you do not mention is not part of the query. With rules A, B and C and the logic A AND B, rule C is ignored. You can also mention a rule more than once.
An empty logic box means an empty query. Preview then does nothing and Apply Changes stores no query at all.

Checking the Logic

The logic is checked about half a second after you stop typing. When it is wrong, a message appears under the box while the cursor is in it; click elsewhere and the message hides, click back into the box and it shows again. When the logic is right, the message disappears.

The messages and what is wrong:

There are no rules defined. The query has no rules yet. Add a rule first.

Unexpected identifier 'X' found at position 4. Only rule identifiers A-C are allowed. X is not the letter of a rule. Either the rule was removed, or two words ran together, like AAND.

Token of type 'Operator' cannot be the first token in an expression. The logic starts with AND or OR.

Token of type 'Operator' cannot be the last token in an expression. The logic ends with AND or OR.

Token of type 'Rule identifier' at position 2 cannot occur after token type 'Rule identifier'. Two letters follow each other without AND or OR between them — A B. The same message with other token types means an AND after an AND, a letter right after a ), and so on.

Not all parentheses are closed. A ( has no ).

Unexpected token ')' found at position 5. A ) has no ( before it.

Positions count characters from the start of the box, starting at 0.

The check only looks at the shape of the logic — whether it can be read — not at whether it selects anything. A logic that reads fine can still select nothing; use Preview to see.

Copying and Removing Rules

Copying Rules

Tick the letter of every rule you want to copy. The letter at the left edge of a rule row is a check box.
Click Add or Copy Rules and choose Copy Selected Rules — it is the first entry, and only there while a rule is ticked.

The copies are added at the end, with new letters, and the ticks are cleared. A copy is independent of its original: change one and the other stays as it was. Copying is the fast way to make a second rule on the same property with a different value.

Removing a Rule

Click the × at the right end of the rule's header. The rule disappears and the rules below it move up one letter: remove B out of A, B, C, D and the old C becomes B and the old D becomes C.

Under All and Any the logic box is simply rewritten. Under Advanced the logic is rewritten to match:

every mention of the removed rule is dropped, and the brackets are simplified where that leaves a bracket with one rule in it — A AND (B OR C) without B becomes A AND C;
the letters after the removed one are shifted down — A AND (B OR C) without A becomes A OR B;
if the logic was not valid at the time — the box was salmon — only the letters are shifted and nothing else is touched, so read the logic again afterwards.

There is no undo. If you removed the wrong rule, Discard Changes brings back the query as it was when you opened the editor, together with everything else you changed since.

Previewing the Query

A query that is built correctly is not necessarily the right query. Preview, at the top right, builds the query from the rules as they are now, runs it against the model and selects the matching objects — in the 3D view and in every palette that shows the selection. Whatever was selected before is replaced; when nothing matches, the selection becomes empty.

Preview changes nothing else. The query is not stored, and the objects are only selected, not changed, so you can preview as often as you like while you adjust the rules.

Preview needs at least one rule, and under Advanced a valid, non-empty logic; otherwise nothing happens. When a rule cannot be turned into a query — a value that is not a number, for example — a message names the rule, Error in rule B, and says what is wrong. Fix it and click Preview again.

Keeping or Discarding Your Changes

The editor opens in place of the list you came from, and the two buttons above it take you back.

Apply Changes — the query built from the rules replaces the one in the setting.

Discard Changes — the setting keeps the query it had.

Two things to know:

Apply Changes stores whatever can be built. If nothing can be built — there are no rules, the Advanced logic is empty, or a rule reports an error — the setting is emptied and the button in the configuration reads Edit Query (empty). If you want to keep the query that was there, click Discard Changes instead. Clicking Preview first is the easy way to find out which of the two you are about to get.
Applying the query puts it back into the configuration; it does not save the configuration itself. Saving happens where it always does, when you finish with the tool or dialog.

The stored query keeps the rules, their letters and the combination. The next time you click Edit Query the editor shows them again as you left them — with one exception: a query with more than 24 rules, which can only come from outside the editor, is cut to the first 24.

Troubleshooting

The property is in the model but not in the rule's property list.
Check three things. The rule type has to match the kind of data — a number stored as text only appears in a Text Property rule, a length only in a Measure Property rule. Properties that hold a list of values are never listed. And when the combination is All and the query has an Object Class rule, the list only shows properties of the ticked classes; tick the right class or switch the combination to Any to see the whole model.

The value list is empty.
Either no property is chosen, or no object in the model — or, under All with an Object Class rule, no object of the ticked classes — has a value for it. You can still type a value.

The object class I want is not in the Object Class list.
Only classes that have objects in the model are listed. Click the list button at the right end of the box and type the class name; it appears under Not in Model and is kept in the query.

Preview selects nothing.
Work through the rules one at a time: set the combination to Any, or write a single letter in the Advanced logic, and preview each rule alone. The usual causes are All where Any was meant, a text value with different capitalisation while the case button is pressed, a date rule with an empty value (it has become Not Exists), a measure compared with = that is never exactly equal, and a value typed in the wrong unit.

Preview selects too much.
Remember that the Not… text operators and ≠ also select objects that have no value for the property. Combine the rule with a rule that requires the property to exist — Not Equal with an empty value for a text property — under All.

The logic box is salmon and says "Unexpected identifier".
The letter is not a rule, or a space is missing: AAND B is read as one word. Compare with the letters of the rules and put spaces around AND and OR.

The logic box is salmon although the logic looks right.
Read the message under the box — it hides when the cursor leaves the box, so click into the box to see it. Look for a missing ), for an AND or OR at the very end, and for two letters with nothing between them.

The rules have different letters than before.
A rule was removed and the ones below it moved up. Under Advanced the logic was rewritten to match; check that it still says what you meant.

I clicked Apply Changes and the setting now says "Edit Query (empty)".
Nothing could be built — the query had no rules, the Advanced logic was empty, or a rule reported an error that was dismissed. The previous query is gone. Open the editor again and rebuild it, and next time click Preview before Apply Changes.

Copy Selected Rules is not in the Add or Copy Rules list.
No rule is ticked. Tick the letter at the left edge of a rule first.

A message says "Rule count exceeded. Maximum number of rules is 24."
That is the limit. Combine rules where you can — a list of values in one Text Property rule instead of one rule per value, or an Expression rule for several conditions on one property.

The date rule selected the objects with no value instead of the ones I wanted.
The value box was empty, so the rule became Not Exists. Pick or type a date.

The unit list of a Measure Property rule is empty.
Pick the property first; the units are listed for the property's kind of measurement.