# Constrain

Constrain 语句可与 Let 或 Set 语句结合使用，用于定义脚本变量。通过 Constrain 语句，可以为这些变量的可能值定义约束条件。如果变量定义违反了限制条件，重载就会失败。通过约束，可以要求变量值与特定类型相匹配，在特定数值范围内，并与自己定义的可接受值相匹配。

Constrain variablename = json

其中：

* variablename 是一个脚本变量。

* json 是一个有效的 JSON 对象，指定约束条件。单个约束条件以键值对形式添加到该对象中。

约束类型

| 约束类型（键） | 含义 | 约束要求（值） | 实例 |
| --- | --- | --- | --- |
| `"type"` | 将变量值限制为特定数据类型。 | `"text"` 指定文本类型。<br><br>`"number"` 指定数字类型。 | ```<br>CONSTRAIN vExampleText = {"type": "text"}<br>```<br><br>```<br>CONSTRAIN vExampleNumeric = {"type": "number"}<br>``` |
| `"maxnum"` | 为变量设置最大值。 | 仅限数字（整数或浮点数）。允许使用科学符号。 | ```<br>CONSTRAIN vExample = {"maxnum": 5000}<br>``` |
| `"minnum"` | 为变量设置最小值。 | 仅限数字（整数或浮点数）。允许使用科学符号。 | ```<br>CONSTRAIN vExample = {"minnum": 250}<br>``` |
| `"valuesnum"` | 定义变量的可接受数值的列表。 | 以逗号分隔的方括号内数字的列表。例如：`[1,2,3]` | ```<br>CONSTRAIN vExample = {"valuesnum": [1,2,3]}<br>``` |
| `"valuestext"` | 定义变量的可接受文本值的列表。 | 以逗号分隔的方括号内字符串的列表。例如：`["a","b","c"]` | ```<br>CONSTRAIN vExample = {"valuestext": ["Department A", "Department B", "Department C"]}<br>``` |

## 何时使用 Constrain 语句

使用 Constrain 语句可防止不需要的变量值加载到分析应用程序中。

## 注意事项

* Constrain 变量的定义必须为有效的 JSON 对象。

* 您可以为一个变量指定多个约束条件。变量的所有约束条件都必须包含在单个约束对象内。有关示例，请参阅[示例 - 多重约束](https://help.qlik.com/zh-CN/sense/May2026/Subsystems/Hub/Content/Sense_Hub/Scripting/ScriptRegularStatements/Constrain.htm#Examples)。

* 如果您已将某个名称的脚本变量加载到应用程序中，那么今后为该变量定义约束条件和值的尝试可能会因原始变量和重新定义的变量之间的冲突而失败。

  要解决这些冲突，可通过插入空白定义来重置变量约束和值。示例：

  ```
  CONSTRAIN x;
  LET x;
  ```

  ```
  CONSTRAIN x;
  SET x;
  ```

  然后，您可以在加载脚本的后续部分里重新定义变量及其约束条件。有关长篇范例，请参阅[示例 - 解决变量定义冲突](https://help.qlik.com/zh-CN/sense/May2026/Subsystems/Hub/Content/Sense_Hub/Scripting/ScriptRegularStatements/Constrain.htm#ConflictResolve) 。

* 变量定义和约束定义的顺序并不重要。但是，如果发生与变量相关的重载失败事件，发生断点的行将有所不同。

* Constrain 脚本语句只限制脚本变量的变量定义。您还可以通过使用公共 API 对脚本和最终用户变量（在工作表视图中创建或更新的变量，或使用 API 作为会话变量而创建或更新的变量）应用约束。有关更多信息，请参阅[开发人员用于定义变量约束的替代方案](https://help.qlik.com/zh-CN/sense/May2026/Subsystems/Hub/Content/Sense_Hub/Scripting/ScriptRegularStatements/Constrain.htm#Developer)。

* 对约束进行验证，以避免出现无法匹配变量任何值的场景。无效约束的示例：

  * {"minnum": 5000, "maxnum": 4}
  * {"type": "text", "maxnum": 4}

## 开发人员用于定义变量约束的替代方案

您还可以使用公共 API 来定义变量约束，而不是在加载脚本中使用 Constrain 语句。通过 API 定义约束时，所有更新变量值的尝试—无论是直接在加载脚本中还是在工作表视图中—都将受到约束。

要通过公共 API 定义变量约束，请使用 QlikEngine JSON API 中的 GenericVariableConstraints 属性：[GenericVariableProperties](https://help.qlik.com/en-US/sense-developer/May2026/Subsystems/EngineJSONAPI/Content/models-genericvariableproperties.htm) （仅提供英文版本）。

## 示例 - type

[](https://help.qlik.com/en-US/sense/Subsystems/Hub/Content/Sense_Hub/Scripting/ScriptRegularStatements/Constrain.htm)

#### 以 "类型" 重载失败

概述

打开数据加载编辑器，并将下面的加载脚本添加到新部分。

加载脚本包含：

* Constrain 语句，指定 a 的变量定义需要有 number 类型。

* 定义变量 LET 的 a 语句。

加载脚本

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

结果

加载数据。

重载失败的原因是，约束要求变量 a 采用文本类型。变量定义是一个数字。

相比之下，如果在约束中指定 type 为 number ，重载就会成功。

## 示例 - maxnum

[](https://help.qlik.com/en-US/sense/Subsystems/Hub/Content/Sense_Hub/Scripting/ScriptRegularStatements/Constrain.htm)

#### 以 "maxnum" 重载失败

概述

打开数据加载编辑器，并将下面的加载脚本添加到新部分。

加载脚本包含：

* Constrain 语句，指定 b 的变量定义最大值可以是 3000。

* 定义变量 LET 的 b 语句。

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

结果

加载数据。

重载失败，因为约束要求变量 b 的最大值为 3000。变量定义的值计算为 3001。

相比之下，指定为 b 2999 将导致重载成功。

## 示例 - minnum

[](https://help.qlik.com/en-US/sense/Subsystems/Hub/Content/Sense_Hub/Scripting/ScriptRegularStatements/Constrain.htm)

#### 以 "minnum" 重载失败

概述

打开数据加载编辑器，并将下面的加载脚本添加到新部分。

加载脚本包含：

* Constrain 语句，指定 b 的变量定义最小值可以是 3000。

* 定义变量 LET 的 c 语句。

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

结果

加载数据。

重载失败，因为约束要求变量 c 的最小值为 3000。变量定义的值计算为 2999。

相比之下，指定为 c 3000 将导致重载成功。

## 示例 - valuesnum

[](https://help.qlik.com/en-US/sense/Subsystems/Hub/Content/Sense_Hub/Scripting/ScriptRegularStatements/Constrain.htm)

#### 以 "valuesnum" 重载失败

概述

打开数据加载编辑器，并将下面的加载脚本添加到新部分。

加载脚本包含：

* Constrain 语句，指定 d 的变量定义必须是数字，且必须是 2、3 或 4。

* 定义变量 LET 的 d 语句。

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

结果

加载数据。

重载失败的原因是，变量 d 的值为 1，而这不在三个可能值的列表中。

相比之下，指定为 d 2 将导致重载成功。

## 示例 - valuestext

[](https://help.qlik.com/en-US/sense/Subsystems/Hub/Content/Sense_Hub/Scripting/ScriptRegularStatements/Constrain.htm)

#### 以 “值文本” 重载失败

概述

打开数据加载编辑器，并将下面的加载脚本添加到新部分。

加载脚本包含：

* Constrain 语句，指定 e 的变量定义必须是以下文本值之一：

  * Department A

  * Department B

  * Department C

* 定义变量 SET 的 e 语句。

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

结果

加载数据。

重载失败的原因是变量 e 是 Department D ，不在约束定义的允许值列表中。

相比之下，指定 e 为 Department C 将导致重载成功。

## 示例 - SET 与 LET

这些示例显示了在变量定义过程中使用 SET 或 LET 时应用约束条件的不同之处。所有示例都使用了应用 type 要求的约束，但这些原则一般适用于所有约束类型。

[](https://help.qlik.com/en-US/sense/Subsystems/Hub/Content/Sense_Hub/Scripting/ScriptRegularStatements/Constrain.htm)

#### 以 SET 重载失败

概述

打开数据加载编辑器，并将下面的加载脚本添加到新部分。

加载脚本包含：

* Constrain 语句，指定 f 的变量定义需要有 number 类型。

* 定义变量 SET 的 f 语句。

加载脚本

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

结果

加载数据。

重载失败的原因是，约束要求变量 f 采用数字类型。变量定义包含一个数字表达式，但因为使用了 SET 语句，所以定义以文本形式求值。

[](https://help.qlik.com/en-US/sense/Subsystems/Hub/Content/Sense_Hub/Scripting/ScriptRegularStatements/Constrain.htm)

#### 以 LET 重载失败

概述

打开数据加载编辑器，并将下面的加载脚本添加到新部分。

加载脚本包含：

* Constrain 语句，指定 g 的变量定义需要有 text 类型。

* 定义变量 LET 的 g 语句。

加载脚本

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

加载数据。

重载失败的原因是，约束要求变量 g 采用文本类型。变量定义包含一个数值表达式，并使用了一个 LET 语句，导致定义被计算为一个数字。

[](https://help.qlik.com/en-US/sense/Subsystems/Hub/Content/Sense_Hub/Scripting/ScriptRegularStatements/Constrain.htm)

#### 使用 SET 成果加载

概述

打开数据加载编辑器，并将下面的加载脚本添加到新部分。

加载脚本包含：

* Constrain 语句，指定 h 的变量定义需要有 text 类型。

* 定义变量 SET 的 h 语句。

加载脚本

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

加载数据。

重载成功。约束要求变量 h 采用文本类型。变量定义包含一个数字表达式，但因为使用了 SET 语句，所以定义以文本形式求值。

[](https://help.qlik.com/en-US/sense/Subsystems/Hub/Content/Sense_Hub/Scripting/ScriptRegularStatements/Constrain.htm)

#### 使用 LET 成功重载

概述

打开数据加载编辑器，并将下面的加载脚本添加到新部分。

加载脚本包含：

* Constrain 语句，指定 i 的变量定义需要有 number 类型。

* 定义变量 LET 的 i 语句。

加载脚本

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

加载数据。

重载成功。约束要求变量 i 采用数字类型。变量定义包含一个数值表达式，并使用了一个 LET 语句，导致定义被计算为一个数字。

## 示例 - 多重约束

[](https://help.qlik.com/en-US/sense/Subsystems/Hub/Content/Sense_Hub/Scripting/ScriptRegularStatements/Constrain.htm)

#### 设置最小值和最大值

概述

打开数据加载编辑器，并将下面的加载脚本添加到新部分。

加载脚本包含：

* Constrain 语句，指定 j 的变量定义需要介于 1 至 5 之间。

* 定义变量 LET 的 j 语句。

加载脚本

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

加载数据。

重载成功。变量 f 的值计算为 2，在可接受范围内。

[](https://help.qlik.com/en-US/sense/Subsystems/Hub/Content/Sense_Hub/Scripting/ScriptRegularStatements/Constrain.htm)

#### 接受列表中的文本和数字

概述

打开数据加载编辑器，并将下面的加载脚本添加到新部分。

加载脚本包含：

* Constrain 语句，允许变量为文本或数字，只要是可接受值之一即可。

* 定义变量 LET 的 k 语句。

加载脚本

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

加载数据。

重载成功。变量 k 的值可在可接受值列表中找到。同样，将 k 指定为 3 将导致重载成功。

## 示例 - 解决变量定义冲突

[](https://help.qlik.com/en-US/sense/Subsystems/Hub/Content/Sense_Hub/Scripting/ScriptRegularStatements/Constrain.htm)

#### 加载脚本和结果

概述

本例说明了为应用程序中已定义的变量添加约束条件时，发生变量定义冲突的方式。

加载脚本 1：设置脚本变量

打开 数据加载编辑器。添加以下脚本：

```
LET vConflictExample = 'Department C';
```

加载数据。重载成功。变量 vConflictExample 已在应用程序中创建为脚本变量。

加载脚本 2：尝试对先前加载的脚本变量定义约束

删除加载脚本 1。添加以下脚本：

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

加载数据。

尽管新的约束和值定义兼容，但重载失败，出现约束错误。这是因为加载脚本 1 已经将变量加载至应用程序中，并带有一个文本值，而这个值仍然持久存在于应用程序中。要解决这个问题，我们需要重置变量约束和定义。请参阅加载脚本 3。

加载脚本 3：重置约束和值定义

删除加载脚本 2。添加以下脚本：

```
CONSTRAIN vConflictExample;
LET vConflictExample;

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

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

加载数据。

重载成功。上面的脚本可以分成三部分，每个部分之间用空行隔开：

* 第一部分重新设置 vConflictExample 的约束条件和值定义。这将删除用加载脚本 1 载入应用程序的定义。

* 第二部分重新应用加载脚本 2 内失败的新约束和值定义。

* 第三部分简单地添加了模拟数据，这样我们就可打开工作表视图并检查变量值（见下图）。

在编辑模式下将工作表视图打开，然后打开the 变量 icon对话框。我们可以看到，已成功创建变量 vConflictExample。

工作表视图中的变量对话框显示 vConflictExample 的变量定义冲突已解决。

工作表视图中的变量对话框显示 vConflictExample 的变量定义冲突已解决。

工作表视图中的变量对话框显示 vConflictExamplevConflictExample 的变量定义冲突已解决。 ![Variables dialog in sheet view showing that the script variable has successfully been created.](https://help.qlik.com/zh-CN/sense/May2026/Subsystems/Hub/Content/Resources/Images/ui_script-variable_constrain-conflict-resolved.png)

[Let](https://help.qlik.com/zh-CN/sense/May2026/Subsystems/Hub/Content/Sense_Hub/Scripting/ScriptRegularStatements/Let.htm)

[Set](https://help.qlik.com/zh-CN/sense/May2026/Subsystems/Hub/Content/Sense_Hub/Scripting/ScriptRegularStatements/Set.htm)

[在数据加载编辑器中使用变量](https://help.qlik.com/zh-CN/sense/May2026/Subsystems/Hub/Content/Sense_Hub/Scripting/work-with-variables-in-data-load-editor.htm)