Database Explorer
*****************

<div class=perex>

Explorer ponuja intuitiven in učinkovit način dela s podatkovno bazo. Samodejno skrbi za relacije med tabelami in optimizacijo poizvedb, tako da se lahko osredotočite na svojo aplikacijo. Deluje takoj brez nastavljanja. Če potrebujete popoln nadzor nad SQL poizvedbami, lahko uporabite [SQL pristop |SQL way].

- Delo s podatki je naravno in enostavno razumljivo
- Generira optimizirane SQL poizvedbe, ki nalagajo samo potrebne podatke
- Omogoča enostaven dostop do povezanih podatkov brez potrebe po pisanju JOIN poizvedb
- Deluje takoj brez kakršnekoli konfiguracije ali generiranja entitet

</div>


Z Explorerjem začnete s klicem metode `table()` objekta [api:Nette\Database\Explorer] (podrobnosti o povezavi najdete v poglavju [Povezava in konfiguracija |guide#Povezava in konfiguracija]):

```php
$books = $explorer->table('book'); // 'book' je ime tabele
```

Metoda vrača objekt [Selection |api:Nette\Database\Table\Selection], ki predstavlja SQL poizvedbo. Na ta objekt lahko navezujemo nadaljnje metode za filtriranje in razvrščanje rezultatov. Poizvedba se sestavi in zažene šele v trenutku, ko začnemo zahtevati podatke. Na primer s prehajanjem skozi zanko `foreach`. Vsaka vrstica je predstavljena z objektom [ActiveRow |api:Nette\Database\Table\ActiveRow]:

```php
foreach ($books as $book) {
	echo $book->title;        // izpis stolpca 'title'
	echo $book->author_id;    // izpis stolpca 'author_id'
}
```

Explorer bistveno olajša delo s [povezavami med tabelami |#Povezave med tabelami]. Naslednji primer prikazuje, kako enostavno lahko izpišemo podatke iz povezanih tabel (knjige in njihovi avtorji). Opazite, da nam ni treba pisati nobenih JOIN poizvedb, Nette jih ustvari za nas:

```php
$books = $explorer->table('book');

foreach ($books as $book) {
	echo 'Knjiga: ' . $book->title;
	echo 'Avtor: ' . $book->author->name; // ustvari JOIN na tabelo 'author'
}
```

Nette Database Explorer optimizira poizvedbe, da so čim bolj učinkovite. Zgornji primer izvede samo dve SELECT poizvedbi, ne glede na to, ali obdelujemo 10 ali 10.000 knjig.

Poleg tega Explorer spremlja, kateri stolpci se v kodi uporabljajo, in nalaga iz podatkovne baze samo te, s čimer prihrani dodatno zmogljivost. To obnašanje je popolnoma samodejno in prilagodljivo. Če kasneje prilagodite kodo in začnete uporabljati druge stolpce, Explorer samodejno prilagodi poizvedbe. Ničesar vam ni treba nastavljati, niti razmišljati o tem, katere stolpce boste potrebovali - prepustite to Nette.


Filtriranje in razvrščanje
==========================

Razred `Selection` ponuja metode za filtriranje in razvrščanje izbora podatkov.

.[language-php]
| `where($condition, ...$params)` | Doda pogoj WHERE. Več pogojev je povezanih z operatorjem AND
| `whereOr(array $conditions)` | Doda skupino pogojev WHERE, povezanih z operatorjem OR
| `wherePrimary($value)` | Doda pogoj WHERE po primarnem ključu
| `order($columns, ...$params)` | Nastavi razvrščanje ORDER BY
| `select($columns, ...$params)` | Določi stolpce, ki naj se naložijo
| `limit($limit, $offset = null)` | Omeji število vrstic (LIMIT) in po želji nastavi OFFSET
| `page($page, $itemsPerPage, &$total = null)` | Nastavi stranskanje
| `group($columns, ...$params)` | Združi vrstice (GROUP BY)
| `having($condition, ...$params)` | Doda pogoj HAVING za filtriranje združenih vrstic

Metode lahko verižimo (t.i. [fluent interface |nette:introduction-to-object-oriented-programming#Tekoči vmesniki]): `$table->where(...)->order(...)->limit(...)`.

V teh metodah lahko uporabljate tudi posebno notacijo za dostop do [podatkov iz povezanih tabel |#Poizvedovanje prek povezanih tabel].


Ubežanje znakov in identifikatorji
----------------------------------

Metode samodejno ubežijo parametre in navajajo identifikatorje (imena tabel in stolpcev), s čimer preprečujejo SQL injection. Za pravilno delovanje je treba upoštevati nekaj pravil:

- Ključne besede, imena funkcij, procedur ipd. pišite **z velikimi črkami**.
- Imena stolpcev in tabel pišite **z malimi črkami**.
- Nize vedno vstavljajte prek **parametrov**.

```php
where('name = ' . $name);         // KRITIČNA RANLJIVOST: SQL injection
where('name LIKE "%search%"');    // NAPAKA: otežuje samodejno navajanje
where('name LIKE ?', '%search%'); // PRAVILNO: vrednost vstavljena prek parametra

where('name like ?', $name);     // NAPAKA: generira: `name` `like` ?
where('name LIKE ?', $name);     // PRAVILNO: generira: `name` LIKE ?
where('LOWER(name) = ?', $value);// PRAVILNO: LOWER(`name`) = ?
```


where(string|array $condition, ...$parameters): static .[method]
----------------------------------------------------------------

Filtrira rezultate s pomočjo pogojev WHERE. Njena močna stran je inteligentno delo z različnimi tipi vrednosti in samodejna izbira SQL operatorjev.

Osnovna uporaba:

```php
$table->where('id', $value);     // WHERE `id` = 123
$table->where('id > ?', $value); // WHERE `id` > 123
$table->where('id = ? OR name = ?', $id, $name); // WHERE `id` = 1 OR `name` = 'Jon Snow'
```

Zahvaljujoč samodejnemu zaznavanju ustreznih operatorjev nam ni treba reševati različnih posebnih primerov. Nette jih reši za nas:

```php
$table->where('id', 1);          // WHERE `id` = 1
$table->where('id', null);       // WHERE `id` IS NULL
$table->where('id', [1, 2, 3]);  // WHERE `id` IN (1, 2, 3)
// lahko se uporabi tudi nadomestni vprašaj brez operatorja:
$table->where('id ?', 1);        // WHERE `id` = 1
```

Metoda pravilno obdela tudi negativne pogoje in prazno polje:

```php
$table->where('id', []);         // WHERE `id` IS NULL AND FALSE -- ničesar ne najde
$table->where('id NOT', []);     // WHERE `id` IS NULL OR TRUE -- najde vse
$table->where('NOT (id ?)', []); // WHERE NOT (`id` IS NULL AND FALSE) -- najde vse
// $table->where('NOT id ?', $ids);  Pozor - ta sintaksa ni podprta
```

Kot parameter lahko posredujemo tudi rezultat iz druge tabele - ustvari se podpoizvedba:

```php
// WHERE `id` IN (SELECT `id` FROM `tableName`)
$table->where('id', $explorer->table($tableName));

// WHERE `id` IN (SELECT `col` FROM `tableName`)
$table->where('id', $explorer->table($tableName)->select('col'));
```

Pogoje lahko posredujemo tudi kot polje, katerega elementi se združijo s pomočjo AND:

```php
// WHERE (`price_final` < `price_original`) AND (`stock_count` > `min_stock`)
$table->where([
	'price_final < price_original',
	'stock_count > min_stock',
]);
```

V polju lahko uporabimo pare ključ => vrednost in Nette spet samodejno izbere pravilne operatorje:

```php
// WHERE (`status` = 'active') AND (`id` IN (1, 2, 3))
$table->where([
	'status' => 'active',
	'id' => [1, 2, 3],
]);
```

V polju lahko kombiniramo SQL izraze z nadomestnimi vprašaji in več parametri. To je primerno za kompleksne pogoje z natančno določenimi operatorji:

```php
// WHERE (`age` > 18) AND (ROUND(`score`, 2) > 75.5)
$table->where([
	'age > ?' => 18,
	'ROUND(score, ?) > ?' => [2, 75.5], // dva parametra posredujemo kot polje
]);
```

Večkratni klic `where()` pogoje samodejno združuje s pomočjo AND.


whereOr(array $parameters): static .[method]
--------------------------------------------

Podobno kot `where()` dodaja pogoje, vendar s to razliko, da jih združuje s pomočjo OR:

```php
// WHERE (`status` = 'active') OR (`deleted` = 1)
$table->whereOr([
	'status' => 'active',
	'deleted' => true,
]);
```

Tudi tukaj lahko uporabimo kompleksnejše izraze:

```php
// WHERE (`price` > 1000) OR (`price_with_tax` > 1500)
$table->whereOr([
	'price > ?' => 1000,
	'price_with_tax > ?' => 1500,
]);
```


wherePrimary(mixed $key): static .[method]
------------------------------------------

Doda pogoj za primarni ključ tabele:

```php
// WHERE `id` = 123
$table->wherePrimary(123);

// WHERE `id` IN (1, 2, 3)
$table->wherePrimary([1, 2, 3]);
```

Če ima tabela sestavljen primarni ključ (npr. `foo_id`, `bar_id`), ga posredujemo kot polje:

```php
// WHERE `foo_id` = 1 AND `bar_id` = 5
$table->wherePrimary(['foo_id' => 1, 'bar_id' => 5])->fetch();

// WHERE (`foo_id`, `bar_id`) IN ((1, 5), (2, 3))
$table->wherePrimary([
	['foo_id' => 1, 'bar_id' => 5],
	['foo_id' => 2, 'bar_id' => 3],
])->fetchAll();
```


order(string $columns, ...$parameters): static .[method]
--------------------------------------------------------

Določa vrstni red, v katerem bodo vrnjene vrstice. Lahko razvrščamo po enem ali več stolpcih, v padajočem ali naraščajočem vrstnem redu, ali po lastnem izrazu:

```php
$table->order('created');                   // ORDER BY `created`
$table->order('created DESC');              // ORDER BY `created` DESC
$table->order('priority DESC, created');    // ORDER BY `priority` DESC, `created`
$table->order('status = ? DESC', 'active'); // ORDER BY `status` = 'active' DESC
```


select(string $columns, ...$parameters): static .[method]
---------------------------------------------------------

Določa stolpce, ki naj se vrnejo iz podatkovne baze. V privzetem stanju Nette Database Explorer vrača samo tiste stolpce, ki se dejansko uporabijo v kodi. Metodo `select()` tako uporabljamo v primerih, ko moramo vrniti specifične izraze:

```php
// SELECT *, DATE_FORMAT(`created_at`, "%d.%m.%Y") AS `formatted_date`
$table->select('*, DATE_FORMAT(created_at, ?) AS formatted_date', '%d.%m.%Y');
```

Aliasi, definirani s pomočjo `AS`, so nato dostopni kot lastnosti objekta ActiveRow:

```php
foreach ($table as $row) {
	echo $row->formatted_date;   // dostop do aliasa
}
```


limit(?int $limit, ?int $offset = null): static .[method]
---------------------------------------------------------

Omejuje število vrnjenih vrstic (LIMIT) in po želji omogoča nastavitev odmika (offset):

```php
$table->limit(10);        // LIMIT 10 (vrne prvih 10 vrstic)
$table->limit(10, 20);    // LIMIT 10 OFFSET 20
```

Za stranskanje je primernejša uporaba metode `page()`.


page(int $page, int $itemsPerPage, &$numOfPages = null): static .[method]
-------------------------------------------------------------------------

Olajša stranskanje rezultatov. Sprejme številko strani (šteto od 1) in število postavk na stran. Po želji lahko posredujemo referenco na spremenljivko, v katero se shrani skupno število strani:

```php
$numOfPages = null;
$table->page(page: 3, itemsPerPage: 10, $numOfPages);
echo "Skupaj strani: $numOfPages";
```


group(string $columns, ...$parameters): static .[method]
--------------------------------------------------------

Združuje vrstice po navedenih stolpcih (GROUP BY). Uporablja se običajno v povezavi z agregatnimi funkcijami:

```php
// Prešteje število izdelkov v vsaki kategoriji
$table->select('category_id, COUNT(*) AS count')
	->group('category_id');
```


having(string $having, ...$parameters): static .[method]
--------------------------------------------------------

Nastavi pogoj za filtriranje združenih vrstic (HAVING). Lahko se uporablja v povezavi z metodo `group()` in agregatnimi funkcijami:

```php
// Najde kategorije, ki imajo več kot 100 izdelkov
$table->select('category_id, COUNT(*) AS count')
	->group('category_id')
	->having('count > ?', 100);
```


Branje podatkov
===============

Za branje podatkov iz podatkovne baze imamo na voljo več uporabnih metod:

.[language-php]
| `foreach ($table as $key => $row)` | Iterira čez vse vrstice, `$key` je vrednost primarnega ključa, `$row` je objekt ActiveRow
| `$row = $table->get($key)` | Vrne eno vrstico po primarnem ključu
| `$row = $table->fetch()` | Vrne trenutno vrstico in premakne kazalec na naslednjo
| `$array = $table->fetchPairs()` | Ustvari asociativno polje iz rezultatov
| `$array = $table->fetchAll()` | Vrne vse vrstice kot polje
| `count($table)` | Vrne število vrstic v objektu Selection

Objekt [ActiveRow |api:Nette\Database\Table\ActiveRow] je namenjen samo za branje. To pomeni, da ni mogoče spreminjati vrednosti njegovih lastnosti. Ta omejitev zagotavlja doslednost podatkov in preprečuje nepričakovane stranske učinke. Podatki se nalagajo iz podatkovne baze in vsaka sprememba bi morala biti izvedena eksplicitno in nadzorovano.


`foreach` - iteracija čez vse vrstice
-------------------------------------

Najlažji način za izvedbo poizvedbe in pridobitev vrstic je iteriranje v zanki `foreach`. Samodejno zažene SQL poizvedbo.

```php
$books = $explorer->table('book');
foreach ($books as $key => $book) {
	// $key je vrednost primarnega ključa, $book je ActiveRow
	echo "$book->title ({$book->author->name})";
}
```


get($key): ?ActiveRow .[method]
-------------------------------

Izvede SQL poizvedbo in vrne vrstico po primarnem ključu, ali `null`, če ne obstaja.

```php
$book = $explorer->table('book')->get(123);  // vrne ActiveRow z ID 123 ali null
if ($book) {
	echo $book->title;
}
```


fetch(): ?ActiveRow .[method]
-----------------------------

Vrne vrstico in premakne notranji kazalec na naslednjo. Če ni več vrstic, vrne `null`.

```php
$books = $explorer->table('book');
while ($book = $books->fetch()) {
	$this->processBook($book);
}
```


fetchPairs(string|int|null $key = null, string|int|null $value = null): array .[method]
---------------------------------------------------------------------------------------

Vrne rezultate kot asociativno polje. Prvi argument določa ime stolpca, ki se uporabi kot ključ v polju, drugi argument določa ime stolpca, ki se uporabi kot vrednost:

```php
$authors = $explorer->table('author')->fetchPairs('id', 'name');
// [1 => 'John Doe', 2 => 'Jane Doe', ...]
```

Če navedemo samo prvi parameter, bo vrednost celotna vrstica, torej objekt `ActiveRow`:

```php
$authors = $explorer->table('author')->fetchPairs('id');
// [1 => ActiveRow(id: 1, ...), 2 => ActiveRow(id: 2, ...), ...]
```

V primeru podvojenih ključev se uporabi vrednost iz zadnje vrstice. Pri uporabi `null` kot ključa bo polje indeksirano numerično od nič (takrat do kolizij ne pride):

```php
$authors = $explorer->table('author')->fetchPairs(null, 'name');
// [0 => 'John Doe', 1 => 'Jane Doe', ...]
```


fetchPairs(Closure $callback): array .[method]
----------------------------------------------

Alternativno lahko kot parameter navedete povratni klic (callback), ki bo za vsako vrstico vračal bodisi samo vrednost, bodisi par ključ-vrednost.

```php
$titles = $explorer->table('book')
	->fetchPairs(fn($row) => "$row->title ({$row->author->name})");
// ['Prva knjiga (Jan Novak)', ...]

// Callback lahko vrne tudi polje s parom ključ & vrednost:
$titles = $explorer->table('book')
	->fetchPairs(fn($row) => [$row->title, $row->author->name]);
// ['Prva knjiga' => 'Jan Novak', ...]
```


fetchAll(): array .[method]
---------------------------

Vrne vse vrstice kot asociativno polje objektov `ActiveRow`, kjer so ključi vrednosti primarnih ključev.

```php
$allBooks = $explorer->table('book')->fetchAll();
// [1 => ActiveRow(id: 1, ...), 2 => ActiveRow(id: 2, ...), ...]
```


count(): int .[method]
----------------------

Metoda `count()` brez parametra vrne število vrstic v objektu `Selection`:

```php
$table->where('category', 1);
$count = $table->count();
$count = count($table); // alternativa
```

Pozor, `count()` s parametrom izvaja agregatno funkcijo COUNT v podatkovni bazi, glej spodaj.


ActiveRow::toArray(): array .[method]
-------------------------------------

Pretvori objekt `ActiveRow` v asociativno polje, kjer so ključi imena stolpcev in vrednosti ustrezni podatki.

```php
$book = $explorer->table('book')->get(1);
$bookArray = $book->toArray();
// $bookArray bo ['id' => 1, 'title' => '...', 'author_id' => ..., ...]
```


Agregacija
==========

Razred `Selection` ponuja metode za enostavno izvajanje agregatnih funkcij (COUNT, SUM, MIN, MAX, AVG itd.).

.[language-php]
| `count($expr)` | Prešteje število vrstic
| `min($expr)` | Vrne minimalno vrednost v stolpcu
| `max($expr)` | Vrne maksimalno vrednost v stolpcu
| `sum($expr)` | Vrne vsoto vrednosti v stolpcu
| `aggregation($function)` | Omogoča izvedbo poljubne agregatne funkcije. Npr. `AVG()`, `GROUP_CONCAT()`


count(string $expr): int .[method]
----------------------------------

Izvede SQL poizvedbo s funkcijo COUNT in vrne rezultat. Metoda se uporablja za ugotavljanje, koliko vrstic ustreza določenemu pogoju:

```php
$count = $table->count('*');                 // SELECT COUNT(*) FROM `table`
$count = $table->count('DISTINCT column');   // SELECT COUNT(DISTINCT `column`) FROM `table`
```

Pozor, [#count()] brez parametra samo vrača število vrstic v objektu `Selection`.


min(string $expr) a max(string $expr) .[method]
-----------------------------------------------

Metodi `min()` in `max()` vračata minimalno in maksimalno vrednost v določenem stolpcu ali izrazu:

```php
// SELECT MAX(`price`) FROM `products` WHERE `active` = 1
$maxPrice = $products->where('active', true)
	->max('price');
```


sum(string $expr) .[method]
---------------------------

Vrne vsoto vrednosti v določenem stolpcu ali izrazu:

```php
// SELECT SUM(`price` * `items_in_stock`) FROM `products` WHERE `active` = 1
$totalPrice = $products->where('active', true)
	->sum('price * items_in_stock');
```


aggregation(string $function, ?string $groupFunction = null) .[method]
----------------------------------------------------------------------

Omogoča izvedbo poljubne agregatne funkcije.

```php
// povprečna cena izdelkov v kategoriji
$avgPrice = $products->where('category_id', 1)
	->aggregation('AVG(price)');

// združi oznake izdelka v en niz
$tags = $products->where('id', 1)
	->aggregation('GROUP_CONCAT(tag.name) AS tags')
	->fetch()
	->tags;
```

Če moramo agregirati rezultate, ki so že sami po sebi nastali iz neke agregatne funkcije in združevanja (npr. `SUM(vrednost)` čez združene vrstice), kot drugi argument navedemo agregatno funkcijo, ki naj se uporabi na teh vmesnih rezultatih:

```php
// Izračuna skupno ceno izdelkov na zalogi za posamezne kategorije in nato sešteje te cene skupaj.
$totalPrice = $products->select('category_id, SUM(price * stock) AS category_total')
	->group('category_id')
	->aggregation('SUM(category_total)', 'SUM');
```

V tem primeru najprej izračunamo skupno ceno izdelkov v vsaki kategoriji (`SUM(price * stock) AS category_total`) in združimo rezultate po `category_id`. Nato uporabimo `aggregation('SUM(category_total)', 'SUM')` za seštevanje teh vmesnih vsot `category_total`. Drugi argument `'SUM'` pove, da naj se na vmesne rezultate uporabi funkcija SUM.


Insert, Update & Delete
=======================

Nette Database Explorer poenostavlja vstavljanje, posodabljanje in brisanje podatkov. Vse navedene metode v primeru napake vržejo izjemo `Nette\Database\DriverException`.


Selection::insert(iterable $data) .[method]
-------------------------------------------

Vstavi nove zapise v tabelo.

**Vstavljanje enega zapisa:**

Nov zapis posredujemo kot asociativno polje ali iterable objekt (na primer ArrayHash, ki se uporablja v [obrazcih |forms:]), kjer ključi ustrezajo imenom stolpcev v tabeli.

Če ima tabela definiran primarni ključ, metoda vrne objekt `ActiveRow`, ki se ponovno naloži iz podatkovne baze, da se upoštevajo morebitne spremembe, izvedene na ravni podatkovne baze (sprožilci, privzete vrednosti stolpcev, izračuni auto-increment stolpcev). S tem je zagotovljena doslednost podatkov in objekt vedno vsebuje aktualne podatke iz podatkovne baze. Če enoličnega primarnega ključa nima, vrne posredovane podatke v obliki polja.

```php
$row = $explorer->table('users')->insert([
	'name' => 'John Doe',
	'email' => 'john.doe@example.com',
]);
// $row je instanca ActiveRow in vsebuje celotne podatke vstavljene vrstice,
// vključno s samodejno generiranim ID-jem in morebitnimi spremembami, izvedenimi s sprožilci (triggerji)
echo $row->id; // Izpiše ID novo vstavljenega uporabnika
echo $row->created_at; // Izpiše čas ustvarjanja, če je nastavljen s sprožilcem
```

**Vstavljanje več zapisov hkrati:**

Metoda `insert()` omogoča vstavljanje več zapisov z eno samo SQL poizvedbo. V tem primeru vrne število vstavljenih vrstic.

```php
$insertedRows = $explorer->table('users')->insert([
	[
		'name' => 'John',
		'year' => 1994,
	],
	[
		'name' => 'Jack',
		'year' => 1995,
	],
]);
// INSERT INTO `users` (`name`, `year`) VALUES ('John', 1994), ('Jack', 1995)
// $insertedRows bo 2
```

Kot parameter lahko posredujemo tudi objekt `Selection` z izborom podatkov.

```php
$newUsers = $explorer->table('potential_users')
	->where('approved', 1)
	->select('name, email');

$insertedRows = $explorer->table('users')->insert($newUsers);
```

**Vstavljanje posebnih vrednosti:**

Kot vrednosti lahko posredujemo tudi datoteke, objekte DateTime ali SQL literale:

```php
$explorer->table('users')->insert([
	'name' => 'John',
	'created_at' => new DateTime,           // pretvori v format podatkovne baze
	'avatar' => fopen('image.jpg', 'rb'),   // vstavi binarno vsebino datoteke
	'uuid' => $explorer::literal('UUID()'), // pokliče funkcijo UUID()
]);
```


Selection::update(iterable $data): int .[method]
------------------------------------------------

Posodobi vrstice v tabeli po navedenem filtru. Vrne število dejansko spremenjenih vrstic.

Spremenjene stolpce posredujemo kot asociativno polje ali iterable objekt (na primer ArrayHash, ki se uporablja v [obrazcih |forms:]), kjer ključi ustrezajo imenom stolpcev v tabeli:

```php
$affected = $explorer->table('users')
	->where('id', 10)
	->update([
		'name' => 'John Smith',
		'year' => 1994,
	]);
// UPDATE `users` SET `name` = 'John Smith', `year` = 1994 WHERE `id` = 10
```

Za spremembo številskih vrednosti lahko uporabimo operatorja `+=` in `-=`:

```php
$explorer->table('users')
	->where('id', 10)
	->update([
		'points+=' => 1,  // poveča vrednost stolpca 'points' za 1
		'coins-=' => 1,   // zmanjša vrednost stolpca 'coins' za 1
	]);
// UPDATE `users` SET `points` = `points` + 1, `coins` = `coins` - 1 WHERE `id` = 10
```


Selection::delete(): int .[method]
----------------------------------

Briše vrstice iz tabele po navedenem filtru. Vrne število izbrisanih vrstic.

```php
$count = $explorer->table('users')
	->where('id', 10)
	->delete();
// DELETE FROM `users` WHERE `id` = 10
```

.[caution]
Pri klicu `update()` in `delete()` ne pozabite s pomočjo `where()` določiti vrstic, ki naj se uredijo/izbrišejo. Če `where()` ne uporabite, se operacija izvede na celotni tabeli!


ActiveRow::update(iterable $data): bool .[method]
-------------------------------------------------

Posodobi podatke v podatkovni vrstici, ki jo predstavlja objekt `ActiveRow`. Kot parameter sprejme iterable s podatki, ki naj se posodobijo (ključi so imena stolpcev). Za spremembo številskih vrednosti lahko uporabimo operatorja `+=` in `-=`:

Po izvedbi posodobitve se `ActiveRow` samodejno ponovno naloži iz podatkovne baze, da se upoštevajo morebitne spremembe, izvedene na ravni podatkovne baze (npr. sprožilci). Metoda vrne true samo, če je prišlo do dejanske spremembe podatkov.

```php
$article = $explorer->table('article')->get(1);
$article->update([
	'views += 1',  // povečamo število prikazov
]);
echo $article->views; // Izpiše trenutno število prikazov
```

Ta metoda posodobi samo eno določeno vrstico v podatkovni bazi. Za množično posodabljanje več vrstic uporabite metodo [#Selection::update()].


ActiveRow::delete() .[method]
-----------------------------

Izbriše vrstico iz podatkovne baze, ki jo predstavlja objekt `ActiveRow`.

```php
$book = $explorer->table('book')->get(1);
$book->delete(); // Izbriše knjigo z ID 1
```

Ta metoda briše samo eno določeno vrstico v podatkovni bazi. Za množično brisanje več vrstic uporabite metodo [#Selection::delete()].


Povezave med tabelami
=====================

V relacijskih podatkovnih bazah so podatki razdeljeni na več tabel in medsebojno povezani s pomočjo tujih ključev. Nette Database Explorer prinaša revolucionaren način dela s temi povezavami - brez pisanja JOIN poizvedb in potrebe po kakršnikoli konfiguraciji ali generiranju.

Za ilustracijo dela s povezavami bomo uporabili primer podatkovne baze knjig ([najdete ga na GitHubu |https://github.com/nette-examples/books]). V podatkovni bazi imamo tabele:

- `author` - pisatelji in prevajalci (stolpci `id`, `name`, `web`, `born`)
- `book` - knjige (stolpci `id`, `author_id`, `translator_id`, `title`, `sequel_id`)
- `tag` - oznake (stolpci `id`, `name`)
- `book_tag` - povezovalna tabela med knjigami in oznakami (stolpci `book_id`, `tag_id`)

[* db-schema-1-.webp *] *** Struktura podatkovne baze .<>

V našem primeru podatkovne baze knjig najdemo več tipov odnosov (čeprav je model poenostavljen v primerjavi z realnostjo):

- Ena-proti-mnogo 1:N – vsaka knjiga **ima enega** avtorja, avtor lahko napiše **več** knjig
- Nič-proti-mnogo 0:N – knjiga **lahko ima** prevajalca, prevajalec lahko prevede **več** knjig
- Nič-proti-ena 0:1 – knjiga **lahko ima** naslednji del
- Mnogo-proti-mnogo M:N – knjiga **lahko ima več** oznak in oznaka je lahko dodeljena **več** knjigam

V teh odnosih vedno obstaja nadrejena in podrejena tabela. Na primer v odnosu med avtorjem in knjigo je tabela `author` nadrejena in `book` podrejena - lahko si predstavljamo, da knjiga vedno »pripada« nekemu avtorju. To se odraža tudi v strukturi podatkovne baze: podrejena tabela `book` vsebuje tuji ključ `author_id`, ki se nanaša na nadrejeno tabelo `author`.

Če moramo izpisati knjige vključno z imeni njihovih avtorjev, imamo dve možnosti. Ali podatke pridobimo z eno samo SQL poizvedbo s pomočjo JOIN:

```sql
SELECT book.*, author.name FROM book LEFT JOIN author ON book.author_id = author.id
```

Ali pa podatke naložimo v dveh korakih - najprej knjige in nato njihove avtorje - in jih nato v PHP sestavimo:

```sql
SELECT * FROM book;
SELECT * FROM author WHERE id IN (1, 2, 3);  -- id-ji avtorjev pridobljenih knjig
```

Drugi pristop je dejansko učinkovitejši, čeprav se to morda zdi presenetljivo. Podatki so naloženi samo enkrat in jih je mogoče bolje izkoristiti v predpomnilniku. Prav na ta način deluje Nette Database Explorer - vse rešuje pod površjem in vam ponuja eleganten API:

```php
$books = $explorer->table('book');
foreach ($books as $book) {
	echo 'title: ' . $book->title;
	echo 'written by: ' . $book->author->name; // $book->author je zapis iz tabele 'author'
	echo 'translated by: ' . $book->translator?->name;
}
```


Dostop do nadrejene tabele
--------------------------

Dostop do nadrejene tabele je neposreden. Gre za odnose kot *knjiga ima avtorja* ali *knjiga lahko ima prevajalca*. Povezan zapis pridobimo prek lastnosti objekta ActiveRow - njeno ime ustreza imenu stolpca s tujim ključem brez `_id`:

```php
$book = $explorer->table('book')->get(1);
echo $book->author->name;      // najde avtorja po stolpcu author_id
echo $book->translator?->name; // najde prevajalca po stolpcu translator_id
```

Ko dostopamo do lastnosti `$book->author`, Explorer v tabeli `book` išče stolpec, katerega ime vsebuje niz `author` (torej `author_id`). Po vrednosti v tem stolpcu naloži ustrezen zapis iz tabele `author` in ga vrne kot `ActiveRow`. Podobno deluje tudi `$book->translator`, ki uporabi stolpec `translator_id`. Ker stolpec `translator_id` lahko vsebuje `null`, v kodi uporabimo operator `?->`.

Alternativno pot ponuja metoda `ref()`, ki sprejme dva argumenta, ime ciljne tabele in ime povezovalnega stolpca, ter vrne instanco `ActiveRow` ali `null`:

```php
echo $book->ref('author', 'author_id')->name;      // povezava na avtorja
echo $book->ref('author', 'translator_id')->name;  // povezava na prevajalca
```

Metoda `ref()` je koristna, če ni mogoče uporabiti dostopa prek lastnosti, ker tabela vsebuje stolpec z istim imenom (tj. `author`). V ostalih primerih je priporočljivo uporabljati dostop prek lastnosti, ki je bolj berljiv.

Explorer samodejno optimizira podatkovne poizvedbe. Ko prehajamo skozi knjige v zanki in dostopamo do njihovih povezanih zapisov (avtorjev, prevajalcev), Explorer ne generira poizvedbe za vsako knjigo posebej. Namesto tega izvede samo en SELECT za vsak tip povezave, s čimer bistveno zmanjša obremenitev podatkovne baze. Na primer:

```php
$books = $explorer->table('book');
foreach ($books as $book) {
	echo $book->title . ': ';
	echo $book->author->name;
	echo $book->translator?->name;
}
```

Ta koda pokliče samo te tri bliskovite poizvedbe v podatkovno bazo:

```sql
SELECT * FROM `book`;
SELECT * FROM `author` WHERE (`id` IN (1, 2, 3)); -- id iz stolpca author_id izbranih knjig
SELECT * FROM `author` WHERE (`id` IN (2, 3));    -- id iz stolpca translator_id izbranih knjig
```

.[note]
Logika iskanja povezovalnega stolpca je določena z implementacijo [Conventions |api:Nette\Database\Conventions]. Priporočamo uporabo [DiscoveredConventions |api:Nette\Database\Conventions\DiscoveredConventions], ki analizira tuje ključe in omogoča enostavno delo z obstoječimi relacijami med tabelami.


Dostop do podrejene tabele
--------------------------

Dostop do podrejene tabele deluje v obratni smeri. Zdaj se sprašujemo *katere knjige je napisal ta avtor* ali *prevedel ta prevajalec*. Za ta tip poizvedbe uporabljamo metodo `related()`, ki vrne `Selection` s povezanimi zapisi. Poglejmo si primer:

```php
$author = $explorer->table('author')->get(1);

// Izpiše vse knjige avtorja
foreach ($author->related('book.author_id') as $book) {
	echo "Napisal: $book->title";
}

// Izpiše vse knjige, ki jih je avtor prevedel
foreach ($author->related('book.translator_id') as $book) {
	echo "Prevedel: $book->title";
}
```

Metoda `related()` sprejme opis povezave kot en argument s pikčasto notacijo ali kot dva ločena argumenta:

```php
$author->related('book.translator_id');  // en argument
$author->related('book', 'translator_id');  // dva argumenta
```

Explorer zna samodejno zaznati pravilen povezovalni stolpec na podlagi imena nadrejene tabele. V tem primeru se povezuje prek stolpca `book.author_id`, ker je ime izvorne tabele `author`:

```php
$author->related('book');  // uporabi book.author_id
```

Če bi obstajalo več možnih povezav, Explorer vrže izjemo [AmbiguousReferenceKeyException |api:Nette\Database\Conventions\AmbiguousReferenceKeyException].

Metodo `related()` lahko seveda uporabimo tudi pri prehajanju skozi več zapisov v zanki in Explorer tudi v tem primeru samodejno optimizira poizvedbe:

```php
$authors = $explorer->table('author');
foreach ($authors as $author) {
	echo $author->name . ' napisal:';
	foreach ($author->related('book') as $book) {
		echo $book->title;
	}
}
```

Ta koda generira samo dve bliskoviti SQL poizvedbi:

```sql
SELECT * FROM `author`;
SELECT * FROM `book` WHERE (`author_id` IN (1, 2, 3)); -- id izbranih avtorjev
```


Povezava Mnogo-proti-mnogo
--------------------------

Za povezavo mnogo-proti-mnogo (M:N) je potrebna obstoj povezovalne tabele (v našem primeru `book_tag`), ki vsebuje dva stolpca s tujima ključema (`book_id`, `tag_id`). Vsak od teh stolpcev se nanaša na primarni ključ ene od povezanih tabel. Za pridobitev povezanih podatkov najprej pridobimo zapise iz povezovalne tabele s pomočjo `related('book_tag')` in nato nadaljujemo k ciljnim podatkom:

```php
$book = $explorer->table('book')->get(1);
// izpiše imena oznak, dodeljenih knjigi
foreach ($book->related('book_tag') as $bookTag) {
	echo $bookTag->tag->name;  // izpiše ime oznake prek povezovalne tabele
}

$tag = $explorer->table('tag')->get(1);
// ali obratno: izpiše imena knjig, označenih s to oznako
foreach ($tag->related('book_tag') as $bookTag) {
	echo $bookTag->book->title; // izpiše ime knjige
}
```

Explorer spet optimizira SQL poizvedbe v učinkovito obliko:

```sql
SELECT * FROM `book`;
SELECT * FROM `book_tag` WHERE (`book_tag`.`book_id` IN (1, 2, ...));  -- id izbranih knjig
SELECT * FROM `tag` WHERE (`tag`.`id` IN (1, 2, ...));                 -- id oznak, najdenih v book_tag
```


Poizvedovanje prek povezanih tabel
----------------------------------

V metodah `where()`, `select()`, `order()` in `group()` lahko uporabljamo posebne notacije za dostop do stolpcev iz drugih tabel. Explorer samodejno ustvari potrebne JOINe.

**Pikčasta notacija** (`nadrejena_tabela.stolpec`) se uporablja za odnos 1:N z vidika podrejene tabele:

```php
$books = $explorer->table('book');

// Najde knjige, katerih avtor ima ime, ki se začne na 'Jon'
$books->where('author.name LIKE ?', 'Jon%');

// Razvrsti knjige po imenu avtorja padajoče
$books->order('author.name DESC');

// Izpiše naslov knjige in ime avtorja
$books->select('book.title, author.name');
```

**Dvopična notacija** (`:podrejena_tabela.stolpec`) se uporablja za odnos 1:N z vidika nadrejene tabele:

```php
$authors = $explorer->table('author');

// Najde avtorje, ki so napisali knjigo s 'PHP' v naslovu
$authors->where(':book.title LIKE ?', '%PHP%');

// Prešteje število knjig za vsakega avtorja
$authors->select('*, COUNT(:book.id) AS book_count')
	->group('author.id');
```

V zgornjem primeru z dvopično notacijo (`:book.title`) ni določen stolpec s tujim ključem. Explorer samodejno zazna pravilen stolpec na podlagi imena nadrejene tabele. V tem primeru se povezuje prek stolpca `book.author_id`, ker je ime izvorne tabele `author`. Če bi obstajalo več možnih povezav, Explorer vrže izjemo [AmbiguousReferenceKeyException |api:Nette\Database\Conventions\AmbiguousReferenceKeyException].

Povezovalni stolpec lahko eksplicitno navedemo v oklepaju:

```php
// Najde avtorje, ki so prevedli knjigo s 'PHP' v naslovu
$authors->where(':book(translator_id).title LIKE ?', '%PHP%');
```

Notacije lahko verižimo za dostop prek več tabel:

```php
// Najde avtorje knjig, označenih z oznako 'PHP'
$authors->where(':book:book_tag.tag.name', 'PHP')
	->group('author.id');
```


Razširitev pogojev za JOIN
--------------------------

Metoda `joinWhere()` razširja pogoje, ki se navajajo pri povezovanju tabel v SQL za ključno besedo `ON`.

Recimo, da želimo najti knjige, prevedene s strani določenega prevajalca:

```php
// Najde knjige, prevedene s strani prevajalca z imenom 'David'
$books = $explorer->table('book')
	->joinWhere('translator', 'translator.name', 'David');
// LEFT JOIN author translator ON book.translator_id = translator.id AND (translator.name = 'David')
```

V pogoju `joinWhere()` lahko uporabljamo enake konstrukcije kot v metodi `where()` - operatorje, nadomestne vprašaje, polja vrednosti ali SQL izraze.

Za kompleksnejše poizvedbe z več JOINi lahko definiramo aliase tabel:

```php
$tags = $explorer->table('tag')
	->joinWhere(':book_tag.book.author', 'book_author.born < ?', 1950)
	->alias(':book_tag.book.author', 'book_author');
// LEFT JOIN `book_tag` ON `tag`.`id` = `book_tag`.`tag_id`
// LEFT JOIN `book` ON `book_tag`.`book_id` = `book`.`id`
// LEFT JOIN `author` `book_author` ON `book`.`author_id` = `book_author`.`id`
//    AND (`book_author`.`born` < 1950)
```

Opazite, da medtem ko metoda `where()` dodaja pogoje v klavzulo `WHERE`, metoda `joinWhere()` razširja pogoje v klavzuli `ON` pri povezovanju tabel.