Learning ECSQL

This tutorial allows you to learn how to use ECSQL to read and query the business data in your iModels.

ECSQL is an implementation of SQL — a proven, well-adopted text-based command language. It adheres to standard SQL (SQL-92 and SQL-99) wherever possible.



In the course of the tutorial you will notice how similar ECSQL and SQL are. To not reinvent the wheel, this tutorial therefore expects you to be familiar with the basics of SQL. If you are new to SQL, please take a class on the SQL basics first.


The tutorial makes reference to the iModelConsole application to try out the ECSQL examples in the tutorial yourself and to experiment with your own ECSQL statements.

Sample iModel

The ECSQL examples in the tutorial work with a sample iModel.


The schemas for iModels are based on BIS. Therefore, the examples throughout the tutorial use the BIS schemas. While not required to learn ECSQL, familiarity with BIS is a good idea to get more from this tutorial.


The data in iModels can only be modified via the respective APIs. ECSQL is used to query the data from iModels. Therefore the tutorial only covers the query portion of ECSQL, i.e. ECSQL SELECT statements.

How to use the tutorial

The tutorial looks at typical questions and finds the respective ECSQL answer to it. The goal of the tutorial is that you can try out all ECSQL statements used in the lessons yourself. The tool to run the ECSQL statements is the iModelConsole with the tutorial's Sample iModel.

This also enables you to experiment more with ECSQL by modifying the tutorial's ECSQL statements or by trying out your own ECSQL statements.

Step 1 - Start the iModelConsole

  1. Launch the console
  2. Authenticate with your CONNECT credentials.

Step 2 - Open the sample iModel

Run this command:

.open -project:ECSQL

Step 3 - Run an ECSQL in the iModelConsole

Once you opened the iModel just type in the ECSQL (without a leading .) and hit Enter to execute it.

Try it yourself


SELECT count(*) ElementCount FROM bis.Element



Tutorial Overview

Next >

Last Updated: 05 June, 2020