Parâmetros de contexto de consulta

Um parâmetro de contexto de consulta é um valor nomeado e tipado que o engine resolve por requisição a partir dos atributos de sessão da conexão. Diferente de um calculated member (fixo no momento da autoria) ou Liquid estilo Looker (SQL runtime arbitrário), um query parameter é limitado e em sandbox: é tipado, opcionalmente restrito a um conjunto fixo de valores permitidos, e pode ser usado apenas como um valor de bind — nunca interpolado em SQL.

Você declara um <QueryParameter> uma vez no schema, fornece seu valor no momento da conexão via uma propriedade session.<name>, e o referencia onde o engine aceita um valor vinculado — hoje, em row security baseada em predicado.

O modelo de segurança

A garantia de não-injeção vem de tipagem mais enumeração, não de escape:

Cada valor fornecido é coagido ao tipo declarado (String, Numeric, Date, Member) e, quando um conjunto de valores permitidos é declarado, verificado contra ele — antes que possa virar parte de uma consulta.
Um valor que é do tipo errado ou fora do conjunto permitido é rejeitado no momento da conexão (a conexão falha em voz alta), nunca silenciosamente passado.
O valor validado alcança SQL apenas como um literal vinculado em um único ponto de substituição auditado. Não há template livre.

Declarar um parâmetro

Um <QueryParameter> é um elemento de schema de nível superior (ao lado de <Role>). Dê a ele um name, um type, um defaultValue opcional e uma lista opcional de valores permitidos <QueryParameterValue> (a enumeração fechada).

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`	Coagido a	Notas
`String`	string
`Numeric`	número
`Date`	data ISO (`yyyy-MM-dd`)
`Member`	chave folha de um membro	Apenas levels de chave única

Se allowed_values é omitido o parâmetro é irrestrito (ainda type-checked). Um default_value declarado deve estar no conjunto permitido.

Fornecer um valor no momento da conexão

Valores chegam na conexão através de propriedades session.<name> — o mesmo canal que o Saiku usa para passar atributos de usuário, e o mesmo que roles dinâmicas leem.

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

Quando a conexão é estabelecida, o engine constrói um contexto de parâmetro validado: cada parâmetro declarado pega seu valor session.<name> se presente, senão seu default; o valor é coagido e verificado contra o conjunto permitido. Um valor ilegal faz a conexão falhar em vez de produzir resultados errados.

Usar um parâmetro para row security

O uso primário é row security baseada em predicado: restringir as linhas de fato de um measure group àquelas cuja coluna de fato real casa com o valor de parâmetro do usuário solicitante. Declare um <PredicateGrant> em uma role; o adaptador Calcite o injeta como um filtro WHERE em cada carga de segmento para aquele measure group, pré-agregação, para que totais sejam corretamente restritos.

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

Agora dois usuários conectando com session.region=EAST e session.region=WEST veem totais corretamente diferentes e não sobrepostos sobre a mesma consulta — e o predicado aparece no SQL gerado em cada carga do measure group seguro.

Troca de fields

Um parâmetro também pode selecionar qual de um conjunto fixo de medidas ou colunas pré-declaradas está ativa — o padrão field-switching do parameter do Looker. Do lado do engine, você declara o conjunto; a seleção é injetada na camada de consulta como um WITH MEMBER / WITH SET MDX padrão que lê o contexto do parâmetro, então permanece dentro do contrato limitado e sem template.

Migrar do Looker

Um field parameter do LookML mapeia diretamente para um <QueryParameter> (type + allowed_values + default). O uso de um parâmetro dentro de Liquid SQL {% parameter %} é o caso de template dinâmico que o importador ainda recusa — veja Migrar do Looker.