Query-Context-Parameter

Ein Query-Context-Parameter ist ein benannter, getypter Wert, den die Engine pro Anfrage aus den Session-Attributen der Verbindung auflöst. Anders als ein berechneter Member (zur Autorenzeit fest) oder Looker-Style-Liquid (beliebiges Laufzeit-SQL) ist ein Query-Parameter begrenzt und gekapselt: Er ist getypt, optional auf eine feste Menge erlaubter Werte beschränkt und kann nur als Bind-Value verwendet werden – niemals in SQL interpoliert.

Sie deklarieren einen <QueryParameter> einmal im Schema, liefern seinen Wert zur Verbindungszeit über eine session.<name>-Property und referenzieren ihn dort, wo die Engine einen gebundenen Wert akzeptiert – heute in der predicate-basierten Zeilensicherheit.

Hinweis

Dies ist ein anderes Element als das Legacy-<Parameter> (ein MDX-ParamRef, dessen Standardwert ein MDX-Ausdruck ist). Ein <QueryParameter> ist eine Laufzeit-Bindung – ein getypter Wert, der aus dem Request-Kontext gespeist wird – kein MDX-Parameter.

Das Sicherheitsmodell

Die No-Injection-Garantie kommt aus Typisierung plus Enumeration, nicht aus Escaping:

• Jeder gelieferte Wert wird auf den deklarierten Typ (String, Numeric, Date, Member) gecastet und, wenn eine Menge erlaubter Werte deklariert ist, gegen sie geprüft – bevor er jemals Teil einer Abfrage werden kann.
• Ein Wert mit falschem Typ oder außerhalb der erlaubten Menge wird zur Verbindungszeit abgelehnt (die Verbindung schlägt laut fehl), wird niemals still durchgereicht.
• Der validierte Wert erreicht SQL nur als gebundenes Literal an einem einzigen, geprüften Substitutionspunkt. Es gibt kein freies Templating.

Einen Parameter deklarieren

Ein <QueryParameter> ist ein Schema-Top-Level-Element (neben <Role>). Geben Sie ihm einen name, einen type, einen optionalen defaultValue und eine optionale Liste von <QueryParameterValue>-erlaubten Werten (die geschlossene Enumeration).

XML

<QueryParameter name="region" type="String" defaultValue="EAST">
  <QueryParameterValue>EAST</QueryParameterValue>
  <QueryParameterValue>WEST</QueryParameterValue>
</QueryParameter>

YAML

parameters:
  - name: region
    type: String
    default_value: EAST
    allowed_values: [EAST, WEST]

type	Gecastet zu	Anmerkungen
String	String
Numeric	Zahl
Date	ISO-Datum (yyyy-MM-dd)
Member	Blattschlüssel eines Members	Nur Single-Key-Ebenen

Wenn allowed_values weggelassen wird, ist der Parameter unbeschränkt (immer noch typgeprüft). Ein deklarierter default_value muss selbst in der erlaubten Menge sein.

Einen Wert zur Verbindungszeit liefern

Werte kommen über session.<name>-Properties auf der Verbindung an – derselbe Kanal, den Saiku verwendet, um Benutzerattribute zu übergeben, und derselbe, den dynamische Rollen lesen.

Provider=mondrian;Jdbc=...;Catalog=...;session.region=WEST

Wenn die Verbindung hergestellt wird, baut die Engine einen validierten Parameter-Kontext: Jeder deklarierte Parameter nimmt seinen session.<name>-Wert, falls vorhanden, sonst seinen Standardwert; der Wert wird gecastet und gegen die erlaubte Menge geprüft. Ein unzulässiger Wert lässt die Verbindung fehlschlagen, statt falsche Ergebnisse zu produzieren.

Tipp

In Saiku ordnen Sie den Parameternamen einem Benutzerattribut zu, sodass die Verbindung jedes Benutzers automatisch seinen eigenen Wert trägt – z. B. fließt ein region-Benutzerattribut als session.region ein.

Einen Parameter für Zeilensicherheit verwenden

Die primäre Verwendung ist predicate-basierte Zeilensicherheit: Beschränken Sie die Fact-Zeilen einer Measure-Group auf diejenigen, deren echte Fact-Spalte mit dem Parameterwert des anfragenden Benutzers übereinstimmt. Deklarieren Sie einen <PredicateGrant> auf einer Rolle; der Calcite-Adapter injiziert ihn als WHERE-Filter auf jeder Segment-Last für diese Measure-Group, vor-Aggregation, sodass Summen korrekt eingeschränkt sind.

XML

<Role name="Regional">
  <SchemaGrant access="all">
    <CubeGrant cube="Sales" access="all">
      <!-- restrict Sales fact rows to the user's region -->
      <PredicateGrant measureGroup="Sales" column="region"
                      operator="eq" parameter="region"/>
    </CubeGrant>
  </SchemaGrant>
</Role>

YAML

roles:
  - name: Regional
    schema_grant:
      access: all
      cube_grants:
        - cube: Sales
          access: all
          predicate_grants:
            - measure_group: Sales
              column: region
              operator: eq        # or: in
              parameter: region

Jetzt sehen zwei Benutzer, die mit session.region=EAST und session.region=WEST verbunden sind, korrekt unterschiedliche, nicht überlappende Summen über dieselbe Abfrage – und das Prädikat erscheint im generierten SQL bei jeder Last der gesicherten Measure-Group.

Achtung

Predicate-Grants wenden Gleichheit (eq) oder Mitgliedschaft (in) nur auf einer echten Fact-Spalte an, mit dem Wert gebunden an einen Query-Parameter – kein beliebiges SQL. Ein ungebundener Parameter schlägt geschlossen fehl (null Zeilen), niemals uneingeschränkt. Predicate-Grants erfordern das Calcite-Backend.

Feldwechsel (Field-Switching)

Ein Parameter kann auch auswählen, welche aus einer festen Menge vor-deklarierter Measures oder Spalten aktiv ist – Lookers parameter-Field-Switching-Muster. Auf der Engine-Seite deklarieren Sie die Menge; die Auswahl wird auf der Abfrageebene als standardmäßiges MDX-WITH MEMBER / WITH SET injiziert, das den Parameter-Kontext liest, sodass sie innerhalb des begrenzten, kein-Templating-Vertrags bleibt.

Migration von Looker

Ein LookML-parameter-Feld mappt direkt auf einen <QueryParameter> (Typ + allowed_values + Standard). Die Verwendung eines Parameters innerhalb von {% parameter %}-Liquid-SQL ist der dynamische Templating-Fall, den der Importer immer noch ablehnt – siehe Migration von Looker.

Hinweis

Query-Parameter und Predicate-Grants werden vom Calcite-Backend bedient. Siehe Zugriffskontrolle und Rollen für den Rest des Rollen-/Grant-Modells.