json_extract în SQLite

json_extract(json, cale)
json_extract(json, cale1, cale2, ...)
json_valid(json)
json_array_length(json [, cale])

Ce face json_extract

SQLite nu are un tip de coloană JSON: documentele JSON se păstrează într-o coloană TEXT, iar funcțiile JSON le citesc la cerere. json_extract primește textul JSON și o cale. Calea începe mereu cu $ (tot documentul); .nume intră într-un obiect, [0] alege elementul dintr-un tablou, iar [#-1] înseamnă ultimul element.

Pentru valori simple (text, număr, true/false, null) rezultatul este o valoare SQL obișnuită: textul vine fără ghilimele, true devine 1. Pentru un obiect sau un tablou primești textul JSON al acelei părți. Dacă dai mai multe căi, rezultatul este un tablou JSON cu toate valorile. O cale care nu există întoarce NULL.

json_valid(x) întoarce 1 dacă textul este JSON corect (după standardul RFC 8259) și 0 altfel; json_array_length numără elementele unui tablou. Funcțiile JSON sunt incluse implicit din SQLite 3.38.0; în versiunile mai vechi, începând cu 3.9.0, erau o extensie (JSON1) activată la compilare.

Parametri

Parametru	Descriere
json	Textul JSON: o coloană sau o valoare scrisă direct.
cale	Calea spre valoare: $, $.cheie, $.tablou[0], $.tablou[#-1].

Ce returnează

Valoarea găsită (INTEGER, REAL, TEXT sau NULL) ori textul JSON pentru obiecte și tablouri.

Exemple

Exemplele de pe această pagină pornesc de la datele de mai jos. Rulează mai întâi acest cod, apoi exemplul.

CREATE TABLE comenzi (
  id      INTEGER PRIMARY KEY,
  client  TEXT NOT NULL,
  detalii TEXT NOT NULL      -- document JSON
);
INSERT INTO comenzi (client, detalii) VALUES
  ('Ana',   '{"oras": "Iași", "produse": [{"nume": "carte", "pret": 45}, {"nume": "pix", "pret": 5}], "livrare": {"curier": "FAN", "cost": 15}}'),
  ('Vlad',  '{"oras": "Cluj", "produse": [{"nume": "caiet", "pret": 12}], "livrare": {"curier": "Poșta", "cost": 8}}'),
  ('Elena', '{"oras": "Iași", "produse": [], "livrare": {"curier": "FAN", "cost": 15}}');

Exemplul 1: Câmpuri simple și câmpuri din interior

Primul produs al Elenei nu există (tabloul e gol), așa că json_extract întoarce NULL, afișat ca celulă goală.

SELECT client,
       json_extract(detalii, '$.oras')             AS oras,
       json_extract(detalii, '$.livrare.curier')   AS curier,
       json_extract(detalii, '$.produse[0].nume')  AS primul_produs,
       json_array_length(detalii, '$.produse')     AS nr_produse
FROM comenzi
ORDER BY id;

Rezultat

╭────────┬──────┬────────┬───────────────┬────────────╮
│ client │ oras │ curier │ primul_produs │ nr_produse │
╞════════╪══════╪════════╪═══════════════╪════════════╡
│ Ana    │ Iași │ FAN    │ carte         │          2 │
│ Vlad   │ Cluj │ Poșta  │ caiet         │          1 │
│ Elena  │ Iași │ FAN    │               │          0 │
╰────────┴──────┴────────┴───────────────┴────────────╯

Exemplul 2: Filtrare și sortare după o valoare din JSON

Valorile extrase pot fi folosite în WHERE, ORDER BY și GROUP BY la fel ca o coloană. Costul livrării este număr, deci compararea cu 10 este numerică.

SELECT client, json_extract(detalii, '$.livrare.cost') AS cost_livrare
FROM comenzi
WHERE json_extract(detalii, '$.livrare.cost') > 10
ORDER BY client;

SELECT json_extract(detalii, '$.oras') AS oras, COUNT(*) AS comenzi
FROM comenzi
GROUP BY oras
ORDER BY oras;

Rezultat

╭────────┬──────────────╮
│ client │ cost_livrare │
╞════════╪══════════════╡
│ Ana    │           15 │
│ Elena  │           15 │
╰────────┴──────────────╯
╭──────┬─────────╮
│ oras │ comenzi │
╞══════╪═════════╡
│ Cluj │       1 │
│ Iași │       2 │
╰──────┴─────────╯

Exemplul 3: Mai multe căi, ultimul element și validare

Cu două căi, rezultatul este un tablou JSON. [#-1] alege ultimul element al tabloului. json_valid arată că al doilea text nu este JSON corect (cheia nu are ghilimele).

SELECT json_extract(detalii, '$.oras', '$.livrare.cost') AS doua_valori,
       json_extract(detalii, '$.produse[#-1].nume')     AS ultimul_produs
FROM comenzi WHERE client = 'Ana';

SELECT json_valid('{"oras": "Iași"}') AS corect,
       json_valid('{oras: "Iași"}')   AS gresit;

Rezultat

╭─────────────┬────────────────╮
│ doua_valori │ ultimul_produs │
╞═════════════╪════════════════╡
│ ["Iași",15] │ pix            │
╰─────────────┴────────────────╯
╭────────┬────────╮
│ corect │ gresit │
╞════════╪════════╡
│      1 │      0 │
╰────────┴────────╯

Exemplul 4: Calea trebuie să înceapă cu $

Fără $, json_extract nu recunoaște calea. Operatorul ->> acceptă și forma scurtă 'oras'.

SELECT json_extract('{"oras": "Iași"}', 'oras');

Rezultat (eroare)

Error near line 1: bad JSON path: 'oras'

Greșeli frecvente

• Uiți $ la începutul căii și primești „bad JSON path”. Calea corectă este '$.oras', nu 'oras'.
• Păstrezi în coloană text care nu este JSON valid (o acoladă lipsă, o virgulă în plus). Funcțiile JSON dau eroarea „malformed JSON” pe acel rând; verifică datele la inserare cu CHECK (json_valid(detalii)).
• Filtrezi des după o valoare JSON într-un tabel mare. Fiecare rând trebuie citit și analizat; creează un index pe expresie, de exemplu CREATE INDEX ... ON comenzi(json_extract(detalii, '$.oras')).

Comenzi înrudite

• Operatorii -> și ->>: Prescurtări pentru citirea din JSON: -> întoarce o bucată de JSON, ->> întoarce valoarea SQL, fără ghilimele.
• json_each / json_tree: Transformă un tablou sau un obiect JSON în rânduri, ca să poți filtra, număra și lega elementele lui cu alte tabele.
• json_set / json_insert / json_replace / json_remove: Modifică un document JSON: adaugă sau schimbă chei, adaugă la un tablou, șterge chei, și întoarce documentul nou.
• Index pe expresii: Indexează rezultatul unei expresii, de exemplu lower(email) sau un câmp JSON, ca să cauți rapid după valoarea calculată.