Required properties（必需属性(Required properties)）¶
Required properties are object type properties that must have a value. You can use this object type property to validate that there are no objects that have a null value for this property, or an empty array if it is an array property. This validation applies to data from the backing datasource and edits via actions.
Summary of required properties¶
When working with required properties, keep the following in mind:
- Validation happens when data is being indexed into the object: The check for null values happens as backing datasources are indexed into Object Storage. This means that the ontology modification itself will succeed if the column backing a required property contains null values.
- Array properties cannot be empty: Setting an array property to required ensures the presence of at least one item.
- Changes via actions are validated at apply time: If you attempt to write a null or empty value to a property via an action, the action will fail to execute.
- Available only in Object Storage V2: Required properties are only supported by object types leveraging Object Storage V2.
Create a required property¶
- Navigate to Ontology Manager.
- Choose the object type, and then the property you want to set as required.
- Select Create Property and fill in the required details, including the property name, type, and description.
- Under the Configuration section, toggle on the Required toggle.
- Save your changes to the Ontology and wait for the reindex to be completed.
Note that if there is any null value currently set on the backing column for the property, the reindex will fail. To fix this, you must either update the backing datasource to no longer have nulls in the column, or unset the property as required.
Required properties that allow empty arrays¶
You can configure your required property to allow empty arrays. This means that the property will still reject null values, but will accept empty arrays. This is useful for mandatory control properties which can never be null, but can be configured to allow empty arrays. Learn more about mandatory control properties.
It is important to note that Actions will write an empty array to any property that is mapped to a parameter, but the parameter is not set. This means that if you have a required property that allows empty arrays, and you leave the parameter blank in an Action, the Action will succeed and write an empty array to the property. If you do not want this behavior and want to enforce that users always set a value for this property via Actions, you should not allow empty arrays on your required property.
Required properties for object types with multiple backing datasources¶
You may occasionally encounter situations where null values appear in required properties of object types backed by multiple datasources. This phenomenon occurs when a record for the object is present in some datasources, but absent in the datasource that supplies the required property.
The following example illustrates this behavior. Assume there is a Movie object type with two backing datasources and a Genre property that is required.
Datasource 1
| Movie Id | Title | Box office | Regions |
|---|---|---|---|
| 101 | The Adventure Begins | 200m | ["USA", "Canada", "UK"] |
| 102 | Love in the City | 75m | [] |
| 103 | Galactic Battles | 500m | ["USA", "UK", "Australia"] |
Datasource 2
| Movie Id | Budget | Genre (Required) | Director |
|---|---|---|---|
| 101 | 50m | Adventure | Michael John Smith |
| 102 | 20m | Romance | Jane Doe |
| 103 | 150m | Sci-Fi |
If a new Movie is added to both backing datasources without providing a value for Genre, it will fail to index to the Ontology.
However, suppose only Datasource 1 had a row for the new Movie object.
Datasource 1
| Movie Id | Title | Box office | Regions |
|---|---|---|---|
| 101 | The Adventure Begins | 200m | ["USA", "Canada", "UK"] |
| 102 | Love in the City | 75m | [] |
| 103 | Galactic Battles | 500m | ["USA", "UK", "Australia"] |
| 104 | Happy Ending | 150m | ["UK", "FRANCE"] |
Datasource 2
| Movie Id | Budget | Genre (Required) | Director |
|---|---|---|---|
| 101 | 50m | Adventure | Michael John Smith |
| 102 | 20m | Romance | Jane Doe |
| 103 | 150m | Sci-Fi |
The example above will successfully get indexed into the Ontology, despite the fact that the resulting object would have no value for the required property.
| Property | Value |
|---|---|
| Movie Id | 104 |
| Title | Happy Ending |
| Box Office | 150m |
| Regions | ["UK", "FRANCE"] |
| Budget | |
| Genre (Required) | |
| Director |
The same applies to objects created via Action edits. Movie objects can be created or modified successfully, if they only contain properties tied to columns in Datasource 1. However if the Action adds a property to the object that is sourced from Datasource 2, such as Budget, then the Action will be invalid and will fail to execute. This is because the object will now be present on Datasource 2 and thus Genre must be set.
中文翻译¶
必需属性(Required properties)¶
必需属性是指必须包含值的对象类型属性。您可以使用此对象类型属性来验证是否存在对该属性具有空值(null value)的对象，或者对于数组属性而言是否存在空数组。此验证适用于来自后端数据源(backing datasource)的数据以及通过操作(actions)进行的编辑。
必需属性概述¶
在处理必需属性时，请牢记以下几点：
- 验证发生在数据索引到对象时： 空值检查在后端数据源索引到对象存储(Object Storage)时进行。这意味着，如果支持必需属性的列包含空值，本体论修改本身仍会成功。
- 数组属性不能为空： 将数组属性设置为必需属性可确保至少包含一个元素。
- 通过操作进行的更改在应用时进行验证： 如果您尝试通过操作向属性写入空值或空数组，该操作将执行失败。
- 仅在对象存储V2中可用： 必需属性仅受使用对象存储V2(Object Storage V2)的对象类型支持。
创建必需属性¶
- 导航至本体论管理器(Ontology Manager)。
- 选择对象类型，然后选择要设置为必需的属性。
- 选择创建属性(Create Property)并填写必要详细信息，包括属性名称、类型和描述。
- 在配置(Configuration)部分，打开必需(Required)开关。
- 保存(Save)您对本体的更改，并等待重新索引完成。
请注意，如果该属性的支持列当前存在任何空值，重新索引将失败。要解决此问题，您必须更新后端数据源，使其列中不再包含空值，或者取消该属性的必需设置。
允许空数组的必需属性¶
您可以配置必需属性以允许空数组。这意味着该属性仍会拒绝空值，但会接受空数组。这对于强制控制属性(mandatory control properties)非常有用，这些属性永远不能为空，但可以配置为允许空数组。了解更多关于强制控制属性的信息。
需要注意的是，操作会将空数组写入任何映射到参数但未设置该参数的属性。这意味着，如果您有一个允许空数组的必需属性，并且在操作中留空参数，操作将成功执行并向该属性写入空数组。如果您不希望出现这种行为，并希望强制用户始终通过操作为此属性设置值，则不应在必需属性上允许空数组。
具有多个后端数据源的对象类型的必需属性¶
您偶尔可能会遇到这样的情况：在由多个数据源支持的对象类型的必需属性中出现空值。当对象的记录存在于某些数据源中，但不存在于提供必需属性的数据源中时，就会发生这种现象。
以下示例说明了这种行为。假设有一个Movie对象类型，具有两个后端数据源和一个必需属性Genre。
数据源1
| Movie Id | Title | Box office | Regions |
|---|---|---|---|
| 101 | The Adventure Begins | 200m | ["USA", "Canada", "UK"] |
| 102 | Love in the City | 75m | [] |
| 103 | Galactic Battles | 500m | ["USA", "UK", "Australia"] |
数据源2
| Movie Id | Budget | Genre (必需) | Director |
|---|---|---|---|
| 101 | 50m | Adventure | Michael John Smith |
| 102 | 20m | Romance | Jane Doe |
| 103 | 150m | Sci-Fi |
如果向两个后端数据源添加一个新的Movie对象，但未提供Genre的值，则该对象将无法索引到本体中。
然而，假设只有数据源1包含新Movie对象的行。
数据源1
| Movie Id | Title | Box office | Regions |
|---|---|---|---|
| 101 | The Adventure Begins | 200m | ["USA", "Canada", "UK"] |
| 102 | Love in the City | 75m | [] |
| 103 | Galactic Battles | 500m | ["USA", "UK", "Australia"] |
| 104 | Happy Ending | 150m | ["UK", "FRANCE"] |
数据源2
| Movie Id | Budget | Genre (必需) | Director |
|---|---|---|---|
| 101 | 50m | Adventure | Michael John Smith |
| 102 | 20m | Romance | Jane Doe |
| 103 | 150m | Sci-Fi |
尽管最终生成的对象对于必需属性没有值，上述示例仍会成功索引到本体中。
| 属性 | 值 |
|---|---|
| Movie Id | 104 |
| Title | Happy Ending |
| Box Office | 150m |
| Regions | ["UK", "FRANCE"] |
| Budget | |
| Genre (必需) | |
| Director |
同样的规则也适用于通过操作编辑创建的对象。如果Movie对象仅包含与数据源1中列相关的属性，则可以成功创建或修改。但是，如果操作向对象添加了来自数据源2的属性（例如Budget），则该操作将无效并执行失败。这是因为该对象现在将出现在数据源2中，因此必须设置Genre。