fontcolor_theme
Deepkit ORM

Query

Eine Query ist ein Objekt, das beschreibt, wie Daten aus der Datenbank abgerufen oder geändert werden. Sie verfügt über mehrere Methoden zur Beschreibung der Query sowie über abschließende Methoden, die sie ausführen. Der Datenbankadapter kann die Query-API auf vielfältige Weise erweitern, um datenbankspezifische Features zu unterstützen.

Eine Query kann mit Database.query(T) oder Session.query(T) erstellt werden. Wir empfehlen Sessions, da sie die Performance verbessern.

@entity.name('user')
class User {
    id: number & PrimaryKey & AutoIncrement = 0;
    created: Date = new Date;
    birthdate?: Date;
    visits: number = 0;

    constructor(public username: string) {
    }
}

const database = new Database(...);

//[ { username: 'User1' }, { username: 'User2' }, { username: 'User2' } ]
const users = await database.query(User).select('username').find();

Filter

Ein Filter kann angewendet werden, um die Ergebnismenge einzuschränken.

//einfache Filter
const users = await database.query(User).filter({name: 'User1'}).find();

//mehrere Filter, alle mit AND verknüpft
const users = await database.query(User).filter({name: 'User1', id: 2}).find();

//Bereichsfilter: $gt, $lt, $gte, $lte (größer als, kleiner als, ...)
//entspricht WHERE created < NOW()
const users = await database.query(User).filter({created: {$lt: new Date}}).find();
//entspricht WHERE id > 500
const users = await database.query(User).filter({id: {$gt: 500}}).find();
//entspricht WHERE id >= 500
const users = await database.query(User).filter({id: {$gte: 500}}).find();

//Mengenfilter: $in, $nin (in, nicht in)
//entspricht WHERE id IN (1, 2, 3)
const users = await database.query(User).filter({id: {$in: [1, 2, 3]}}).find();

//Regex-Filter
const users = await database.query(User).filter({username: {$regex: /User[0-9]+/}}).find();

//Gruppierung: $and, $nor, $or
//entspricht WHERE (username = 'User1') OR (username = 'User2')
const users = await database.query(User).filter({
    $or: [{username: 'User1'}, {username: 'User2'}]
}).find();


//verschachtelte Gruppierung
//entspricht WHERE username = 'User1' OR (username = 'User2' and id > 0)
const users = await database.query(User).filter({
    $or: [{username: 'User1'}, {username: 'User2', id: {$gt: 0}}]
}).find();


//verschachtelte Gruppierung
//entspricht WHERE username = 'User1' AND (created < NOW() OR id > 0)
const users = await database.query(User).filter({
    $and: [{username: 'User1'}, {$or: [{created: {$lt: new Date}, id: {$gt: 0}}]}]
}).find();

Gleich

Größer / Kleiner

RegExp

Gruppierung AND/OR

In

Select

Um die aus der Datenbank abzurufenden Felder einzugrenzen, kann select('field1') verwendet werden.

const user = await database.query(User).select('username').findOne();
const user = await database.query(User).select('id', 'username').findOne();

Wichtig ist, dass die Ergebnisse keine Instanzen der Entity mehr sind, sondern nur noch Objektliterale, sobald die Felder mit select eingegrenzt werden.

const user = await database.query(User).select('username').findOne();
user instanceof User; //false

Sortierung

Mit orderBy(field, order) kann die Reihenfolge der Einträge geändert werden. orderBy kann mehrfach ausgeführt werden, um die Sortierung immer weiter zu verfeinern.

const users = await session.query(User).orderBy('created', 'desc').find();
const users = await session.query(User).orderBy('created', 'asc').find();

Paginierung

Mit den Methoden itemsPerPage() und page() können die Ergebnisse paginiert werden. Die Seitenzählung beginnt bei 1.

const users = await session.query(User).itemsPerPage(50).page(1).find();

Mit den alternativen Methoden limit und skip kann manuell paginiert werden.

const users = await session.query(User).limit(5).skip(10).find();

[#database-join]

Join

Standardmäßig werden Referenzen der Entity weder in Queries einbezogen noch geladen. Um einen Join in die Query aufzunehmen, ohne die Referenz zu laden, verwende join() (Left Join) oder innerJoin(). Um einen Join in die Query aufzunehmen und die Referenz zu laden, verwende joinWith() oder innerJoinWith().

Alle folgenden Beispiele gehen von diesen Modellschemata aus:

@entity.name('group')
class Group {
    id: number & PrimaryKey & AutoIncrement = 0;
    created: Date = new Date;

    constructor(public username: string) {
    }
}

@entity.name('user')
class User {
    id: number & PrimaryKey & AutoIncrement = 0;
    created: Date = new Date;

    group?: Group & Reference;

    constructor(public username: string) {
    }
}
//nur Benutzer auswählen, denen eine Gruppe zugewiesen ist (INNER JOIN)
const users = await session.query(User).innerJoin('group').find();
for (const user of users) {
    user.group; //Error, da die Referenz nicht geladen wurde
}
//nur Benutzer auswählen, denen eine Gruppe zugewiesen ist (INNER JOIN), und die Relation laden
const users = await session.query(User).innerJoinWith('group').find();
for (const user of users) {
    user.group.name; //funktioniert
}

Um Join-Queries zu ändern, verwende dieselben Methoden, jedoch mit dem Präfix use: useJoin, useInnerJoin, useJoinWith oder useInnerJoinWith. Um die Änderung der Join-Query zu beenden, verwende end(), womit du zur übergeordneten Query zurückkehrst.

//nur Benutzer auswählen, denen eine Gruppe mit dem Namen 'admins' zugewiesen ist (INNER JOIN)
const users = await session.query(User)
    .useInnerJoinWith('group')
        .filter({name: 'admins'})
        .end()  // kehrt zur übergeordneten Query zurück
    .find();

for (const user of users) {
    user.group.name; //immer admin
}

Aggregation

Mit Aggregationsmethoden lassen sich Datensätze zählen und Felder aggregieren.

Die folgenden Beispiele gehen von diesem Modellschema aus:

@entity.name('file')
class File {
    id: number & PrimaryKey & AutoIncrement = 0;
    created: Date = new Date;

    downloads: number = 0;

    category: string = 'none';

    constructor(public path: string & Index) {
    }
}

groupBy ermöglicht es, das Ergebnis nach dem angegebenen Feld zu gruppieren.

await database.persist(
    cast<File>({path: 'file1', category: 'images'}),
    cast<File>({path: 'file2', category: 'images'}),
    cast<File>({path: 'file3', category: 'pdfs'})
);

//[ { category: 'images' }, { category: 'pdfs' } ]
await session.query(File).groupBy('category').find();

Es gibt mehrere Aggregationsmethoden: withSum, withAverage, withCount, withMin, withMax, withGroupConcat. Jede erfordert einen Feldnamen als erstes Argument und akzeptiert ein optionales zweites Argument, um den Alias zu ändern.

// zuerst aktualisieren wir einige der Datensätze:
await database.query(File).filter({path: 'images/file1'}).patchOne({$inc: {downloads: 15}});
await database.query(File).filter({path: 'images/file2'}).patchOne({$inc: {downloads: 5}});

//[{ category: 'images', downloads: 20 },{ category: 'pdfs', downloads: 0 }]
await session.query(File).groupBy('category').withSum('downloads').find();

//[{ category: 'images', downloads: 10 },{ category: 'pdfs', downloads: 0 }]
await session.query(File).groupBy('category').withAverage('downloads').find();

//[ { category: 'images', amount: 2 }, { category: 'pdfs', amount: 1 } ]
await session.query(File).groupBy('category').withCount('id', 'amount').find();

Returning

Mit returning können bei Änderungen über patch und delete zusätzliche Felder angefordert werden.

Achtung: Nicht alle Datenbankadapter geben Felder atomar zurück. Verwende Transaktionen, um die Datenkonsistenz sicherzustellen.

await database.query(User).patchMany({visits: 0});

//{ modified: 1, returning: { visits: [ 5 ] }, primaryKeys: [ 1 ] }
const result = await database.query(User)
    .filter({username: 'User1'})
    .returning('username', 'visits')
    .patchOne({$inc: {visits: 5}});

Find

Gibt ein Array von Einträgen zurück, die dem angegebenen Filter entsprechen.

const users: User[] = await database.query(User).filter({username: 'Peter'}).find();

FindOne

Gibt einen Eintrag zurück, der dem angegebenen Filter entspricht. Wird kein Eintrag gefunden, wird ein ItemNotFound-Error geworfen.

const users: User = await database.query(User).filter({username: 'Peter'}).findOne();

FindOneOrUndefined

Gibt einen Eintrag zurück, der dem angegebenen Filter entspricht. Wird kein Eintrag gefunden, wird undefined zurückgegeben.

const query = database.query(User).filter({username: 'Peter'});
const users: User|undefined = await query.findOneOrUndefined();

FindField

Gibt eine Liste der Werte eines Feldes zurück, die dem angegebenen Filter entsprechen.

const usernames: string[] = await database.query(User).findField('username');

FindOneField

Gibt eine Liste der Werte eines Feldes zurück, die dem angegebenen Filter entsprechen. Wird kein Eintrag gefunden, wird ein ItemNotFound-Error geworfen.

const username: string = await database.query(User).filter({id: 3}).findOneField('username');

Patch

Patch ist eine Änderungs-Query, die die in der Query beschriebenen Datensätze patcht. Die Methoden patchOne und patchMany schließen die Query ab und führen den Patch aus.

patchMany ändert alle Datensätze in der Datenbank, die dem angegebenen Filter entsprechen. Ist kein Filter gesetzt, wird die gesamte Tabelle geändert. Verwende patchOne, um jeweils nur einen Eintrag zu ändern.

await database.query(User).filter({username: 'Peter'}).patch({username: 'Peter2'});

await database.query(User).filter({username: 'User1'}).patchOne({birthdate: new Date});
await database.query(User).filter({username: 'User1'}).patchOne({$inc: {visits: 1}});

await database.query(User).patchMany({visits: 0});

Delete

deleteMany löscht alle Einträge in der Datenbank, die dem angegebenen Filter entsprechen. Ist kein Filter gesetzt, wird die gesamte Tabelle gelöscht. Verwende deleteOne, um jeweils nur einen Eintrag zu löschen.

const result = await database.query(User)
    .filter({visits: 0})
    .deleteMany();

const result = await database.query(User).filter({id: 4}).deleteOne();

Das Ergebnis enthält in modified die Anzahl der gelöschten Einträge. Die Primärschlüssel der gelöschten Einträge sind nur mit returnPrimaryKeys() verfügbar, da ihr Auslesen den Löschvorgang verlangsamt. Wird primaryKeys ohne diese Methode gelesen, wird ein PrimaryKeysNotReturnedError geworfen, auch innerhalb von Event-Listenern.

const result = await database.query(User)
    .filter({logins: 0})
    .returnPrimaryKeys()
    .deleteMany();
result.primaryKeys; //[{id: 4}, {id: 7}]

Has

Gibt zurück, ob mindestens ein Eintrag in der Datenbank existiert.

const userExists: boolean = await database.query(User).filter({username: 'Peter'}).has();

Count

Gibt die Anzahl der Einträge zurück.

const userCount: number = await database.query(User).count();

Lift

Das Liften einer Query bedeutet, ihr neue Funktionalität hinzuzufügen. Dies wird üblicherweise entweder von Plugins oder in komplexen Architekturen verwendet, um größere Query-Klassen in mehrere praktische, wiederverwendbare Klassen aufzuteilen.

import { FilterQuery, Query } from '@deepkit/orm';

class UserQuery<T extends {birthdate?: Date}> extends Query<T>  {
    hasBirthday() {
        const start = new Date();
        start.setHours(0,0,0,0);
        const end = new Date();
        end.setHours(23,59,59,999);

        return this.filter({$and: [{birthdate: {$gte: start}}, {birthdate: {$lte: end}}]} as FilterQuery<T>);
    }
}

await session.query(User).lift(UserQuery).hasBirthday().find();
English中文 (Chinese)한국어 (Korean)日本語 (Japanese)Deutsch (German)