Graph Model¶

This page describes the Neo4j graph structure created by ifc-graph. Understanding this model is essential for writing effective Cypher queries.

Overview¶

The graph model represents IFC building elements and their relationships in a property graph format suitable for Neo4j.

┌─────────────┐      CONTAINS       ┌─────────────┐
│   Project   │─────────────────────│   Element   │
└─────────────┘                     └─────────────┘
                                           │
                                           │ HAS_MATERIAL
                                           ▼
┌─────────────┐      CONTAINS       ┌─────────────┐
│  Structure  │─────────────────────│   Material  │
└─────────────┘                     └─────────────┘
       │
       │ (spatial hierarchy)
       ▼
┌─────────────┐
│  Metadata   │
└─────────────┘

Node Types¶

Project¶

The root node representing the IFC project.

Label: Project

Properties:

Property	Type	Description
`id`	String	Unique IFC entity ID
`name`	String	Project name
`type`	String	Always "IfcProject"
`description`	String	Project description
`phase`	String	Project phase

Example Query:

MATCH (p:Project) RETURN p

Element¶

Building elements extracted from the IFC file (walls, doors, windows, etc.).

Label: Element

Properties:

Property	Type	Description
`id`	String	Unique IFC entity ID
`name`	String	Element name
`guid`	String	IFC GlobalId (UUID)
`type`	String	IFC type (e.g., "IfcWall", "IfcDoor")
`object_type`	String	Object type/family name
`description`	String	Element description
`tag`	String	Element tag/mark

Example Query:

// Find all walls
MATCH (e:Element)
WHERE e.type = 'IfcWall'
RETURN e.name, e.guid

Structure¶

Spatial structure elements (sites, buildings, storeys, spaces).

Label: Structure

Properties:

Property	Type	Description
`id`	String	Unique IFC entity ID
`name`	String	Structure name
`type`	String	IFC type (e.g., "IfcBuildingStorey")
`long_name`	String	Long name/description
`elevation`	Float	Elevation (for storeys)

Example Query:

// Find all storeys with their elevations
MATCH (s:Structure)
WHERE s.type = 'IfcBuildingStorey'
RETURN s.name, s.elevation
ORDER BY s.elevation

Material¶

Materials associated with building elements.

Label: Material

Properties:

Property	Type	Description
`id`	String	Unique IFC material ID
`name`	String	Material name
`category`	String	Material category

Example Query:

// Find all unique materials
MATCH (m:Material)
RETURN DISTINCT m.name, m.category

Metadata¶

Import metadata node created for each import operation.

Label: Metadata

Properties:

Property	Type	Description
`timestamp`	String	Import timestamp
`count`	Integer	Number of elements imported
`types`	String	Comma-separated element types
`ifc_file`	String	Source IFC filename
`duration`	Float	Import duration in seconds

Example Query:

MATCH (m:Metadata)
RETURN m.timestamp, m.count, m.duration
ORDER BY m.timestamp DESC

Relationships¶

CONTAINS (Project to Element)¶

Links the project to all building elements.

(:Project)-[:CONTAINS]->(:Element)

Example Query:

// Count elements in project
MATCH (p:Project)-[:CONTAINS]->(e:Element)
RETURN p.name, count(e) as element_count

CONTAINS (Structure to Element)¶

Links spatial structures to the elements they contain.

(:Structure)-[:CONTAINS]->(:Element)

Example Query:

// Find all elements on each storey
MATCH (s:Structure)-[:CONTAINS]->(e:Element)
WHERE s.type = 'IfcBuildingStorey'
RETURN s.name, collect(e.name) as elements

HAS_MATERIAL¶

Links elements to their materials.

(:Element)-[:HAS_MATERIAL]->(:Material)

Example Query:

// Find elements with concrete materials
MATCH (e:Element)-[:HAS_MATERIAL]->(m:Material)
WHERE m.name CONTAINS 'Concrete'
RETURN e.type, e.name, m.name

Common Query Patterns¶

Count Elements by Type¶

MATCH (e:Element)
RETURN e.type, count(e) as count
ORDER BY count DESC

Find Elements on a Specific Storey¶

MATCH (s:Structure {name: 'Level 1'})-[:CONTAINS]->(e:Element)
RETURN e.type, e.name

Find All Elements Using a Material¶

MATCH (e:Element)-[:HAS_MATERIAL]->(m:Material {name: 'Concrete'})
RETURN e.type, e.name

Get Building Hierarchy¶

MATCH path = (p:Project)-[:CONTAINS]->(e:Element)<-[:CONTAINS]-(s:Structure)
RETURN p.name, s.name, s.type, e.name, e.type
LIMIT 100

Find Elements Without Materials¶

MATCH (e:Element)
WHERE NOT (e)-[:HAS_MATERIAL]->()
RETURN e.type, e.name

Count Elements per Storey¶

MATCH (s:Structure)-[:CONTAINS]->(e:Element)
WHERE s.type = 'IfcBuildingStorey'
RETURN s.name, s.elevation, count(e) as element_count
ORDER BY s.elevation

Find Most Common Materials¶

MATCH (e:Element)-[:HAS_MATERIAL]->(m:Material)
RETURN m.name, count(e) as usage_count
ORDER BY usage_count DESC
LIMIT 10

Elements by Type and Storey¶

MATCH (s:Structure)-[:CONTAINS]->(e:Element)
WHERE s.type = 'IfcBuildingStorey'
RETURN s.name, e.type, count(e) as count
ORDER BY s.elevation, e.type

Graph Visualization¶

To visualize the graph in Neo4j Browser:

View All Node Types¶

CALL db.schema.visualization()

Sample of the Graph¶

MATCH (n)
OPTIONAL MATCH (n)-[r]->(m)
RETURN n, r, m
LIMIT 100

View Element Distribution¶

MATCH (e:Element)
RETURN e.type as Type, count(*) as Count
ORDER BY Count DESC

Performance Tips¶

Create Indexes¶

For better query performance, create indexes on frequently queried properties:

// Index on Element type
CREATE INDEX element_type IF NOT EXISTS FOR (e:Element) ON (e.type)

// Index on Element guid
CREATE INDEX element_guid IF NOT EXISTS FOR (e:Element) ON (e.guid)

// Index on Structure type
CREATE INDEX structure_type IF NOT EXISTS FOR (s:Structure) ON (s.type)

// Index on Material name
CREATE INDEX material_name IF NOT EXISTS FOR (m:Material) ON (m.name)

Use PROFILE for Query Analysis¶

PROFILE
MATCH (e:Element)-[:HAS_MATERIAL]->(m:Material)
WHERE e.type = 'IfcWall'
RETURN e.name, m.name

Schema Diagram¶

                    ┌──────────────────────┐
                    │       Project        │
                    │──────────────────────│
                    │ id: String           │
                    │ name: String         │
                    │ type: String         │
                    │ description: String  │
                    │ phase: String        │
                    └──────────┬───────────┘
                               │
                               │ CONTAINS
                               ▼
┌───────────────────┐     ┌──────────────────────┐     ┌───────────────────┐
│     Structure     │     │       Element        │     │     Material      │
│───────────────────│     │──────────────────────│     │───────────────────│
│ id: String        │     │ id: String           │     │ id: String        │
│ name: String      │ ──► │ name: String         │ ──► │ name: String      │
│ type: String      │     │ guid: String         │     │ category: String  │
│ long_name: String │     │ type: String         │     └───────────────────┘
│ elevation: Float  │     │ object_type: String  │
└───────────────────┘     │ description: String  │
     CONTAINS             │ tag: String          │
                          └──────────────────────┘
                                    ▲
                                    │ HAS_MATERIAL

┌──────────────────────┐
│      Metadata        │
│──────────────────────│
│ timestamp: String    │
│ count: Integer       │
│ types: String        │
│ ifc_file: String     │
│ duration: Float      │
└──────────────────────┘

Graph Model¶

Overview¶

Node Types¶

Project¶

Element¶

Structure¶

Material¶

Metadata¶

Relationships¶

CONTAINS (Project to Element)¶

CONTAINS (Structure to Element)¶

HAS_MATERIAL¶

Common Query Patterns¶

Count Elements by Type¶

Find Elements on a Specific Storey¶

Find All Elements Using a Material¶

Get Building Hierarchy¶

Find Elements Without Materials¶

Count Elements per Storey¶

Find Most Common Materials¶

Elements by Type and Storey¶

Graph Visualization¶

View All Node Types¶

Sample of the Graph¶

View Element Distribution¶

Performance Tips¶

Create Indexes¶

Use PROFILE for Query Analysis¶

Schema Diagram¶

See Also¶