Select using Query Builder

What is QueryBuilder

QueryBuilder is one of the most powerful features of TypeORM - it allows you to build SQL queries using elegant and convenient syntax, execute them and get automatically transformed entities.
Simple example of QueryBuilder:
1
const firstUser = await connection
2
.getRepository(User)
3
.createQueryBuilder("user")
4
.where("user.id = :id", { id: 1 })
5
.getOne();
Copied!
It builds the following SQL query:
1
SELECT
2
user.id as userId,
3
user.firstName as userFirstName,
4
user.lastName as userLastName
5
FROM users user
6
WHERE user.id = 1
Copied!
and returns you an instance of User:
1
User {
2
id: 1,
3
firstName: "Timber",
4
lastName: "Saw"
5
}
Copied!

Important note when using the QueryBuilder

When using the QueryBuilder, you need to provide unique parameters in your WHERE expressions. This will not work:
1
const result = await getConnection()
2
.createQueryBuilder('user')
3
.leftJoinAndSelect('user.linkedSheep', 'linkedSheep')
4
.leftJoinAndSelect('user.linkedCow', 'linkedCow')
5
.where('user.linkedSheep = :id', { id: sheepId })
6
.andWhere('user.linkedCow = :id', { id: cowId });
Copied!
... but this will:
1
const result = await getConnection()
2
.createQueryBuilder('user')
3
.leftJoinAndSelect('user.linkedSheep', 'linkedSheep')
4
.leftJoinAndSelect('user.linkedCow', 'linkedCow')
5
.where('user.linkedSheep = :sheepId', { sheepId })
6
.andWhere('user.linkedCow = :cowId', { cowId });
Copied!
Note that we uniquely named :sheepId and :cowId instead of using :id twice for different parameters.

How to create and use a QueryBuilder

There are several ways how you can create a Query Builder:
    Using connection:
    1
    import {getConnection} from "typeorm";
    2
    ​
    3
    const user = await getConnection()
    4
    .createQueryBuilder()
    5
    .select("user")
    6
    .from(User, "user")
    7
    .where("user.id = :id", { id: 1 })
    8
    .getOne();
    Copied!
    Using entity manager:
    1
    import {getManager} from "typeorm";
    2
    ​
    3
    const user = await getManager()
    4
    .createQueryBuilder(User, "user")
    5
    .where("user.id = :id", { id: 1 })
    6
    .getOne();
    Copied!
    Using repository:
    1
    import {getRepository} from "typeorm";
    2
    ​
    3
    const user = await getRepository(User)
    4
    .createQueryBuilder("user")
    5
    .where("user.id = :id", { id: 1 })
    6
    .getOne();
    Copied!
There are 5 different QueryBuilder types available:
    SelectQueryBuilder - used to build and execute SELECT queries. Example:
    1
    import {getConnection} from "typeorm";
    2
    ​
    3
    const user = await getConnection()
    4
    .createQueryBuilder()
    5
    .select("user")
    6
    .from(User, "user")
    7
    .where("user.id = :id", { id: 1 })
    8
    .getOne();
    Copied!
    InsertQueryBuilder - used to build and execute INSERT queries. Example:
    1
    import {getConnection} from "typeorm";
    2
    ​
    3
    await getConnection()
    4
    .createQueryBuilder()
    5
    .insert()
    6
    .into(User)
    7
    .values([
    8
    { firstName: "Timber", lastName: "Saw" },
    9
    { firstName: "Phantom", lastName: "Lancer" }
    10
    ])
    11
    .execute();
    Copied!
    UpdateQueryBuilder - used to build and execute UPDATE queries. Example:
    1
    import {getConnection} from "typeorm";
    2
    ​
    3
    await getConnection()
    4
    .createQueryBuilder()
    5
    .update(User)
    6
    .set({ firstName: "Timber", lastName: "Saw" })
    7
    .where("id = :id", { id: 1 })
    8
    .execute();
    Copied!
    DeleteQueryBuilder - used to build and execute DELETE queries. Example:
    1
    import {getConnection} from "typeorm";
    2
    ​
    3
    await getConnection()
    4
    .createQueryBuilder()
    5
    .delete()
    6
    .from(User)
    7
    .where("id = :id", { id: 1 })
    8
    .execute();
    Copied!
    RelationQueryBuilder - used to build and execute relation-specific operations [TBD].
You can switch between different types of query builder within any of them, once you do, you will get a new instance of query builder (unlike all other methods).

Getting values using QueryBuilder

To get a single result from the database, for example to get a user by id or name, you must use getOne:
1
const timber = await getRepository(User)
2
.createQueryBuilder("user")
3
.where("user.id = :id OR user.name = :name", { id: 1, name: "Timber" })
4
.getOne();
Copied!
getOneOrFail will get a single result from the database, but if no result exists it will throw an EntityNotFoundError:
1
const timber = await getRepository(User)
2
.createQueryBuilder("user")
3
.where("user.id = :id OR user.name = :name", { id: 1, name: "Timber" })
4
.getOneOrFail();
Copied!
To get multiple results from the database, for example, to get all users from the database, use getMany:
1
const users = await getRepository(User)
2
.createQueryBuilder("user")
3
.getMany();
Copied!
There are two types of results you can get using select query builder: entities or raw results. Most of the time, you need to select real entities from your database, for example, users. For this purpose, you use getOne and getMany. But sometimes you need to select some specific data, let's say the sum of all user photos. This data is not an entity, it's called raw data. To get raw data, you use getRawOne and getRawMany. Examples:
1
const { sum } = await getRepository(User)
2
.createQueryBuilder("user")
3
.select("SUM(user.photosCount)", "sum")
4
.where("user.id = :id", { id: 1 })
5
.getRawOne();
Copied!
1
const photosSums = await getRepository(User)
2
.createQueryBuilder("user")
3
.select("user.id")
4
.addSelect("SUM(user.photosCount)", "sum")
5
.groupBy("user.id")
6
.getRawMany();
7
​
8
// result will be like this: [{ id: 1, sum: 25 }, { id: 2, sum: 13 }, ...]
Copied!

What are aliases for?

We used createQueryBuilder("user"). But what is "user"? It's just a regular SQL alias. We use aliases everywhere, except when we work with selected data.
createQueryBuilder("user") is equivalent to:
1
createQueryBuilder()
2
.select("user")
3
.from(User, "user")
Copied!
Which will result in the following sql query:
1
SELECT ... FROM users user
Copied!
In this SQL query, users is the table name, and user is an alias we assign to this table. Later we use this alias to access the table:
1
createQueryBuilder()
2
.select("user")
3
.from(User, "user")
4
.where("user.name = :name", { name: "Timber" })
Copied!
Which produces the following SQL query:
1
SELECT ... FROM users user WHERE user.name = 'Timber'
Copied!
See, we used the users table by using the user alias we assigned when we created a query builder.
One query builder is not limited to one alias, they can have multiple aliases. Each select can have its own alias, you can select from multiple tables each with its own alias, you can join multiple tables each with its own alias. You can use those aliases to access tables are you selecting (or data you are selecting).

Using parameters to escape data

We used where("user.name = :name", { name: "Timber" }). What does { name: "Timber" } stand for? It's a parameter we used to prevent SQL injection. We could have written: where("user.name = '" + name + "'), however this is not safe, as it opens the code to SQL injections. The safe way is to use this special syntax: where("user.name = :name", { name: "Timber" }), where :name is a parameter name and the value is specified in an object: { name: "Timber" }.
1
.where("user.name = :name", { name: "Timber" })
Copied!
is a shortcut for:
1
.where("user.name = :name")
2
.setParameter("name", "Timber")
Copied!
Note: do not use the same parameter name for different values across the query builder. Values will be overridden if you set them multiple times.
You can also supply an array of values, and have them transformed into a list of values in the SQL statement, by using the special expansion syntax:
1
.where("user.name IN (:...names)", { names: [ "Timber", "Cristal", "Lina" ] })
Copied!
Which becomes:
1
WHERE user.name IN ('Timber', 'Cristal', 'Lina')
Copied!

Adding WHERE expression

Adding a WHERE expression is as easy as:
1
createQueryBuilder("user")
2
.where("user.name = :name", { name: "Timber" })
Copied!
Which will produce:
1
SELECT ... FROM users user WHERE user.name = 'Timber'
Copied!
You can add AND into an existing WHERE expression:
1
createQueryBuilder("user")
2
.where("user.firstName = :firstName", { firstName: "Timber" })
3
.andWhere("user.lastName = :lastName", { lastName: "Saw" });
Copied!
Which will produce the following SQL query:
1
SELECT ... FROM users user WHERE user.firstName = 'Timber' AND user.lastName = 'Saw'
Copied!
You can add OR into an existing WHERE expression:
1
createQueryBuilder("user")
2
.where("user.firstName = :firstName", { firstName: "Timber" })
3
.orWhere("user.lastName = :lastName", { lastName: "Saw" });
Copied!
Which will produce the following SQL query:
1
SELECT ... FROM users user WHERE user.firstName = 'Timber' OR user.lastName = 'Saw'
Copied!
You can do an IN query with the WHERE expression:
1
createQueryBuilder("user")
2
.where("user.id IN (:...ids)", { ids: [1, 2, 3, 4] })
Copied!
Which will produce the following SQL query:
1
SELECT ... FROM users user WHERE user.id IN (1, 2, 3, 4)
Copied!
You can add a complex WHERE expression into an existing WHERE using Brackets
1
createQueryBuilder("user")
2
.where("user.registered = :registered", { registered: true })
3
.andWhere(new Brackets(qb => {
4
qb.where("user.firstName = :firstName", { firstName: "Timber" })
5
.orWhere("user.lastName = :lastName", { lastName: "Saw" })
6
}))
Copied!
Which will produce the following SQL query:
1
SELECT ... FROM users user WHERE user.registered = true AND (user.firstName = 'Timber' OR user.lastName = 'Saw')
Copied!
You can combine as many AND and OR expressions as you need. If you use .where more than once you'll override all previous WHERE expressions.
Note: be careful with orWhere - if you use complex expressions with both AND and OR expressions, keep in mind that they are stacked without any pretences. Sometimes you'll need to create a where string instead, and avoid using orWhere.

Adding HAVING expression

Adding a HAVING expression is easy as:
1
createQueryBuilder("user")
2
.having("user.name = :name", { name: "Timber" })
Copied!
Which will produce following SQL query:
1
SELECT ... FROM users user HAVING user.name = 'Timber'
Copied!
You can add AND into an exist HAVING expression:
1
createQueryBuilder("user")
2
.having("user.firstName = :firstName", { firstName: "Timber" })
3
.andHaving("user.lastName = :lastName", { lastName: "Saw" });
Copied!
Which will produce the following SQL query:
1
SELECT ... FROM users user HAVING user.firstName = 'Timber' AND user.lastName = 'Saw'
Copied!
You can add OR into a exist HAVING expression:
1
createQueryBuilder("user")
2
.having("user.firstName = :firstName", { firstName: "Timber" })
3
.orHaving("user.lastName = :lastName", { lastName: "Saw" });
Copied!
Which will produce the following SQL query:
1
SELECT ... FROM users user HAVING user.firstName = 'Timber' OR user.lastName = 'Saw'
Copied!
You can combine as many AND and OR expressions as you need. If you use .having more than once you'll override all previous HAVING expressions.

Adding ORDER BY expression

Adding an ORDER BY expression is easy as:
1
createQueryBuilder("user")
2
.orderBy("user.id")
Copied!
Which will produce:
1
SELECT ... FROM users user ORDER BY user.id
Copied!
You can change the ordering direction from ascending to descending (or versa):
1
createQueryBuilder("user")
2
.orderBy("user.id", "DESC")
3
​
4
createQueryBuilder("user")
5
.orderBy("user.id", "ASC")
Copied!
You can add multiple order-by criteria:
1
createQueryBuilder("user")
2
.orderBy("user.name")
3
.addOrderBy("user.id");
Copied!
You can also use a map of order-by fields:
1
createQueryBuilder("user")
2
.orderBy({
3
"user.name": "ASC",
4
"user.id": "DESC"
5
});
Copied!
If you use .orderBy more than once you'll override all previous ORDER BY expressions.

Adding DISTINCT ON expression (Postgres only)

When using both distinct-on with an order-by expression, the distinct-on expression must match the leftmost order-by. The distinct-on expressions are interpreted using the same rules as order-by. Please note that, using distinct-on without an order-by expression means that the first row of each set is unpredictable.
Adding a DISTINCT ON expression is easy as:
1
createQueryBuilder("user")
2
.distinctOn(["user.id"])
3
.orderBy("user.id")
Copied!
Which will produce:
1
SELECT DISTINCT ON (user.id) ... FROM users user ORDER BY user.id
Copied!

Adding GROUP BY expression

Adding a GROUP BY expression is easy as:
1
createQueryBuilder("user")
2
.groupBy("user.id")
Copied!
Which will produce the following SQL query:
1
SELECT ... FROM users user GROUP BY user.id
Copied!
To add more group-by criteria use addGroupBy:
1
createQueryBuilder("user")
2
.groupBy("user.name")
3
.addGroupBy("user.id");
Copied!
If you use .groupBy more than once you'll override all previous GROUP BY expressions.

Adding LIMIT expression

Adding a LIMIT expression is easy as:
1
createQueryBuilder("user")
2
.limit(10)
Copied!
Which will produce the following SQL query:
1
SELECT ... FROM users user LIMIT 10
Copied!
The resulting SQL query depends on the type of database (SQL, mySQL, Postgres, etc). Note: LIMIT may not work as you may expect if you are using complex queries with joins or subqueries. If you are using pagination, it's recommended to use take instead.

Adding OFFSET expression

Adding an SQL OFFSET expression is easy as:
1
createQueryBuilder("user")
2
.offset(10)
Copied!
Which will produce the following SQL query:
1
SELECT ... FROM users user OFFSET 10
Copied!
The resulting SQL query depends on the type of database (SQL, mySQL, Postgres, etc). Note: OFFSET may not work as you may expect if you are using complex queries with joins or subqueries. If you are using pagination, it's recommended to use skip instead.

Joining relations

Let's say you have the following entities:
1
import {Entity, PrimaryGeneratedColumn, Column, OneToMany} from "typeorm";
2
import {Photo} from "./Photo";
3
​
4
@Entity()
5
export class User {
6
​
7
@PrimaryGeneratedColumn()
8
id: number;
9
​
10
@Column()
11
name: string;
12
​
13
@OneToMany(type => Photo, photo => photo.user)
14
photos: Photo[];
15
}
Copied!
1
import {Entity, PrimaryGeneratedColumn, Column, ManyToOne} from "typeorm";
2
import {User} from "./User";
3
​
4
@Entity()
5
export class Photo {
6
​
7
@PrimaryGeneratedColumn()
8
id: number;
9
​
10
@Column()
11
url: string;
12
​
13
@ManyToOne(type => User, user => user.photos)
14
user: User;
15
}
Copied!
Now let's say you want to load user "Timber" with all of his photos:
1
const user = await createQueryBuilder("user")
2
.leftJoinAndSelect("user.photos", "photo")
3
.where("user.name = :name", { name: "Timber" })
4
.getOne();
Copied!
You'll get the following result:
1
{
2
id: 1,
3
name: "Timber",
4
photos: [{
5
id: 1,
6
url: "me-with-chakram.jpg"
7
}, {
8
id: 2,
9
url: "me-with-trees.jpg"
10
}]
11
}
Copied!
As you can see leftJoinAndSelect automatically loaded all of Timber's photos. The first argument is the relation you want to load and the second argument is an alias you assign to this relation's table. You can use this alias anywhere in query builder. For example, let's take all Timber's photos which aren't removed.
1
const user = await createQueryBuilder("user")
2
.leftJoinAndSelect("user.photos", "photo")
3
.where("user.name = :name", { name: "Timber" })
4
.andWhere("photo.isRemoved = :isRemoved", { isRemoved: false })
5
.getOne();
Copied!
This will generate following sql query:
1
SELECT user.*, photo.* FROM users user
2
LEFT JOIN photos photo ON photo.user = user.id
3
WHERE user.name = 'Timber' AND photo.isRemoved = FALSE
Copied!
You can also add conditions to the join expression instead of using "where":
1
const user = await createQueryBuilder("user")
2
.leftJoinAndSelect("user.photos", "photo", "photo.isRemoved = :isRemoved", { isRemoved: false })
3
.where("user.name = :name", { name: "Timber" })
4
.getOne();
Copied!
This will generate the following sql query:
1
SELECT user.*, photo.* FROM users user
2
LEFT JOIN photos photo ON photo.user = user.id AND photo.isRemoved = FALSE
3
WHERE user.name = 'Timber'
Copied!

Inner and left joins

If you want to use INNER JOIN instead of LEFT JOIN just use innerJoinAndSelect instead:
1
const user = await createQueryBuilder("user")
2
.innerJoinAndSelect("user.photos", "photo", "photo.isRemoved = :isRemoved", { isRemoved: false })
3
.where("user.name = :name", { name: "Timber" })
4
.getOne();
Copied!
This will generate:
1
SELECT user.*, photo.* FROM users user
2
INNER JOIN photos photo ON photo.user = user.id AND photo.isRemoved = FALSE
3
WHERE user.name = 'Timber'
Copied!