Selector syntax#

A common task in querying IFC models is to filter or search for elements which match particular criteria. For example, you might want to find all plasterboard walls with a 2 hour fire rating on level 3.

Alternatively, you might want to fetch some data about a single element. For example, you might want to fetch the fire rating property of an element, or the type description of an element, or the net volume of a list of elements.

Once you’ve retreived your data, you might want to format it in some way. You might want to ensure that all names are always uppercase. Or you might want to take length values defined in feet, and apply imperial formatting such that it shows both feet and inches including fractions.

These three usecases of filtering, getting a value, and formatting that value are common and used in many utilities, such as in the BlenderBIM Add-on, IfcCSV, IfcDiff, IfcClash, IfcPatch, and IfcFM.

IfcOpenShell provides a custom syntax to consistently and concisely describe filters, value queries, and formatting rules.

Filtering elements#

Filtering is typically used to select any IFC element or type.

import ifcopenshell
import ifcopenshell.util.selector

model = ifcopenshell.open("model.ifc")
# Get all concrete walls and slabs.
ifcopenshell.util.selector.filter_elements(model, "IfcWall, IfcSlab, material=concrete")

Example Query

Description

IfcElement

All physical IfcElements including subclasses like walls, doors, windows, etc. Yep, that’s it! Nothing else. Literally just IfcElement.

IfcWall, IfcSlab

All walls and slabs. Technically, this is either a wall or a slab, but it’s easier to describe it as all walls and slabs

IfcWall, IfcSlab, material=concrete

All walls made out of concrete and slabs made out of concrete. The material checks any assigned IfcMaterial with a matching name or category attribute.

325Q7Fhnf67OZC$$r43uzK

A single element. Yep, just the GlobalId, nothing else! Easy.

325Q7Fhnf67OZC$$r43uzK, 2VlJ7nbF5AFfQQuRvSWexT

A bunch of arbitrary elements.

IfcWall, ! 325Q7Fhnf67OZC$$r43uzK

All walls except that one element.

IfcElement, ! IfcWall

All elements except for walls.

IfcDoor, Name=D01

Any doors named D01, notice how attributes match the IFC Attribute naming exactly

IfcDoor, Name=/D[0-9]{2}/

Any doors with the naming scheme of D followed by two numbers:

IfcWall, Pset_WallCommon.FireRating=2HR

Any 2 hour fire rated wall

IfcWall, IfcColumn, IfcBeam, IfcFooting, /Pset_.*Common/.LoadBearing=TRUE

Any load bearing structure

IfcElement, /Pset_.*Common/.FireRating != NULL

Any element with a fire rating property

IfcWall, type=WT01, location="Level 3"

Any walls of wall type WT01 on level 3 (we quote Level 3 since it has a space)

IfcElement, classification=/Pr_.*/

Any maintainable product according to Uniclass tables

IfcWall, IfcSlab, ! 325Q7Fhnf67OZC$$r43uzK, material=concrete, /Pset_.*Common/.FireRating=2HR

Notice how there are intuitive rules that class and instance filters are OR whereas other filters are AND So here is any wall or slab except that one element that has a material of concrete and has a 2 hour fire rating

IfcSlab, material=concrete + IfcDoor

Finally, you can union facet lists together. So here is all concrete slabs, as well as all doors (regardless of concrete)

IfcDoor, IfcWindow + IfcWall, IfcSlab, material=concrete + 325Q7Fhnf67OZC$$r43uzK

Here’s another example of unioning facet groups. All doors and window, and all concrete walls and slabs, plus that one random element

IfcPump, location="Level 3"

Locations bubble up the hierarchy. So if a pump is in a space and that space is on Level 3, then you can say “all pumps on level 3” which will include that pump in the space.

The filter elements syntax works by specifying one or more groups of filters separated by a + character. Each filter group will return a set of filtered elements, and these are unioned together.

filter_group[ + filter_group]*

A filter group consists of one or more filters separated by a , character. The filters are chained and apply from left to right.

filter[, filter]*

There are nine types of filters to choose from. Some of these filters will add new elements to your filter group, and some will filter previously added elements in your filter group based on their criteria.

Filter

Type

Usage

Example

Class

Add

[!] {{ifc_class_name}}

IfcWall adds all IfcWall elements and their subclasses. ! IfcWall subtracts all non-IfcWall elements from the filter group.

GlobalId

Add

[!] {{global_id}}

325Q7Fhnf67OZC$$r43uzK adds the single element with that GlobalId attribute. ! 325Q7Fhnf67OZC$$r43uzK subtracts that single element.

Attribute

Filter

{{name}}{{=}}{{value}}

Name=Foo specifies the criteria that elements must have a Name attribute with a value of Foo. Attribute names must be spelled exactly the same as in IFC, which means that they must start with an uppercase character.

Property

Filter

{{pset}}.{{prop}}{{=}}{{value}}

Pset_WallCommon.FireRating=2HR specifies the criteria that elements must have a Pset_WallCommon property set, with a FireRating property within it with a value of 2HR. The property set name and the property name are separated by a ..

Type

Filter

type{{=}}{{value}}

type=Foo specifies the criteria that elements must have a type which has a Name attribute with a value of Foo.

Material

Filter

material{{=}}{{value}}

material=Foo specifies the criteria that elements must have a IfcMaterial assigned directly or indirectly (such as within a layer set). That IfcMaterial must have either a Name or Category attribute with a value of Foo.

Classification

Filter

classification{{=}}{{value}}

classification=Foo specifies the criteria that elements must have an IfcClassificationReference with an Identification attribute with a value of Foo.

Location

Filter

location{{=}}{{value}}

location=Foo specifies the criteria that elements must be contained directly or indirectly in a spatial element with a Name attribute with a value of Foo.

Query

Filter

query:{{keys}}{{=}}{{value}}

query:types.count=0 specifies the criteria that elements must have zero type occurrences. The query keys corresponds to the syntax used in the Getting element values section

When you specify a filter with a {{=}} check, you can choose from one of the following comparison checks:

Comparison

Description

=

Must equal the value. The data type of the value is automatically converted to match.

!=

Must not equal the value.

>

Must be greater than the value.

>=

Must be greater than or equal to the value.

<

Must be less than the value.

<=

Must be less than or equal to the value.

When you specify a {{pset}}, {{prop}}, or {{value}}, there are three ways you can do so:

Value Type

Example

Description

Quoted string

"foo \"bar\" baz"

The value must be in double quotes. The value may contain spaces, symbols, and other characters. If you need to use a double quote, you can escape it with a backslash. This is the safest, most general way to specify a value.

Unquoted string

foobarbaz

For convenience, if you have a simple value which contains no spaces or special characters, you are free to specify it as an unquoted string.

Regex string

/foo.*baz/

You may specify a Python-compatible regex pattern delimited by forward slashes.

Getting element values#

Given a single element, this syntax provides a simple way to extract a value without needing to write complex code for it.

import ifcopenshell
import ifcopenshell.util.selector

# Get the Name attribute of the wall's type.
ifcopenshell.util.selector.get_element_value(wall, "type.Name")

Example Query

Description

class

Get the IFC class of the element.

Name

Get the Name attribute.

Pset_WallCommon.Status

Get the value of the Status property in the Pset_WallCommon property set.

/Pset_.*Common/.Status

Get the value of the Status property in the any common property set.

type.Name

Get the Name attribute of the element’s relating type.

types.count

Count the number of occurrences of a type.

storey.Name

Get the Name attribute of the storey that the element is contained in.

materials.count

Count the number of materials assigned to an element.

material.Name

Get the name of the assigned material.

material.item.0.Name

Get the name of the first item in a material set (e.g. the first material layer)

The element value syntax works by specifying one or more query keys separated by a . character. Each query key returns data based of the results of the previous key.

key[.key]*

Valid keys are:

Key

Description

id

Gets the IFC ID (equivalent to .id())

class

Gets the IFC class (equivalent to .is_a())

predefined_type

Gets the predefined type of the element, taking into account inheritance.

{{attribute}}

Gets the value of the attribute you specify. Attributes always start with an uppercase letter.

{{pset}}

This gets the property set with the same name specified in {{pset}}. Note that this can be ambiguous with {{attribute}}. If there is an ambiguity, {{attribute}} takes priority.

{{prop}}

If the previous key returns a property set, {{prop}} gets the value of a property with the same name specified in {{prop}}. For this reason, often you specify both keys together, like this: {{pset}}.{{prop}}.

type

Gets the relating type of an element occurrence.

types or occurrences

Gets the related objects of an element type.

container

Gets the immediate spatial element that an element is contained in.

space

Gets the first IfcSpace spatial element that an element is contained in.

storey

Gets the first IfcBuildingStorey spatial element that an element is contained in.

building

Gets the first IfcBuilding spatial element that an element is contained in.

site

Gets the first IccSite spatial element that an element is contained in.

material or mat

Gets the assigned material, which may be a material set.

item or i

If the previous key returns a material set, gets the relevant material set items

materials or mats

Gets a list of IfcMaterials assigned directly or indirectly (such as via a material set) to the element

x

Gets the X coordinate of the element’s placement

y

Gets the Y coordinate of the element’s placement

z

Gets the Z coordinate of the element’s placement

easting

Gets the map easting of the element’s placement

northing

Gets the map northing of the element’s placement

elevation

Gets the map elevation of the element’s placement

count

If the previous key returns multiple things, count that list. Otherwise, return 1.

{{number}}

If the previous key returns multiple things, fetch the {{number}} index (e.g. 0, 1, 2, 3, etc) item in that list.

When you specify a {{pset}} or {{prop}}, there are three ways you can do so:

Value Type

Example

Description

Quoted string

"foo \"bar\" baz"

The value must be in double quotes. The value may contain spaces, symbols, and other characters. If you need to use a double quote, you can escape it with a backslash. This is the safest, most general way to specify a value.

Unquoted string

foobarbaz

For convenience, if you have a simple value which contains no spaces or special characters, you are free to specify it as an unquoted string.

Regex string

/foo.*baz/

You may specify a Python-compatible regex pattern delimited by forward slashes.

Formatting#

Given a value, this syntax allows a simple way to specify a set of formatting rules. This is useful for configuring outputs of how data should be presented.

import ifcopenshell
import ifcopenshell.util.selector

# Get the Name attribute of the wall's type.
value = ifcopenshell.util.selector.get_element_value(wall, "type.Name")
# Always display names in uppercase.
ifcopenshell.util.selector.format(f'upper("{value}")')

Formatting queries are written similar to how you’d write functions or formulas in spreadsheets. For example upper("foo") will produce FOO. You may nest formulas, for example concat(title("foo"), lower("Bar")) will produce Foobar. Strings must be double quoted.

Function

Example

Result

Description

upper({{value}})

upper("Foo")

FOO

Uppercases a string.

lower({{value}})

lower("Foo")

foo

Lowercases a string.

title({{value}})

title("foo")

Foo

Titlecases a string.

concat({{value}}[, {{value2}}]*)

concat("foo", "bar")

foobar

Concatenates two or more strings.

round({{value}}, {{precision}})

round(3.123, 0.1)

3.1

Rounds {{value}} to the nearest {{precision}}.

metric_length({{value}}, {{precision}}, {{decimals}})

metric_length(3.123, 0.1, 2)

3.10

Rounds {{value}} to the nearest {{precision}} then displays using a certain amount of decimal places.

imperial_length({{value}}, {{precision}}, {{unit}})

imperial_length(3.22, 4, "foot")

3' - 3 3/4"

Rounds {{value}} to the nearest 1/{{precision}} inch then displays using fractional feet and inches. The {{value}} may be specified either as foot or inch depending on {{unit}}.