This article is part 4 of 11 in the series Python SQLAlchemy Tutorial

Last Updated: Wednesday 12th March 2014


In the previous article, we made a comparison between SQLAlchemy and other Python ORMs. In this article, we are going to take a deeper look at SQLAlchemy's ORM and Expression Language and use an example to showcase their empowering API and easy-to-understand Python structures.

Not only does the SQLAlchemy ORM provide a way to map database concepts into the Python space, it also provides a convenient Pythonic querying API. To find something in an SQLAlchemy database using ORM is pleasant, since everything is straightforward and the query results are returned as Python objects, as well as the query parameters.

The SQLAlchemy Expression Language provides a system for the programmers to write "SQL statements" using Python constructs. These constructs are modeled to resemble those of the underlying database as closely as possible, while hiding the difference between various database backends from the user. Although these constructs aim to represent equivalent concepts between backends with consistent structures, they do not conceal useful backend-specific features. Therefore, the Expression Language provides a way for the programmers to write backend-neutral expressions, while allowing the programmers to take advantage of specific backend features if they really want to.

The Expression Language complements the Object Relational Mapper. Whereas the ORM presents an abstracted pattern of usage mapping database concepts into Python's space, where models are used to map tables and relationships are used to map many-to-many through an association table and one-to-one through a foreign key, the Expression Language is used to directly represent more primitive constructs in a database without opinion.

An example with departments and employees

Let's use an example to illustrate how to use the expression language in a database with two tables department and employee. A department has many employees while an employee belongs to at most one department. Therefore, the database could be designed as follows:

In this example, we created a in-memory sqlite database with two tables 'department' and 'employee'. The column 'employee.department_id' is a foreign key to the column '' and the relationship 'department.employees' include all the employees in that department. To test our setup, we can simply insert several example records and query them using SQLAlchemy's ORM:

As you can see, we inserted one employee, john, into the IT department.

Now let's perform the same kind of query using the expression language:

Since the Expression Language provides lower-level Python structures that mimic a backend-neutral SQL, it feels almost identical to writing actual SQL but in a Pythonic way.

Many-to-many between the departments and the employees

In our previous example, it's simple that one employee belongs to at most one department. What if an employee could belong to multiple departments? Isn't one foreign key not enough to represent this kind of relationship?

Yes, one foreign key is not enough. To model a many-to-many relationship between department and employee, we create a new association table with two foreign keys, one to '' and another to ''.

In the previous example, we created an association table with two foreign keys. This association table 'department_employee' links 'department' and 'employee' and the relationships Department.employees and Employee.departments are to-many mapping between the tables. Notice the "magic-trick" to make this happen is the argument "secondary" we passed into the relationship() function in the Department and Employee model classes.

We can test our setup using the following queries:

Now let's insert one more employee and another department into the database:

To find all the employees in the IT department, we can write it in ORM:

Or the Expression Language:

Now let's assign employee marry into the IT department so that she will be part of two departments.

To find marry, i.e., all the employees who belong to at least two departments, we use group_by and having in an ORM query:

Similar to the ORM query, we can also use group_by and having in a Expression Language query:

Of course, always remember to close the database session when you're done.

Summary and Tips

In this article, we used an example database with two main tables and one association table to demonstrate how to write queries in SQLAlchemy's ORM and Expression Language. As a carefully designed API, writing queries is as easy as writing normal Python code. Since the Expression Language provides a lower-level API than the ORM, writing a query in the Expression Language feels more like writing one in a DBAPI such as psycopg2 and Python-MySQL. However, the lower-level API provided the Expression Language is more flexible than the ORM and its queries can be mapped into selectable SQL views in Python, which is very helpful as our queries become more and more complex. In the future articles, we are going to further explore how to utilize the Expression Language to make writing complex queries a joy instead of a pain.

About The Author

  • nueces

    There is a error in the seccond block of code

    >>> it.employees
    [] >> it.employees[0].name


    I think it must look somenthing like

    >>> it.employees
    [>> it.employees[0].name


    • odacharlee

      Yes looks like all the objects embraced in “” are missing, possibly due to html escape?