iModels for Developers

This page gives a developer-oriented overview of iModels: what they are, how they are structured, and how iTwin.js exposes them.

Overview

The Data

iModels are designed to store BIM/CAD Engineering data in a format that is ideal for editing applications. It standardizes the data stored so common concepts are represented the same way across different editing applications. This standardization is accomplished using a 'conceptual schema' called BIS that expresses taxonomy, data structure and relationships for modeling real-world Entities.

The File

Under the hood, an iModel is a standard SQLite file. Two standard SQLite extensions are used to create a change history and ease working with large files.

• The Session Extension to record changes to the database and package them into 'changesets'
• The Cloud Backed SQLite VFS to allow access to the database without first downloading the entire database.

The Tables

While iModels physically store data using a SQL persistence schema, they expose that data as BIS entities. The ECSQL language allows you to use SQL syntax to query data in an iModel based on its conceptual schema rather than in terms of the underlying database structure. The data tables in an iModel are defined by the imported BIS schemas. Additionally, the database includes metadata tables that store these schemas and define how the persistence layer maps to the logical layer.

BIS Basics

Base Infrastructure Schemas (BIS) is an open source ecosystem of modular and coordinated schemas. The BisCore schema defines the foundational data model of an iModel, and all other schemas derive from the base classes BisCore defines. BisCore defines Elements as the primary data-carrying entities and Models which contain Elements. Elements may also be extended via ElementAspects which can store additional data and are considered conceptually to be part of the Element. Individual Elements are connected via Relationships, which can also store data, to build assemblies, systems, networks, hierarchies or other arbitrary connections.

BIS enables modeling real world objects from multiple Perspectives. Different Elements are used to represent the real world object in each perspective. For example, a pump can have a functional perspective defining the requirements of a functional pump (e.g. flow rate or pressure), a physical perspective defining the pump location in space (e.g. location, geometry, materials), and an analytical perspective defining the attributes needed for flow simulation.

Change History and Versioning

iModels are stored as a seed SQLite file plus a sequence of SQLite changesets making a linear and immutable change history. Thus, it is always possible to recreate a version of an iModel by applying changesets in order up to the revision desired.

The change history can be managed via the iModels API and enables operations like Forks and Clones.

Editing

To edit an iModel as a standalone SQLite file and produce no change history, use a SnapshotDb. To produce a change history, the iModel must be managed by the iModel Hub using the iModel APIs mentioned above. When managed by the Hub, the user is able to checkout a Briefcase and use Locks on elements to avoid data conflicts.

Under the default pessimistic concurrency policy, locks are required before modifying an Element. An iModel can instead use an optimistic policy (noLocks: true) that allows editing without locks and reconciles conflicts through merging; see Concurrency Control. Briefcases ensure Element ids are unique by appending a briefcase id to the sequential id specified for the next element.

As multiple users edit an iModel, they will push changesets with their changes and pull in changesets with others' changes. A briefcase must be at the tip of the change history to push a changeset. If it is not, incoming changesets need to be pulled, and local changes are merged with them. Once conflicts are resolved, the local changes are pushed as one or more changesets.

Forks create an independent copy of the change history, creating an iModel which can be edited independently from the source iModel. Changes must be merged back using iModel Transformation which works at the BIS Element level rather than with SQLite changesets.

Code Basics

The ECDb library underpins the iModel file format and uses ECSchemas as its data modeling language. ECSchemas can be represented in XML or JSON and loaded using TypeScript (ecschema-metadata) or C++ (ECObjects) libraries. The C++ iModelPlatform layer adds basic logic that understands and enforces BisCore concepts. This internal API is exposed to TypeScript via a N-API interface consumed by the iTwin.js core-backend package. In TypeScript, BriefcaseDb and SnapshotDb from @itwin/core-backend are the primary entry points for working with iModels.