Paramètres de contexte de requête

Un paramètre de contexte de requête est une valeur nommée et typée que le moteur résout par requête depuis les attributs de session de la connexion. Contrairement à un membre calculé (fixé au moment de la création) ou au Liquid style Looker (SQL arbitraire à l’exécution), un paramètre de requête est borné et en sandbox : il est typé, optionnellement restreint à un ensemble fixe de valeurs autorisées, et ne peut être utilisé que comme valeur liée — jamais interpolé dans le SQL.

Vous déclarez un <QueryParameter> une fois dans le schema, fournissez sa valeur au moment de la connexion via une propriété session.<name>, et le référencez là où le moteur accepte une valeur liée — aujourd’hui, dans la sécurité de lignes par prédicat.

Note

C’est un élément différent du legacy <Parameter> (un MDX ParamRef dont la valeur par défaut est une expression MDX). Un <QueryParameter> est une liaison runtime — une valeur typée alimentée depuis le contexte de la requête — pas un paramètre MDX.

Le modèle de sécurité

La garantie de non-injection vient du typage plus énumération, pas de l’échappement :

• Chaque valeur fournie est coercée vers le type déclaré (String, Numeric, Date, Member) et, lorsqu’un ensemble de valeurs autorisées est déclaré, vérifiée contre lui — avant qu’elle ne puisse jamais faire partie d’une requête.
• Une valeur qui est du mauvais type ou hors de l’ensemble autorisé est rejetée au moment de la connexion (la connexion échoue bruyamment), jamais silencieusement laissée passer.
• La valeur validée atteint le SQL uniquement comme littéral lié à un point de substitution unique et audité. Il n’y a pas de templating en forme libre.

Déclarer un paramètre

Un <QueryParameter> est un élément de schema de niveau supérieur (à côté de <Role>). Donnez-lui un name, un type, un defaultValue facultatif, et une liste facultative de valeurs autorisées <QueryParameterValue> (l’énumération fermée).

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	Coercé vers	Notes
String	string
Numeric	number
Date	date ISO (yyyy-MM-dd)
Member	la clé feuille d’un membre	Niveaux à clé unique seulement

Si allowed_values est omis, le paramètre n’est pas contraint (toujours type-checké). Un default_value déclaré doit lui-même être dans l’ensemble autorisé.

Fournir une valeur au moment de la connexion

Les valeurs arrivent sur la connexion via les propriétés session.<name> — le même canal que Saiku utilise pour passer les attributs utilisateur, et le même que lisent les rôles dynamiques.

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

Lorsque la connexion est établie, le moteur construit un contexte de paramètres validé : chaque paramètre déclaré prend sa valeur session.<name> si présente, sinon sa valeur par défaut ; la valeur est coercée et vérifiée contre l’ensemble autorisé. Une valeur illégale fait échouer la connexion plutôt que de produire des résultats erronés.

Astuce

Dans Saiku, mappez le nom du paramètre à un attribut utilisateur afin que la connexion de chaque utilisateur porte sa propre valeur automatiquement — par ex. un attribut utilisateur region arrive comme session.region.

Utiliser un paramètre pour la sécurité de lignes

L’usage principal est la sécurité de lignes par prédicat : restreindre les lignes de fait d’un groupe de mesures à celles dont la vraie colonne de fait correspond à la valeur du paramètre de l’utilisateur appelant. Déclarez un <PredicateGrant> sur un rôle ; l’adaptateur Calcite l’injecte comme filtre WHERE sur chaque chargement de segment pour ce groupe de mesures, pré-agrégation, afin que les totaux soient correctement restreints.

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

Maintenant deux utilisateurs se connectant avec session.region=EAST et session.region=WEST voient des totaux correctement différents et non chevauchants sur la même requête — et le prédicat apparaît dans le SQL généré à chaque chargement du groupe de mesures sécurisé.

Attention

Les autorisations par prédicat appliquent l’égalité (eq) ou l’appartenance (in) sur une vraie colonne de fait uniquement, avec la valeur liée à un paramètre de requête — pas de SQL arbitraire. Un paramètre non lié échoue fermé (zéro lignes), jamais non restreint. Les autorisations par prédicat nécessitent le backend Calcite.

Changement de champ

Un paramètre peut également sélectionner laquelle d’un ensemble fixe de mesures ou colonnes pré-déclarées est active — le pattern Looker parameter de field-switching. Côté moteur, vous déclarez l’ensemble ; la sélection est injectée à la couche requête comme un MDX standard WITH MEMBER / WITH SET qui lit le contexte de paramètres, donc il reste dans le contrat borné et sans templating.

Migration depuis Looker

Un champ LookML parameter mappe directement à un <QueryParameter> (type + allowed_values + défaut). L’usage d’un paramètre à l’intérieur du SQL Liquid {% parameter %} est le cas de templating dynamique que l’importeur refuse encore — voir Migration depuis Looker.

Note

Les paramètres de requête et les autorisations par prédicat sont servis par le backend Calcite. Voir Contrôle d’accès et rôles pour le reste du modèle rôle/autorisation.