Kurs NestJS · Moduł 3: TypeORM i bazy danych
Query Builder - zaawansowane poszukiwania
W tej lekcji7
Konsul Caesar.js staje przed Tobą z nowym zadaniem: "Cenzor pyta, którzy centurioni zebrali w tym miesiącu tributy o największej łącznej wartości. Chce listę posortowaną od najbogatszych." Otwierasz znane Ci repozytorium... i zatrzymujesz się. Metoda find() świetnie radzi sobie z prostymi pytaniami: "daj tributy warte ponad 1000 denarów", "znajdź legionistę po imieniu". Ale sumowanie, grupowanie po centurionie, warunki budowane dopiero w trakcie działania programu - tego find() nie wyrazi.
Do takich pytań TypeORM ma potężniejsze narzędzie: Query Builder. Pomyśl o nim jak o kartografie skarbca - zapytanie budujesz krok po kroku, metoda po metodzie, a on na końcu rysuje z tych kroków jedną precyzyjną mapę (zapytanie SQL) i wysyła ją do bazy.
Pierwsze zapytanie krok po kroku
Zacznijmy od pytania, które umiałbyś zadać także przez find() - tak najłatwiej zobaczyć, co Query Builder robi inaczej. Szukamy tributów wartych ponad 1000 denarów, od najcenniejszych:
const tributes = await this.tributeRepository
.createQueryBuilder('tribute')
.where('tribute.value > :minValue', { minValue: 1000 })
.orderBy('tribute.value', 'DESC')
.getMany();Prześledźmy łańcuch. createQueryBuilder('tribute') otwiera budowę zapytania i nadaje encji alias - krótki przydomek, którym posługujemy się w kolejnych metodach, pisząc tribute.value czy tribute.name. where(...) dodaje warunek, a orderBy(...) sortowanie. Dopiero getMany() skleja z tych klocków SQL i wysyła go do bazy - wcześniej do bazy nie idzie nic. Wynik to zwykła tablica encji Tribute[], dokładnie taka sama, jaką dostałbyś z find() - zmienił się sposób budowania pytania, nie kształt odpowiedzi.
Parametry - tarcza przeciw wrogim rozkazom
W warunku where nie wpisaliśmy liczby 1000 wprost. Zamiast niej stoi :minValue - parametr, którego wartość podajemy obok, w obiekcie { minValue: 1000 }. Po co to rozdzielenie? Wyobraź sobie, że wartość pochodzi od użytkownika. Wklejona bezpośrednio do tekstu zapytania, mogłaby przemycić wrogi rozkaz - jak posłaniec, który w treści listu ukrywa polecenie otwarcia bram. Ten atak nazywa się SQL injection:
// ŹLE - dane użytkownika sklejone z tekstem zapytania
.where(`tribute.name = '${userInput}'`)
// DOBRZE - dane wędrują osobno, jako parametr
.where('tribute.name = :name', { name: userInput })Różnica jest zasadnicza: parametr nigdy nie jest sklejany z tekstem SQL. Baza dostaje go osobnym kanałem i traktuje wyłącznie jako dane - nawet jeśli ktoś wpisze w formularzu fragment złośliwego zapytania, pozostanie on tylko dziwnie wyglądającym tekstem. Dlatego przyjmij żelazną zasadę: każda wartość w zapytaniu przechodzi przez parametr. Bez wyjątków.
Sklejanie warunków
Prawdziwe poszukiwania rzadko mają jeden warunek. Kolejne dokładasz metodą andWhere - warunek musi być spełniony razem z poprzednimi. Jest też orWhere - wystarczy, że spełniony będzie którykolwiek:
const tributes = await this.tributeRepository
.createQueryBuilder('tribute')
.where('tribute.value >= :min', { min: 1000 })
.andWhere('tribute.type = :type', { type: 'gold' })
.getMany();To zapytanie znajdzie tributy, które są złote i zarazem warte co najmniej 1000 denarów. A ponieważ zapytanie jest zwykłym obiektem budowanym metodami, warunki możemy dokładać także warunkowo - w if:
let query = this.tributeRepository.createQueryBuilder('tribute');
if (criteria.minValue) {
query = query.andWhere('tribute.value >= :min', { min: criteria.minValue });
}
if (criteria.type) {
query = query.andWhere('tribute.type = :type', { type: criteria.type });
}
const tributes = await query.orderBy('tribute.value', 'DESC').getMany();I to jest moment, w którym Query Builder zostawia find() daleko w tyle: zapytanie rośnie w trakcie działania programu, warunek po warunku, zależnie od tego, o co pyta użytkownik - a do bazy i tak poleci jako jeden SQL, dopiero przy getMany().
Dołączanie relacji
Tributy nie istnieją w próżni - każdy należy do legionisty, a legionista służy pod centurionem. Aby pobrać tributy razem z danymi właścicieli, dołączamy relację:
const tributes = await this.tributeRepository
.createQueryBuilder('tribute')
.leftJoinAndSelect('tribute.legionariusze', 'legionista')
.where('legionista.isActive = :active', { active: true })
.getMany();Nazwa leftJoinAndSelect to dwie decyzje zapisane w jednym słowie. LeftJoin: dołącz legionistę, ale tributu bez właściciela nie odrzucaj - jego pole będzie po prostu puste (bliźniacze innerJoinAndSelect odrzuciłoby taki tribut z wyniku). AndSelect: załaduj dane legionisty do encji wyniku. Drugi argument, 'legionista', to alias dołączonej encji - dzięki niemu mogliśmy w where filtrować po legionista.isActive. Istnieje też samo leftJoin, bez AndSelect: relacja posłuży wtedy tylko do filtrowania, a jej dane nie zostaną załadowane - wynik będzie lżejszy. I to polecam, gdy danych właściciela nie wyświetlasz.
Statystyki - kiedy wynik nie jest encją
Wróćmy do pytania cenzora: łączna wartość tributów według typu. Odpowiedzią nie jest lista tributów, tylko tabela podsumowań - kilka wierszy z licznikami i sumami. Do takich zapytań kolumny wybieramy sami i zamykamy budowę metodą getRawMany() zamiast getMany():
const stats = await this.tributeRepository
.createQueryBuilder('tribute')
.select('tribute.type', 'type')
.addSelect('COUNT(*)', 'count')
.addSelect('SUM(tribute.value)', 'totalValue')
.groupBy('tribute.type')
.orderBy('totalValue', 'DESC')
.getRawMany();select wybiera pierwszą kolumnę, każdy addSelect dokłada następną, a drugi argument nadaje jej nazwę w wyniku. groupBy zwija wiersze w grupy - COUNT i SUM liczą się wtedy osobno dla każdego typu tributu. Kluczowe jest zakończenie: getMany() zwraca encje Tribute, ale suma czy licznik encją nie są - dlatego wołamy getRawMany(), które zwraca surowe wiersze o polach nazwanych przez Ciebie: { type, count, totalValue }.
Paginacja - skarbiec podawany porcjami
Skarbiec Imperium liczy tysiące tributów i nikt nie ogląda ich naraz. Wyniki podajemy stronami:
const [tributes, total] = await this.tributeRepository
.createQueryBuilder('tribute')
.orderBy('tribute.value', 'DESC')
.skip((page - 1) * limit)
.take(limit)
.getManyAndCount();skip pomija wyniki należące do poprzednich stron, take pobiera jedną porcję. getManyAndCount() zwraca parę: porcję wyników i łączną liczbę wszystkich pasujących wierszy - z niej policzysz liczbę stron: Math.ceil(total / limit). Zwróć uwagę, że orderBy nie jest tu ozdobą, a warunkiem poprawności: bez ustalonej kolejności baza mogłaby podawać wiersze za każdym razem inaczej i strony zaczęłyby się mieszać.
Podsumowanie
Spójrz, ile odpowiedzi potrafisz już wydobyć ze skarbca:
createQueryBuilder('alias')otwiera budowę zapytania, a alias to przydomek encji używany w jego wnętrzu,- warunki sklejasz metodami
where,andWhereiorWhere- także dynamicznie, wif, - każda wartość wędruje jako parametr
:nazwa- to tarcza przeciw SQL injection, - relacje dołączasz przez
leftJoinAndSelect, a gdy służą tylko do filtrowania - lżejszymleftJoin, - statystyki budujesz z
select,addSelectigroupBy, odbierając je przezgetRawMany(), - strony wyników wycinasz parą
skipitake, agetManyAndCount()dorzuca łączny licznik.
W następnej lekcji poznasz transakcje - sposób, by kilka operacji na skarbcu wykonało się jak jedna: albo wszystkie, albo żadna. A na razie zapamiętaj: Query Builder to kartograf - Ty dokładasz klocki, a on rysuje z nich jedną mapę SQL dopiero wtedy, gdy zawołasz getMany().
Kod do tej lekcji: src/query-builder.ts
// Query Builder - Zaawansowane Poszukiwania w Skarbcu
import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
console.log("Query Builder - potezne narzedzie wyszukiwania!");
// ===========================================
// 1. Podstawowy QueryBuilder
// ===========================================
@Injectable()
export class LegionQueryService {
constructor(
@InjectRepository('Legionary')
private legionaryRepo: Repository<any>,
) {}
// Znajdz doswiadczonych legionistow
async findExperienced(minExp: number) {
return this.legionaryRepo
.createQueryBuilder('legionary')
.where('legionary.experience >= :minExp', { minExp })
.orderBy('legionary.experience', 'DESC')
.getMany();
}
// Wyszukaj po imieniu
async searchByName(name: string) {
return this.legionaryRepo
.createQueryBuilder('legionary')
.where('legionary.name LIKE :name', { name: '%' + name + '%' })
.getMany();
}
// Filtrowanie z wieloma warunkami
async findByCriteria(rank?: string, minExp?: number, legion?: string) {
const qb = this.legionaryRepo.createQueryBuilder('l');
if (rank) {
qb.andWhere('l.rank = :rank', { rank });
}
if (minExp) {
qb.andWhere('l.experience >= :minExp', { minExp });
}
if (legion) {
qb.andWhere('l.legion = :legion', { legion });
}
return qb.orderBy('l.experience', 'DESC').getMany();
}
}
// ===========================================
// 2. QueryBuilder z relacjami (JOIN)
// ===========================================
@Injectable()
export class AdvancedQueryService {
constructor(
@InjectRepository('Legion')
private legionRepo: Repository<any>,
) {}
// LEFT JOIN z relacja
async findLegionsWithCenturions() {
return this.legionRepo
.createQueryBuilder('legion')
.leftJoinAndSelect('legion.soldiers', 'soldier')
.where('soldier.rank = :rank', { rank: 'Centurio' })
.orderBy('legion.name', 'ASC')
.getMany();
}
// Agregacja - statystyki
async getLegionStats() {
return this.legionRepo
.createQueryBuilder('legion')
.select('legion.name', 'legionName')
.addSelect('COUNT(soldier.id)', 'soldierCount')
.addSelect('AVG(soldier.experience)', 'avgExperience')
.leftJoin('legion.soldiers', 'soldier')
.groupBy('legion.name')
.getRawMany();
}
// Podzapytanie (subquery)
async findEliteLegions() {
const subQuery = this.legionRepo
.createQueryBuilder('sub')
.select('AVG(sub.soldiers)', 'avg')
.getQuery();
return this.legionRepo
.createQueryBuilder('legion')
.where('legion.soldiers > (' + subQuery + ')')
.getMany();
}
}
console.log("\n=== PODSUMOWANIE QUERY BUILDER ===");
console.log("createQueryBuilder('alias') - rozpocznij zapytanie");
console.log(".where() / .andWhere() - warunki filtrowania");
console.log(".orderBy() - sortowanie wynikow");
console.log(".leftJoinAndSelect() - laczenie z relacjami");
console.log(".select() / .addSelect() - wybor kolumn");
console.log(".groupBy() - grupowanie (agregacja)");
console.log(".getMany() / .getRawMany() - pobranie wynikow");
Hasła z dokumentacji w tej lekcji
Widzisz błąd w tej lekcji?
Sprawdź się
Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.
1. Kiedy warto użyć QueryBuilder zamiast prostych metod repozytorium w TypeORM?
2. Co robi metoda .leftJoinAndSelect() w QueryBuilder?
Zadania praktyczne w grze
- Układanie w pionie
Uporządkuj elementy zapytania QueryBuilder od pierwszego do ostatniego:
- Edytor kodu
Użyj createQueryBuilder do znalezienia legionistów z rangą 'Centurion', posortowanych po doświadczeniu DESC, z limitem 10
- Układanie w poziomie
Ułóż elementy zapytania QueryBuilder z LEFT JOIN:
- Klikanie w kolejności
Ułóż metody QueryBuilder w prawidłowej kolejności budowania zapytania:
- Edytor kodu
Użyj QueryBuilder do znalezienia legionów z ich legionistami, gdzie legion ma więcej niż 1000 żołnierzy, z paginacją (skip i take)