Parámetros de contexto de consulta

Un parámetro de contexto de consulta es un valor nombrado y tipado que el motor resuelve por petición a partir de los atributos de sesión de la conexión. A diferencia de un miembro calculado (fijado en tiempo de creación) o del Liquid estilo Looker (SQL en tiempo de ejecución arbitrario), un parámetro de consulta está acotado y en sandbox: es tipado, opcionalmente restringido a un conjunto fijo de valores permitidos, y solo puede usarse como un valor enlazado — nunca interpolado en SQL.

Declara un <QueryParameter> una vez en el schema, suministra su valor en tiempo de conexión mediante una propiedad session.<name>, y lo referencia donde el motor acepta un valor enlazado — hoy, en la seguridad de fila basada en predicado.

El modelo de seguridad

La garantía de no inyección viene del tipado más la enumeración, no del escapado:

Cada valor suministrado se coerce al tipo declarado (String, Numeric, Date, Member) y, cuando se declara un conjunto de valores permitidos, se comprueba contra él — antes de que pueda formar parte de una consulta.
Un valor con tipo incorrecto o fuera del conjunto permitido se rechaza en tiempo de conexión (la conexión falla ruidosamente), nunca se pasa silenciosamente.
El valor validado llega a SQL solo como un literal enlazado en un único punto de sustitución auditado. No hay plantillas de formato libre.

Declarar un parámetro

Un <QueryParameter> es un elemento de schema de nivel superior (junto con <Role>). Asígnele un name, un type, un defaultValue opcional, y una lista opcional de valores permitidos <QueryParameterValue> (la enumeración cerrada).

XML
YAML

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

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

`type`	Coercionado a	Notas
`String`	cadena
`Numeric`	número
`Date`	fecha ISO (`yyyy-MM-dd`)
`Member`	clave de hoja de un miembro	Solo niveles de clave única

Si se omite allowed_values el parámetro es no restringido (todavía con comprobación de tipo). Un default_value declarado debe estar él mismo en el conjunto permitido.

Suministrar un valor en tiempo de conexión

Los valores llegan a la conexión mediante propiedades session.<name> — el mismo canal que Saiku usa para pasar atributos de usuario, y el mismo que leen los roles dinámicos.

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

Cuando la conexión se establece, el motor construye un contexto de parámetro validado: cada parámetro declarado toma su valor session.<name> si está presente, en caso contrario su default; el valor se coerce y se comprueba contra el conjunto permitido. Un valor ilegal falla la conexión en lugar de producir resultados incorrectos.

Usar un parámetro para seguridad de fila

El uso principal es la seguridad de fila basada en predicado: restringir las filas de hechos de un grupo de medidas a aquellas cuya columna de hecho real coincide con el valor del parámetro del usuario solicitante. Declare un <PredicateGrant> en un rol; el adaptador de Calcite lo inyecta como un filtro WHERE en cada carga de segmento para ese grupo de medidas, pre-agregación, así que los totales están correctamente restringidos.

XML
YAML

<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>

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

Ahora dos usuarios que se conectan con session.region=EAST y session.region=WEST ven totales correctamente diferentes y no solapados sobre la misma consulta — y el predicado aparece en el SQL generado en cada carga del grupo de medidas asegurado.

Cambio de campo

Un parámetro también puede seleccionar cuál de un conjunto fijo de medidas o columnas predeclaradas está activo — el patrón parameter de cambio de campo de Looker. En el lado del motor declara el conjunto; la selección se inyecta en la capa de consulta como un WITH MEMBER / WITH SET estándar de MDX que lee el contexto del parámetro, así que permanece dentro del contrato acotado y sin plantillas.

Migrar desde Looker

Un campo parameter de LookML mapea directamente a un <QueryParameter> (tipo + allowed_values + default). El uso de un parámetro dentro de SQL Liquid {% parameter %} es el caso de plantilla dinámica que el importador todavía rechaza — consulte Migrar desde Looker.