JSON Queries

The new query language is still in development, so expect this to change.

You can read the original motivations to write this language here

Intro

Some characteristics to of this language to keep in mind:

• The data model of the "queried" is the same data model as the "query results". In most cases it will be Ifc2x3tc1 or Ifc4.
• The previous also explains why there are no aggregates (such as COUNT, AVG, MAX, etc. in SQL), because there is no place to store those.
• A query result is always a subset of the original model.
• Query language is probably not the best term here, a "filter language" might be better.
• The queries are based on objects. Geometry is not treated any other way. If you don't ask for geometry, you won't get it.

JSON

Few notes for the queries:

• All queries must be valid JSON. This means that all keys must be quoted, all strings must be quoted.
• When sending a query to BIMserver using the ServiceInterface.download method through JSON, ensure that your query is base64 encoded. For further information regarding downloading the data via queries, please check Downloading models
• field names in JSON queries are different from the field names in the IFC schema. For example, the field GlobalId in the IFC schema is called guid in the JSON query language.

Query structure

The base query retrieves all objects in the model without any filters.

{
}

There are three ways to start the query:

• Type (retrieving objects of a certain type)
• GUID (retrieving objects by unique global identifier)
• OID (retrieving objects by object ID)

Each query can be further extended with additional field or properties to access the attributes and properties of the objects.

Type query

This query will get all IfcWall objects

{
  "type": "IfcWall"
}

When your model for example only contains IfcWallStandardCase objects, this query will not return any objects, although IfcWallStandardCase is a subtype of IfcWall. To include subtypes, you have to explicitly define this:

{
  "type": "IfcWall",
  "includeAllSubtypes": true
}

You can also query multiple types, the next example would give you all IfcDoor and IfcWindow objects

{
  "types": ["IfcDoor", "IfcWindow"]
}

GUID query

When you already know the GUID(s) of (an) object(s), you can query those directly:

{
  "guid": "GUID1"
}  

or

{
  "guids": ["GUID1", "GUID2"]
}

OID query

The same as for GUIDs, you can also query by OID (ObjectID)

{
  "oid": 1523
}

or

{
  "oids": [1523, 2130, 898]
}

Properties

Every IFC object has a fixed set of fields. For example the IfcWindow has the fields "OverallWidth" and "OverallHeight" and many more. To use properties that are not defined in the schema, every object can be extended with more properties by adding them using IfcPropertySet and IfcProperty. For example IfcWall objects that are external can be queried via the property IsExternal in property set Pset_WallCommon:

{
  "type": "IfcWall",
  "includeAllSubtypes": true,
  "properties": {
    "Pset_WallCommon": {
      "IsExternal": true
    }
  }
}

Accessing tree structures

You can "walk" the tree in the object with include or includes and field to query the attribute. For example:

{
  "type": "IfcWall",
  "field": "ContainedInStructure",
  "include": {
    "type": "IfcRelContainedInSpatialStructure",
    "field": "RelatedElements"
  }
}

For all the IfcWall elements in the dataset, the query follows this process:

• It first checks the ContainedInStructure attribute of each IfcWall. This attribute references an instance of IfcRelContainedInSpatialStructure.
• From IfcRelContainedInSpatialStructure, it follows the RelatedElements attribute. This attribute contains a list of building elements.

You can also query multiple attributes at once:

{
  "type": {
    "name": "IfcBuildingStorey"
  },
  "includes": [
    {
      "type": "IfcBuildingStorey",
      "field": "IsDecomposedBy"
    },
    {
      "type": "IfcBuildingStorey",
      "field": "ContainsElements",
      "include": {
        "type": "IfcRelContainedInSpatialStructure",
        "field": "RelatedElements"
      }
    }
  ]
}

Using outputType or outputTypes you can specify the types of objects you want to retrieve. For example, the following query will return all IfcWindow and IfcWallStandardCase objects that are contained in a spatial structure:

{
"type": "IfcRelContainedInSpatialStructure",
"guid": "3kaWE7VBTEgBpPSELKvzcK",
"include":{
  "type": "IfcRelContainedInSpatialStructure",
  "field": "RelatedElements",
  "outputTypes": ["IfcWindow", "IfcWallStandardCase"]
  }
}

Serializing to IFC

In a lot of cases, the results of the query will be serialized as IFC. The previous examples would however not result in valid IFC files. For an IFC file to be valid, it not only has to solely contain objects that conform to the IFC schema, also certain references should always be included. For example every object must have an IfcOwnerHistory. Also there must always be an 1 IfcProject object.

Example of the body of an IFC file for the IfcWall query:

#1= IFCWALLSTANDARDCASE('1hmUg1hfv4UPf0UtHFe7ta',$,'SW - 009',$,$,$,$,'6BC1EA81-AE9E-4479-9A-40-7B744FA07DE4');
#2= IFCWALLSTANDARDCASE('05UYVl82vAa8mFc3FMTYL7',$,'SW - 010',$,$,$,$,'057A27EF-202E-4A90-8C-0F-9833D6762547');
#3= IFCWALLSTANDARDCASE('37ZZt1nzL2nu6PjSr0Wa2a',$,'SW - 011',$,$,$,$,'C78E3DC1-C7D5-42C7-81-99-B5CD408240A4');
#4= IFCWALLSTANDARDCASE('1EzyXtTtv7RAinwkFVr6_I',$,'SW - 012',$,$,$,$,'4EF7C877-777E-476C-AB-31-EAE3DFD46F92');
#5= IFCWALLSTANDARDCASE('08u2EMNSnBL8Izk3LNHAwK',$,'SW - 013',$,$,$,$,'08E02396-5DCC-4B54-84-BD-B8355744AE94');

Predefined includes queries

The above IFC file will not show anything in an IFC viewer because there are no geometric representation defined there, for example: project unit, 2D or 3D coordinates of the object, and its context. Therefore, in order to make queries easier with necessary information, a few predefined includes are available for the IFC versions supported in BIMserver. For every IFC schema, there is a respective standard library holding these predefined includes, for example ifc2x3-stdlib and ifc4-stdlib.

There are multiple predefined includes available for you to check out. Each include has a different function. Some common includes are: ifc4-stdlib:ContainedInStructure, ifc4-stdlib:OwnerHistory, ifc4-stdlib:Representation, ifc4-stdlib:ObjectPlacement, ifc4-stdlib:AllProperties, ifc4-stdlib:ContainsElements, and more.

To make the IfcWall example work in IFC4, this would be the new query:

{
  "type": "IfcWall",
  "includeAllSubtypes": true,
  "includes": [
    "ifc4-stdlib:ContainedInStructure",
    "ifc4-stdlib:OwnerHistory",
    "ifc4-stdlib:Representation",
    "ifc4-stdlib:ObjectPlacement"
  ]
}

Below are the descriptions of the predefined includes. Please note that you must specify the IFC version in the include name. For example, use ifc4-stdlib:ContainedInStructure for IFC4 and ifc2x3-stdlib:ContainedInStructure for IFC2x3.

stdlib: ContainedInStructure

ifc4-stdlib:ContainedInStructure will make sure all the spatial containment references "up" will be followed.
Example project structure:

IfcProject
  IfcSite
    IfcBuilding
      IfcBuildingStorey
        IfcSpace
          IfcWall

For each IfcWall encountered, the tree will be "walked" all the way up. This automatically includes the IfcProject which is a requirement for a valid IFC file

stdlib: OwnerHistory

For every IfcWall, the OwnerHistory will be included

stdlib: Representation

For every IfcWall, the Representation will be included. This can be a very large network/tree of objects. Representation is what gives object geometry in a viewer

stdlib: ObjectPlacement

This makes sure that all objects will also include their placement, which put's the object's geometry in the right place.

stdlib: AllProperties

This will make sure that all properties of an object are included.

Examples

Below are some examples of queries you can use. Additional examples can be found on BIMview.ws.

• Query an object with specific GUID, including its properties:

{
  "guid": "1s2y3MJjT8AuHONdaM2zhl",
  "include": "ifc2x3tc1-stdlib:AllProperties"
}

• Query a specific building storey, including all objects with their relations. The example below uses a Medical Dental Clinic project, which you can find here.

{
  "type": {
    "name": "IfcBuildingStorey"
  },
  "guid": "3eM8WbY_59RR5TDWs3wwJN",
  "includes": [
    {
      "type": "IfcBuildingStorey",
      "field": "IsDecomposedBy",
      "include": {
        "type": "IfcRelAggregates",
        "field": "RelatedObjects",
        "includes": [
          "ifc2x3tc1-stdlib:Representation",
          "ifc2x3tc1-stdlib:ObjectPlacement",
          "ifc2x3tc1-stdlib:AllProperties"
        ]
      }
    },
    {
      "type": "IfcBuildingStorey",
      "field": "ContainsElements",
      "include": {
        "type": "IfcRelContainedInSpatialStructure",
        "field": "RelatedElements",
        "includes": [
          "ifc2x3tc1-stdlib:Representation",
          "ifc2x3tc1-stdlib:ObjectPlacement",
          "ifc2x3tc1-stdlib:AllProperties",
          {
            "type": {
              "name": "IfcBuildingElement",
              "includeAllSubTypes": true
            },
            "field": "HasOpenings",
            "include":{
              "type": "IfcRelVoidsElement",
              "field": "RelatedOpeningElement",
              "includes": [
                {
                  "type": "IfcOpeningElement",
                  "field": "HasFillings",
                  "include": {
                    "type": "IfcRelFillsElement",
                    "field": "RelatedBuildingElement",
                    "includes":[
                      "ifc2x3tc1-stdlib:Representation",
                      "ifc2x3tc1-stdlib:ObjectPlacement",
                      "ifc2x3tc1-stdlib:AllProperties"
                    ]
                  }
                },
                "ifc2x3tc1-stdlib:Representation",
                "ifc2x3tc1-stdlib:ObjectPlacement"
              ]
            }
          },
          {
            "type": "IfcBuildingElement",
            "field": "IsDecomposedBy",
            "include":{
              "type": "IfcRelAggregates",
              "field": "RelatedObjects",
              "includes":[
                "ifc2x3tc1-stdlib:Representation",
                "ifc2x3tc1-stdlib:ObjectPlacement",
                "ifc2x3tc1-stdlib:AllProperties"
              ]
            }
          }
        ]
      }
    },
    "ifc2x3tc1-stdlib:Decomposes"
  ]
}