Salt la conținutul principal
Funcțiile logice rulează în sandbox în procese Node.js de scurtă durată — odată ce o rulare se termină, nimic din ce a fost păstrat în memorie nu supraviețuiește. Când ai nevoie să îți amintești ceva între rulări (să păstrezi în cache un răspuns API costisitor, să stochezi un cursor pentru sincronizări incrementale, să aplici debounce sau să transmiți starea de la o funcție la alta), salvează-l în baza de date a workspace-ului. Nu ai nevoie de o primitivă de stocare dedicată pentru asta: un mic obiect tehnic cu un câmp 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 pe key 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ă cu key: { 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âmp DATE_TIME și curăță periodic rândurile vechi dintr-o funcție declanșată de cron.
  • Ce să stochezi. RAW_JSON poate 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âmp FILES și uploadFile.
  • 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.