Een query opslaan

Doel

Een vraag — "openstaande deals naar branche van het account, dit kwartaal" — onder een naam opslaan, zodat een grafiek, een rapport, een dashboard en een export allemaal dezelfde vraag kunnen stellen door die naam te noemen, in plaats van elk een eigen kopie mee te dragen.

Waarom dit bestaat

Kopieën van een vraag lopen uit elkaar. Iemand scherpt het filter van de grafiek aan en niet dat van het rapport; zes maanden later verschillen de twee vier procent en kan niemand zeggen welke klopt, omdat elk er op zijn eigen plek volkomen correct uitziet.

Een opgeslagen query heeft één definitie. Corrigeer haar één keer en alles wat haar noemt, is gecorrigeerd — ook in Test en Productie bij de volgende import van de oplossing, omdat een opgeslagen query in de oplossing meereist, net als een tabel of een formulier.

Het is een vraag, geen toegang tot een antwoord. Wie een opgeslagen query uitvoert, ziet precies wat zijn eigen machtigingen toestaan, precies zoals in een lijst met dezelfde records. Een query opslaan leent niemand jouw toegang, en een query op een tabel richten die iemand niet mag lezen, laat hem die niet lezen.

Vereisten

Je bent aangemeld als maker, met een oplossing en een omgeving geselecteerd.
De tabellen die de query leest, bestaan al in die omgeving.

Stappen

Open je oplossing en kies Opgeslagen query's.
Selecteer Nieuw. De queryontwerper opent op een eigen pagina.
Geef haar een weergavenaam — de logische naam vult zich in terwijl je typt.
Schrijf een korte beschrijving. Wie later een dashboard op deze query richt, ben vaak niet jij, en een naam zegt zelden welke records de query weglaat.
Bouw de query. Eenvoudig is een tabel, de kolommen, een filter en een sortering; Geavanceerd voegt gerelateerde tabellen, groeperen met metingen en de opties toe; JSON is het document zelf. De drie zijn weergaven van één query, dus ze kunnen het nooit oneens zijn. Een query ontwerpen loopt het allemaal door.

Het kleinste nuttige document noemt een tabel en verder niets:
```
{
  "entity": "par_deal"
}
```
De volledige vorm is het parsware-query@1-schema, en dat is ook wat je een AI-assistent zou geven die je vraagt er een voor je te schrijven.
Selecteer Opslaan. Het platform controleert drie dingen: dat het artefact goed gevormd is, dat het document een geldige query is, en dat ze hier daadwerkelijk zou draaien — elk veld, elke koppeling, groepering en meting opgelost tegen de echte tabellen van deze omgeving. Een verkeerd gespeld veld wordt nu geweigerd, door jou, in plaats van later gevonden door wie het dashboard opent.
Kies Voorbeeld om haar uit te voeren en te zien wat er terugkomt — vanuit de ontwerper, of vanuit de lijst met de query geselecteerd.

Twee vormen: records of groepen

Of het document een aggregate-blok heeft, is het hele verschil, en de lijst zegt in de kolom Geeft terug welke vorm elke query heeft.

Records — een pagina met overeenkomende rijen, wat een raster of een export wil:

{
  "entity": "par_deal",
  "select": ["par_name", "par_amount"],
  "filter": {
    "connector": "And",
    "conditions": [
      { "field": "par_status", "operator": "Equals", "value": "Open" }
    ]
  },
  "order": [{ "field": "par_amount", "descending": true }]
}

Groepen — totalen, wat een grafiek of een KPI-tegel wil. Deze query koppelt ook, en dat is wat een query kan en een weergave niet: ze leest een kolom uit het account van de deal. De ontwerper bouwt dit allemaal — de koppeling wordt uit een relatie gekozen in plaats van getypt.

{
  "entity": "par_deal",
  "links": [
    {
      "alias": "acct",
      "entity": "par_account",
      "from": "par_accountid",
      "to": "id",
      "kind": "outer"
    }
  ],
  "aggregate": {
    "groupBy": [{ "field": "acct.par_industry" }],
    "measures": [{ "alias": "revenue", "function": "Sum", "field": "par_amount" }]
  },
  "order": [{ "field": "revenue", "descending": true }],
  "top": 10
}

Zodra een tabel onder een alias is gekoppeld, heten haar kolommen overal in het document alias.column — in filters, groeperingen, metingen en sorteringen.

Elke gekoppelde tabel wordt op zichzelf gecontroleerd. Mag je deals lezen maar geen accounts, dan wordt deze query geweigerd in plaats van je stilletjes accountkolommen te geven; mag je maar enkele accounts lezen, dan zie je nog steeds elke deal, waarbij de accounts die je niet mag zien gewoon niet zijn gekoppeld.

Een opgeslagen query gebruiken

Alles wat een query uitvoert, kan deze noemen in plaats van een eigen query te houden — en een met de hand geschreven app of besturingselement kan dat ook, via runtime.data.runSavedQuery("par_revenue_by_industry").

Wat haar uitvoert, mag de query verfijnen — een filter toevoegen, om een bepaalde pagina vragen, een tijdzone kiezen voor het groeperen op datum — maar kan niet wijzigen wat de query leest, koppelt of meet. Een toegevoegd filter wordt met het jouwe gecombineerd in plaats van het te vervangen, dus een query die geannuleerde bestellingen uitsluit, blijft ze uitsluiten, hoe ze ook wordt gebruikt.

De naam kan niet worden gewijzigd

De logische naam is wat elke grafiek, elk rapport en elk dashboard opslaat, dus hem hernoemen zou ze allemaal tegelijk en stilletjes breken. Al het andere — de weergavenaam, de beschrijving, het hele document, zelfs de tabel die ze leest — kun je wijzigen wanneer je maar wilt.

Haar tussen omgevingen verplaatsen

Een opgeslagen query is een oplossingsonderdeel, ondergebracht onder de tabel die ze leest. Voeg haar aan je oplossing toe via de lijst Onderdelen beheren van die tabel (ze staat onder Opgeslagen query's), en ze wordt samen met al het andere geëxporteerd en geïmporteerd. Bij het importeren wordt ze op dezelfde manier gecontroleerd tegen de tabellen van de doelomgeving als hier.

Als je de oplossing verwijdert, gaan haar opgeslagen query's mee. Alles elders wat er nog een noemt, mislukt dan met de naam erbij, en dat is de eerlijke uitkomst — de vraag hoorde bij de oplossing die is vertrokken.

Problemen oplossen

"The query document is not valid JSON." — een ontbrekende komma of haakje. Het vak maakt niet opnieuw op wat je typt, dus wat je ziet, is wat is verzonden.
"A saved query must name the table it reads." — voeg "entity": "your_table" toe. Dat is optioneel als een query door een scherm wordt verzonden (het scherm kent de tabel al) en hier verplicht, omdat een opgeslagen query alleen op naam wordt gevonden.
"Unknown field …" — de naam is verkeerd gespeld, of hij hoort bij een gekoppelde tabel en heeft de alias ervoor nodig (acct.par_industry, niet par_industry).
"You did not join that table" — een veld is voorzien van een alias die geen enkele koppeling declareert. Vergelijk de spelling van de alias met de lijst links.
Voorbeeld zegt dat je de tabel niet mag lezen. — je kunt geen query opslaan die je niet zou kunnen uitvoeren; dat is bewust, want een query die je niet kunt uitvoeren, is een query die je niet kunt testen. Vraag een beheerder om leesrechten op de betrokken tabellen.
Een gegroepeerde query geeft getallen terug die te groot zijn. — een koppeling in de een-op-veel-richting herhaalt de bovenliggende rij één keer per overeenkomst, en de totalen tellen de herhalingen mee. Een zoekveld volgen (het gebruikelijke geval) kan dit niet doen; koppelen naar een onderliggende tabel wel.

Doel​

Waarom dit bestaat​

Vereisten​

Stappen​

Twee vormen: records of groepen​

Een opgeslagen query gebruiken​

De naam kan niet worden gewijzigd​

Haar tussen omgevingen verplaatsen​

Problemen oplossen​

Gerelateerde scenario's​