Datastores¶
Een datastore is een verzameling JSON-records met een naam, in je organisatie. Elk record staat
onder een eigen sleutel, zoals klant-1042 of instellingen. Je applicatie leest en schrijft de
records via de API, een agent doet hetzelfde met tools tijdens een beurt, en een beheerder bekijkt
en bewerkt ze in de console. Denk aan een klantenlijst, de instellingen van een integratie, de
afspraken die een assistent heeft gemaakt, of een kleine productcatalogus.
Wat een datastore vastlegt¶
| Onderdeel | Wat het is |
|---|---|
| Record | één JSON-object onder een sleutel. Core zet zelf het tijdstip van aanmaken en van de laatste wijziging |
| Schema | optioneel: een JSON Schema waaraan elk record moet voldoen. Elke wijziging is een nieuwe schemaversie; een record dat niet voldoet, wordt geweigerd |
| Verwijzing | een veld in een record dat de sleutel van een record in een andere datastore bevat, zoals klant in een bestelling. Core controleert bij het schrijven dat dat record bestaat |
| Eigenaar | een record dat is geschreven voor een persoon, is van die persoon. Een record zonder persoon is gedeeld |
Je vindt een record op zijn sleutel, op het begin van een sleutel, op zijn metadata, of met een zoekopdracht die de records van één datastore filtert en sorteert op hun velden.
Wanneer gebruik je een datastore¶
Gebruik een datastore voor gegevens die je organisatie zelf bijhoudt, met een vorm die je kent, en die een agent niet alleen moet lezen maar ook moet bijwerken. Drie onderdelen lijken erop:
| Je hebt | Gebruik |
|---|---|
| records met vaste velden die een agent opzoekt en wijzigt | een datastore |
| documenten waarin een agent zoekt naar wat bij een vraag past | kennis |
| losse feiten die een agent onthoudt tussen gesprekken | geheugen |
Een datastore is geen database. Een zoekopdracht combineert geen datastores, telt en sommeert niet, en leest alle records van de datastore. Een datastore bevat daarom standaard hoogstens 50.000 records. Gegevens die onbeperkt groeien, zoals een logboek, of vragen die records van verschillende soorten combineren, horen in je eigen database. Je applicatie kan die gegevens dan aan een agent geven met een tool.
Per persoon¶
Een verzoek of beurt die een persoon noemt (Bouwen voor
personen), leest de records van die persoon en de gedeelde,
en schrijft records voor die persoon. Anna en Bob kunnen zo elk een eigen record voorkeuren
hebben, naast een gedeeld record onder dezelfde sleutel. Wis je een persoon, dan verdwijnen haar
records mee, behalve in een datastore die je voor je boekhouding bewaart, zoals facturen. Zo'n
datastore markeer je met retained_for: "bookkeeping", wat een eigen termijn in
record_ttl_days vereist: de records blijven, nog altijd de hare, tot die termijn is verstreken.
Core houdt geen lijst van gewiste personen bij, dus een later verzoek met het id van dezelfde
persoon bereikt die bewaarde records weer. Zo'n datastore is niet te verwijderen (409) tot je
retained_for leegmaakt. Een verzoek zonder persoon leest en schrijft de gedeelde records.
Gelijktijdig schrijven¶
Elk record heeft een etag die bij elke schrijfactie verandert. Stuur die terug in If-Match als
je het record schrijft of verwijdert, en Core weigert de schrijfactie met 412 als iemand het
record heeft gewijzigd sinds je het las. Zo overschrijven twee mensen die één winkelwagen bewerken
elkaar nooit ongemerkt. Stuur If-None-Match: * om een record alleen aan te maken als de sleutel
nog vrij is. De tools put en delete van een agent nemen dezelfde etag als if_match.
Wil je meerdere records tegelijk wijzigen, stuur dan tot honderd schrijfacties in één batch naar
POST /datastores/batch: Core voert ze allemaal uit of geen enkele. Een batch kan ook het volgende
nummer van een teller nemen en dat als sleutel gebruiken, zodat je bij een bestelling in één stap
het nummer neemt, de bestelling opslaat en de voorraad verlaagt. Een schema kan bovendien één veld
uniek maken, zoals een artikelnummer: geen twee records van één eigenaar -- de gedeelde records, of
die van één persoon -- hebben daar dezelfde waarde, en een tweede wordt geweigerd met 409 met de
naam van het veld. De waarde moet tekst of een geheel getal zijn.
Een datastore kan zijn schrijfacties ook aankondigen: zet emit_events aan en elk geschreven of
verwijderd record levert een gebeurtenis datastore.record.written of datastore.record.deleted op,
waar een workflowtrigger of een webhook op kan reageren. De
gebeurtenis noemt de datastore en de sleutel, nooit de inhoud van het record (zo werkt het).
Regels die een schema niet kan uitdrukken, zoals naar welke status een bestelling hierna mag, horen in een functie die de datastore als schrijffunctie noemt: die ziet elke schrijfactie en het record dat ze vervangt, mag het record aanvullen en mag de schrijfactie met een eigen reden weigeren (Hoe).
Hoe het samenhangt¶
- Een datastore hoort bij één organisatie en vereist de capability
datastores, in het plafond van de organisatie en op de sleutel. - Elke datastore levert vijf tools aan een agent:
get,list,query,putendelete. Geef een agent die alleen mag lezen, alleen de eerste drie. - De policy van een sleutel bepaalt welke datastores hij bereikt, op naam, en welke records een persoon bereikt.
- Records vallen onder de bewaartermijn van de organisatie, gerekend vanaf hun laatste wijziging.
Een datastore die zijn records bewaart (
retention: "keep"), voor records die je bijhoudt zoals een catalogus of profielen, valt daar buiten, net als een datastore die je voor de boekhouding bewaart: die records gaan alleen op de eigen termijn van de datastore. Een datastore kan ook een eigen termijn hebben, zoals een week voor winkelwagens. Wis je een persoon, dan verdwijnen haar records ook uit een datastore die zijn records bewaart, maar niet uit een die je voor de boekhouding bewaart. - Een datastore kan niet in een publicatie. Een oplossing die er een nodig heeft, maakt hem in elke organisatie waar ze is geïnstalleerd.
Verder¶
- Datastores: een datastore aanmaken, een schema vastleggen, records schrijven, zoeken, en de tools aan een agent geven.
- Bouwen voor personen: personen noemen en regels per persoon.
- Kennis en Geheugen: de twee onderdelen die erop lijken.