Direkt zum Hauptinhalt

Abfrage speichern

Ziel​

Eine Frage – „offene Deals nach Branche des Accounts, in diesem Quartal“ – unter einem Namen speichern, sodass ein Diagramm, ein Bericht, ein Dashboard und ein Export alle dieselbe Frage stellen können, indem sie sie benennen, statt jeweils eine eigene Kopie mitzuführen.

Warum es das gibt​

Kopien einer Frage driften auseinander. Jemand verschärft den Filter des Diagramms, aber nicht den des Berichts; sechs Monate später weichen die beiden um vier Prozent voneinander ab, und niemand kann sagen, welche stimmt, weil jede dort, wo sie steht, völlig korrekt aussieht.

Eine gespeicherte Abfrage hat eine einzige Definition. Korrigieren Sie sie einmal, und alles, was sie benennt, ist korrigiert – auch in Test und Produktion beim nächsten Import der Lösung, denn eine gespeicherte Abfrage reist wie eine Tabelle oder ein Formular in der Lösung mit.

Sie ist eine Frage, kein Zugang zu einer Antwort. Wer eine gespeicherte Abfrage ausführt, sieht genau das, was seine eigenen Berechtigungen erlauben – genau wie in einer Liste derselben Datensätze. Eine Abfrage zu speichern leiht niemandem Ihren Zugriff, und eine Abfrage auf eine Tabelle zu richten, die jemand nicht lesen darf, erlaubt ihm nicht, sie zu lesen.

Voraussetzungen​

  • Sie sind als Ersteller angemeldet, und eine Lösung sowie eine Umgebung sind ausgewählt.
  • Die Tabellen, die die Abfrage liest, sind in dieser Umgebung bereits vorhanden.

Schritte​

  1. Öffnen Sie Ihre Lösung, und wählen Sie Gespeicherte Abfragen.

  2. Wählen Sie Neu. Der Abfrage-Designer öffnet sich auf einer eigenen Seite.

  3. Geben Sie ihr einen Anzeigenamen – der logische Name füllt sich während der Eingabe selbst aus.

  4. Schreiben Sie eine kurze Beschreibung. Wer später ein Dashboard auf diese Abfrage richtet, sind oft nicht Sie, und ein Name sagt selten, welche Datensätze die Abfrage auslässt.

  5. Bauen Sie die Abfrage auf. Einfach ist eine Tabelle, ihre Spalten, ein Filter und eine Sortierung; Erweitert fügt verknüpfte Tabellen, Gruppierung mit Kennzahlen und die Optionen hinzu; JSON ist das Dokument selbst. Die drei sind Sichten auf eine Abfrage und können daher nie voneinander abweichen. Abfrage entwerfen führt durch alles.

    Das kleinste sinnvolle Dokument nennt eine Tabelle und sonst nichts:

    {
      "entity": "par_deal"
    }

    Die vollständige Form ist das Schema parsware-query@1, das Sie auch einem KI-Assistenten geben würden, den Sie bitten, eine Abfrage für Sie zu schreiben.

  6. Wählen Sie Speichern. Die Plattform prüft drei Dinge: dass das Artefakt wohlgeformt ist, dass das Dokument eine gültige Abfrage ist und dass sie hier tatsächlich ausführbar wäre – jedes Feld, jede Verknüpfung, jede Gruppierung und jede Kennzahl gegen die echten Tabellen dieser Umgebung aufgelöst. Ein falsch geschriebenes Feld wird jetzt abgelehnt, von Ihnen bemerkt, statt später von demjenigen gefunden zu werden, der das Dashboard öffnet.

  7. Wählen Sie Vorschau, um sie auszuführen und zu sehen, was zurückkommt – entweder im Designer oder in der Liste bei ausgewählter Abfrage.

Zwei Formen: Datensätze oder Gruppen​

Ob das Dokument einen aggregate-Block hat, ist der ganze Unterschied, und die Liste zeigt in der Spalte Rückgabe, welche Form jede Abfrage hat.

Datensätze – eine Seite passender Zeilen, wie ein Raster oder ein Export sie braucht:

{
  "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 }]
}

Gruppen – Summen, wie ein Diagramm oder eine KPI-Kachel sie braucht. Diese Abfrage verknüpft außerdem, was eine Abfrage kann und eine Ansicht nicht: Sie liest eine Spalte aus dem Account des Deals. Der Designer baut das alles auf – die Verknüpfung wird aus einer Beziehung ausgewählt statt eingetippt.

{
  "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
}

Sobald eine Tabelle unter einem Alias eingebunden ist, heißen ihre Spalten überall im Dokument alias.column – in Filtern, Gruppierungen, Kennzahlen und Sortierungen gleichermaßen.

Jede eingebundene Tabelle wird eigenständig geprüft. Dürfen Sie Deals lesen, aber keine Accounts, wird diese Abfrage abgelehnt, statt Ihnen stillschweigend Account-Spalten zu liefern; dürfen Sie nur einige Accounts lesen, sehen Sie trotzdem jeden Deal, wobei die Accounts, die Sie nicht sehen dürfen, einfach nicht angehängt sind.

Eine gespeicherte Abfrage verwenden​

Alles, was eine Abfrage ausführt, kann stattdessen diese benennen, statt eine eigene zu führen – auch eine von Hand geschriebene App oder ein Steuerelement, über runtime.data.runSavedQuery("par_revenue_by_industry").

Was sie ausführt, darf die Abfrage eingrenzen – einen Filter hinzufügen, eine bestimmte Seite anfordern, eine Zeitzone für die Datumsgruppierung wählen –, aber nicht ändern, was die Abfrage liest, verknüpft oder misst. Ein hinzugefügter Filter wird mit Ihrem kombiniert, statt ihn zu ersetzen; eine Abfrage, die stornierte Bestellungen ausschließt, schließt sie also weiterhin aus, egal wie sie verwendet wird.

Der Name lässt sich nicht ändern​

Den logischen Namen speichert jedes Diagramm, jeder Bericht und jedes Dashboard; eine Umbenennung würde sie alle auf einmal und stillschweigend kaputt machen. Alles andere – den Anzeigenamen, die Beschreibung, das ganze Dokument, sogar die gelesene Tabelle – können Sie jederzeit ändern.

Zwischen Umgebungen übertragen​

Eine gespeicherte Abfrage ist eine Lösungskomponente, abgelegt unter der Tabelle, die sie liest. Fügen Sie sie Ihrer Lösung über die Liste Komponenten verwalten dieser Tabelle hinzu (sie erscheint unter Gespeicherte Abfragen), und sie wird mit allem anderen exportiert und importiert. Beim Import wird sie gegen die Tabellen der Zielumgebung genauso geprüft wie hier.

Wird die Lösung deinstalliert, gehen ihre gespeicherten Abfragen mit. Alles andere, was noch eine davon benennt, schlägt dann unter Nennung des Namens fehl – das ist das ehrliche Ergebnis: Die Frage gehörte zu der Lösung, die gegangen ist.

Fehlerbehebung​

  • „The query document is not valid JSON.“ – Ein Komma oder eine Klammer fehlt. Das Feld formatiert Ihre Eingabe nicht um; was Sie sehen, ist also das, was gesendet wurde.
  • „A saved query must name the table it reads.“ – Fügen Sie "entity": "your_table" hinzu. Das ist optional, wenn eine Abfrage von einem Bildschirm gesendet wird (der Bildschirm kennt die Tabelle bereits), hier aber erforderlich, weil eine gespeicherte Abfrage allein über ihren Namen gefunden wird.
  • „Unknown field …“ – Der Name ist falsch geschrieben, oder er gehört zu einer eingebundenen Tabelle und braucht deren Alias davor (acct.par_industry, nicht par_industry).
  • „You did not join that table“ – Ein Feld ist mit einem Alias qualifiziert, den keine Verknüpfung deklariert. Vergleichen Sie die Schreibweise des Alias mit der Liste links.
  • Die Vorschau meldet, dass Sie die Tabelle nicht lesen dürfen. – Sie können keine Abfrage speichern, die Sie nicht ausführen könnten; das ist Absicht, denn eine Abfrage, die Sie nicht ausführen können, können Sie nicht testen. Bitten Sie einen Administrator um Leserechte für die beteiligten Tabellen.
  • Eine gruppierte Abfrage liefert zu große Zahlen. – Eine Verknüpfung in 1:n-Richtung wiederholt die übergeordnete Zeile einmal pro Treffer, und die Summen zählen die Wiederholungen mit. Einem Nachschlagefeld zu folgen (der übliche Fall) kann das nicht verursachen; eine Verknüpfung zu einer untergeordneten Tabelle schon.

Verwandte Szenarien​