Constrain

A instrução Constrain pode ser usada em combinação com as instruções Let ou Set para definir variáveis de script. A instrução Constrain permite que você defina restrições sobre os valores possíveis para essas variáveis. Se a definição de uma variável violar as restrições, o recarregamento falhará. Com as restrições, você pode exigir que os valores variáveis correspondam a tipos específicos, estejam dentro de intervalos numéricos específicos e correspondam a valores aceitáveis definidos por você.

Sintaxe:

Constrain variablename = json

Em que:

variablename é uma variável de script.
json é um objeto JSON válido que especifica as restrições. As restrições individuais são adicionadas a esse objeto como pares de valores-chave.

Tipos de restrição
Tipo de restrição (chave)	Significado	Requisitos de restrição (valor)	Exemplos
"type"	Restringir valores de variável a um tipo de dados específico.	"text" especifica um tipo de texto. "number" especifica um tipo numérico.	`CONSTRAIN vExampleText = {"type": "text"}` `CONSTRAIN vExampleNumeric = {"type": "number"}`
"maxnum"	Defina um valor máximo para uma variável.	Somente números (inteiros ou de ponto flutuante). É permitida notação científica.	`CONSTRAIN vExample = {"maxnum": 5000}`
"minnum"	Defina um valor mínimo para uma variável.	Somente números (inteiros ou de ponto flutuante). É permitida notação científica.	`CONSTRAIN vExample = {"minnum": 250}`
"valuesnum"	Defina uma lista de valores numéricos aceitáveis para a variável.	Lista de números separados por vírgula, entre colchetes. Por exemplo: [1,2,3]	`CONSTRAIN vExample = {"valuesnum": [1,2,3]}`
"valuestext"	Defina uma lista de valores de texto aceitáveis para a variável.	Lista de strings separadas por vírgulas, entre colchetes. Por exemplo: ["a","b","c"]	`CONSTRAIN vExample = {"valuestext": ["Department A", "Department B", "Department C"]}`

Quando usar uma instrução Constrain

Use a instrução Constrain para evitar que valores variáveis indesejados sejam carregados nos aplicativos de análise. As seções a seguir descrevem maneiras específicas de usá-la.

Atualização de variável de tempo de recarregamento

Constrain é especialmente útil quando usado em combinação com atualizações de variáveis em tempo de recarregamento. Com as atualizações de variáveis em tempo de recarregamento, você pode atualizar dinamicamente as variáveis durante os recarregamentos do aplicativo, usando a propriedade variables na API Recarregamentos. A instrução Constrain impede que definições de variáveis mal-intencionadas ou formatadas incorretamente sejam incorporadas aos recarregamentos de análises.

As atualizações de variáveis de tempo de recarregamento, juntamente com a instrução Constrain, suportam os seguintes casos de uso:

Aplicativos com modelos que carregam dados seletivamente com base em condições como ID ou nome do cliente (que podem ser passados no momento do carregamento como variáveis)
Controle central sobre aplicativos distribuídos em muitos locatários do Qlik Cloud
Migrando fluxos de trabalho e tarefas orientados por variáveis do QlikView e do Qlik Sense Client-Managed para a nuvem

Segurança, confiabilidade e colaboração

Mesmo quando usado fora dos cenários de atualização de variáveis em tempo de recarregamento, o Constrain aprimora os controles de segurança para a criação de scripts de carregamento, por exemplo, durante o desenvolvimento colaborativo de scripts de carregamento. Por exemplo, o proprietário de um aplicativo pode definir restrições para valores de variáveis, informando os colaboradores sobre condições específicas que precisam ser atendidas para que o aplicativo seja recarregado com sucesso e confiabilidade.

Considerações

A definição de Constrain para a variável deve ser um objeto JSON válido.
Você pode especificar mais de uma restrição para uma única variável. Todas as restrições de uma variável precisam estar contidas em um único objeto de restrição. Para ver exemplos, consulte Exemplos - Várias restrições.
Se você já carregou uma variável de script com um determinado nome no aplicativo, tentativas futuras de definir restrições e valores para essa variável podem falhar devido a conflitos entre a variável original e a redefinida.

Para resolver esses conflitos, redefina as restrições e os valores da variável inserindo definições em branco. Exemplos:
```
CONSTRAIN x;
LET x;
```
```
CONSTRAIN x;
SET x;
```
Você pode então redefinir a variável e suas restrições nas seções subsequentes do script de carregamento. Para um exemplo mais longo, consulte Exemplo - Resolvendo conflitos de definição de variável.
A ordem da definição de variável e da restrição não importa. No entanto, em caso de falha de recarregamento relacionada à variável, a linha na qual o ponto de interrupção ocorre será diferente.
A instrução de script Constrain restringe apenas as definições de variáveis para variáveis de script. Você também pode aplicar restrições em variáveis de script e de usuário final (aquelas criadas ou atualizadas na visualização de pasta ou como variáveis de sessão usando a API) usando a API pública. Para obter mais informações, consulte Alternativas do desenvolvedor para definir restrições de variáveis.

Alternativas do desenvolvedor para definir restrições de variáveis

Você também pode usar a API pública para definir restrições de variáveis, em vez de usar a instrução Constrain no script de carregamento. Ao definir restrições via API, todas as tentativas de atualizar valores de variáveis — seja diretamente no script de carregamento, na exibição de pasta ou por meio da API Recarregamentos — estarão sujeitas às restrições.

Para definir restrições de variáveis por meio da API pública, use o objeto GenericVariableConstraints na API Qlik Sense Engine (qix): GenericVariableConstraints.

Exemplo – type

Visão geral

Abra o editor da carga de dados e adicione o script de carregamento abaixo em uma nova seção.

O script de carregamento contém:

Uma instrução Constrain para especificar que a definição de variável para a precisa ter o tipo number.
Uma instrução LET que define a variável a.

Script de carregamento

CONSTRAIN a = {"type": "text"};
LET a = 1000;

Resultados

Carregue os dados.

O recarregamento falha porque a restrição exige um tipo de texto para a variável a. A definição de variável é um número.

Por outro lado, especificar um type de number na restrição faria com que o recarregamento fosse bem-sucedido.

Exemplo – maxnum

Visão geral

Abra o editor da carga de dados e adicione o script de carregamento abaixo em uma nova seção.

O script de carregamento contém:

Uma instrução Constrain para especificar que a definição de variável para b pode ter um valor máximo de 3000.
Uma instrução LET que define a variável b.

CONSTRAIN b = {"maxnum": "3000"};
LET b = 3001;

Resultados

Carregue os dados.

O recarregamento falha porque a restrição exige um valor máximo de 3000 para a variável b. A definição de variável é avaliada como 3001.

Por outro lado, especificar b como 2999 faria com que o recarregamento fosse bem-sucedido.

Exemplo – minnum

Visão geral

Abra o editor da carga de dados e adicione o script de carregamento abaixo em uma nova seção.

O script de carregamento contém:

Uma instrução Constrain para especificar que a definição de variável para b pode ter um valor mínimo de 3000.
Uma instrução LET que define a variável c.

CONSTRAIN c = {"minnum": "3000"};
LET c = 2999;

Resultados

Carregue os dados.

O recarregamento falha porque a restrição exige um valor mínimo de 3000 para a variável c. A definição de variável é avaliada como 2999.

Por outro lado, especificar c como 3000 faria com que o recarregamento fosse bem-sucedido.

Exemplo – valuesnum

Visão geral

Abra o editor da carga de dados e adicione o script de carregamento abaixo em uma nova seção.

O script de carregamento contém:

Uma instrução Constrain para especificar que a definição de variável para d deve ser numérica e deve ser 2, 3 ou 4.
Uma instrução LET que define a variável d.

CONSTRAIN d = {"valuesnum": [2,3,4]};
LET d = 1;

Resultados

Carregue os dados.

O recarregamento falha porque a variável d é avaliada como 1, o que não está na lista de três valores possíveis.

Por outro lado, especificar d como 2 faria com que o recarregamento fosse bem-sucedido.

Exemplo – valuestext

Visão geral

Abra o editor da carga de dados e adicione o script de carregamento abaixo em uma nova seção.

O script de carregamento contém:

Uma instrução Constrain para especificar que a definição de variável para e deve ser um dos seguintes valores de texto:
- Department A
- Department B
- Department C
Uma instrução SET que define a variável e.

CONSTRAIN e = {"valuestext": ["Department A", "Department B", "Department C"]};
SET e = Department D;

Resultados

Carregue os dados.

O recarregamento falha porque a variável e é Department D, que não está na lista de valores permitidos definidos pela restrição.

Por outro lado, especificar e como Department C faria com que o recarregamento fosse bem-sucedido.

Exemplos - SET versus LET

Esses exemplos mostram as diferenças entre como as restrições são aplicadas ao usar SET ou LET durante a definição de variável. Todos os exemplos usam restrições que aplicam um requisito type, mas esses princípios se aplicam a todos os tipos de restrições em geral.

Visão geral

Abra o editor da carga de dados e adicione o script de carregamento abaixo em uma nova seção.

O script de carregamento contém:

Uma instrução Constrain para especificar que a definição de variável para f precisa ter o tipo number.
Uma instrução SET que define a variável f.

Script de carregamento

CONSTRAIN f = {"type": "number"};
SET f = 500*2;

Resultados

Carregue os dados.

O recarregamento falha porque a restrição requer um tipo numérico para a variável f. A definição de variável contém uma expressão numérica, mas como é usada uma instrução SET, a definição é avaliada como texto.

Visão geral

Abra o editor da carga de dados e adicione o script de carregamento abaixo em uma nova seção.

O script de carregamento contém:

Uma instrução Constrain para especificar que a definição de variável para g precisa ter o tipo text.
Uma instrução LET que define a variável g.

Script de carregamento

CONSTRAIN g = {"type": "text"};
LET g = 500*2;

Carregue os dados.

O recarregamento falha porque a restrição exige um tipo de texto para a variável g. A definição de variável contém uma expressão numérica e uma instrução LET é usada, fazendo com que a definição seja avaliada como um número.

Visão geral

Abra o editor da carga de dados e adicione o script de carregamento abaixo em uma nova seção.

O script de carregamento contém:

Uma instrução Constrain para especificar que a definição de variável para h precisa ter o tipo text.
Uma instrução SET que define a variável h.

Script de carregamento

CONSTRAIN h = {"type": "text"};
SET h = 500*2;

Carregue os dados.

O recarregamento foi bem-sucedido. A restrição requer um tipo de texto para a variável h. A definição de variável contém uma expressão numérica, mas como é usada uma instrução SET, a definição é avaliada como texto.

Visão geral

Abra o editor da carga de dados e adicione o script de carregamento abaixo em uma nova seção.

O script de carregamento contém:

Uma instrução Constrain para especificar que a definição de variável para i precisa ter o tipo number.
Uma instrução LET que define a variável i.

Script de carregamento

CONSTRAIN i = {"type": "number"};
LET i = 500*2;

Carregue os dados.

O recarregamento foi bem-sucedido. A restrição requer um tipo numérico para a variável i. A definição de variável contém uma expressão numérica e uma instrução LET é usada, fazendo com que a definição seja avaliada como um número.

Exemplos - Várias restrições

Visão geral

Abra o editor da carga de dados e adicione o script de carregamento abaixo em uma nova seção.

O script de carregamento contém:

Uma instrução Constrain para especificar que a definição de variável para j precisa estar entre 1 e 5.
Uma instrução LET que define a variável j.

Script de carregamento

CONSTRAIN j = {"minnum": 1, "maxnum": 5};
LET j = 2;

Carregue os dados.

O recarregamento foi bem-sucedido. A variável f é avaliada como 2, o que está dentro do intervalo aceitável.

Visão geral

Abra o editor da carga de dados e adicione o script de carregamento abaixo em uma nova seção.

O script de carregamento contém:

Uma instrução Constrain que permite que a variável seja texto ou numérica, desde que seja um dos valores aceitáveis.
Uma instrução LET que define a variável k.

Script de carregamento

CONSTRAIN k = {"valuestext": ["abc","def","ghi"], "valuesnum": [0,1,3,5]};
LET k = 'def';

Carregue os dados.

O recarregamento foi bem-sucedido. O valor da variável k é encontrado na lista de valores aceitáveis. Da mesma forma, especificar k como 3 resultaria em um recarregamento bem-sucedido.

Exemplo - Resolvendo conflitos de definição de variável

Visão geral

Este exemplo mostra como podem ocorrer conflitos na definição de variável ao adicionar restrições para uma variável que já foi definida no aplicativo em um carregamento anterior.

Script de carregamento 1: definindo uma variável de script

Abra o Editor da carga de dados. Adicione o seguinte script:

LET vConflictExample = 'Department C';

Carregue os dados. O recarregamento foi bem-sucedido. A variável vConflictExample foi criada no aplicativo como uma variável de script.

Script de carregamento 2: tentando a definição de restrição em variável de script carregada anteriormente

Excluir o script de carregamento 1. Adicione o script a seguir:

CONSTRAIN vConflictExample = {"type": "number"};
LET vConflictExample = 123;

Carregue os dados.

O recarregamento falha com um erro de restrição, mesmo que a nova restrição e a definição de valor sejam compatíveis. Isso ocorre porque o script de carregamento 1 já carregou a variável no aplicativo, com um valor de texto, e esse valor ainda é mantido no aplicativo. Para resolver esse problema, precisamos redefinir a restrição e a definição de variável. Consulte o script de carregamento 3.

Script de carregamento 3: redefinindo as definições de restrições e valores

Exclua o script de carregamento 2. Adicione o seguinte script:

CONSTRAIN vConflictExample;
LET vConflictExample;

CONSTRAIN vConflictExample = {"type": "number"};
LET vConflictExample = 123;

MockData:
LOAD 
* 
Inline [
id, date, amount
1, 05/30/2025, 23.56
];

Carregue os dados.

O recarregamento foi bem-sucedido. O script acima pode ser dividido em três partes, cada uma separada por linhas em branco:

A primeira parte redefine a definição de restrição e valor para vConflictExample. Isso remove a definição que foi carregada no aplicativo com o script de carregamento 1.
A segunda parte reaplica as novas definições de restrição e valor que falharam no script de carregamento 2.
A terceira parte adiciona dados simulados simplesmente para que possamos abrir a exibição de pasta e inspecionar o valor da variável (veja abaixo).

Abra a exibição de pasta no modo de edição e abra o diálogo Variáveis. Podemos ver que a variável vConflictExample foi criada com sucesso.

O diálogo Variáveis na exibição de pasta mostra que a variável de script foi criada com sucesso. — O diálogo Variáveis na exibição de pasta mostra que o conflito de definição de variável para vConflictExample foi resolvido.

Saiba mais

Esta página ajudou?

Se você encontrar algum problema com esta página ou seu conteúdo – um erro de digitação, uma etapa ausente ou um erro técnico – avise-nos!

Deixe seu feedback aqui