key și un câmp value îți oferă o stocare cheie-valoare durabilă, limitată la workspace, care poate fi interogată prin același client API tipizat pe care îl folosești deja pentru înregistrări.
Definește obiectul de stocare
Declară un obiect personalizat cu două câmpuri —key (un TEXT unic) și value (un RAW_JSON astfel încât să poți stoca orice payload serializabil JSON). Vezi Objects pentru referința completă defineObject.
src/objects/kv-store.object.ts
Aplică unicitatea cheii
Adaugă un index unic pekey astfel încât aceeași cheie să nu poată avea niciodată două rânduri. Acesta este primitiva recomandată pentru unicitate — vezi Data → Unique indexes.
src/indexes/kv-store-key.index.ts
Citește și scrie dintr-o funcție logică
Înfășoară obiectul în câțiva helperi mici astfel încât restul codului tău să se comporte ca un API de tip cheie-valoare —get, set și del. Aceștia folosesc CoreApiClient, care este generat din schema workspace-ului tău și este complet tipizat față de obiectul kvStore.
src/logic-functions/handlers/kv-store.ts
Indexul unic protejează împotriva duplicatelor, dar două rulări care scriu aceeași cheie nouă în același moment pot totuși să intre în cursă între căutare și creare. Tratează o creare care eșuează pe constrângerea de unicitate ca pe „altcineva a câștigat” — intercepteaz-o și recitește, sau reîncearcă sub formă de actualizare.
Folosește-l: păstrează în cache un apel costisitor
O utilizare tipică este păstrarea în cache a unui răspuns lent sau cu limitare de rată de la un terț, astfel încât rulările repetate să îl refolosească în loc să plătească costul de fiecare dată.src/logic-functions/getExchangeRate.logic-function.ts
Tipare și sfaturi
- Spații de nume. Prefixează cheile pentru a separa domeniile diferite și pentru a face ușoare căutările în masă —
sync-cursor:linear,cache:exchange-rate:USD:EUR,lock:nightly-report. Filtrează cukey: { like: 'cache:%' }pentru a lista sau a curăța un întreg namespace. - Expiry (TTL). Store-ul nu are expirare integrată. Stochează un timestamp în interiorul câmpului
value(ca în exemplul de cache) și verifică-l la citire, sau adaugă un câmpDATE_TIMEși curăță periodic rândurile vechi dintr-o funcție declanșată de cron. - Ce să stochezi.
RAW_JSONpoate conține orice valoare serializabilă JSON — numere, stringuri, array-uri, obiecte. Păstrează intrările mici; acesta este pentru coordonare și caching, nu pentru blob-uri mari sau fișiere. Pentru fișiere, folosește un câmpFILESșiuploadFile. - Vizibilitate și permisiuni. Rândurile trăiesc în baza de date a workspace-ului ca orice altă înregistrare, astfel încât pot fi interogate prin API și respectă rolul aplicației tale. Pentru a ține store-ul în afara UI-ului principal, nu îl include în navigation menu.
- Limitare la o înregistrare. Ai nevoie de stare per înregistrare în loc de chei globale? Adaugă o relație de la obiectul de stocare la obiectul țintă, în loc să codifici ID-ul în cheie.
Aceasta este o convenție, nu o funcționalitate separată — „KV Store-ul” este doar un obiect personalizat obișnuit pe care îl definești și îl interoghezi cu API-ul standard. Asta înseamnă că beneficiază de același mecanism de sincronizare, aceleași permisiuni și același tooling ca restul datelor aplicației tale.