Configure derived properties（配置派生属性）

:::callout{theme="neutral" title="Beta"} Derived properties are in the beta phase of development and may not be available on your enrollment. Functionality may change during active development. :::

Overview

Derived properties are properties that are calculated at runtime based on values from linked objects. Instead of storing data directly, a derived property pulls information from objects connected through link types, optionally applying aggregations like averaging, counting, or collecting values into lists.

For example:

• A Department object type could have a derived property for "Average employee salary" that aggregates salary values from all linked Employee objects.
• A Project object type could have a derived property for "Lead engineer name" that retrieves the name from a single linked Engineer object.
• An Order object type could have a derived property for "Product names" that collects all product names from linked Product objects into a list.

Derived properties are read-only and cannot be edited by functions or actions. These properties use the security context of all objects involved in the calculation, ensuring users only see information for which they have access authorization.

Configure a derived property

To configure a derived property on an object type, follow the steps below.

1. Open the property configuration panel

From the Properties tab of your object type, select New property or click on an existing property to edit it. This opens the property configuration side panel.

2. Navigate to the Source tab

In the property configuration side panel, select the Source tab to configure where the property gets its values.

3. Select the Linked objects source type

In the Source type section, choose the Linked objects option. This enables derived property configuration.

4. Select a link type

In the Linked objects section, select a link type from the dropdown. This determines which objects the property will derive values from.

• The dropdown menu shows all available link types from your current object type.
• After selecting a link type, you can optionally add additional link types to traverse multiple levels of connections (up to 3 levels).
• Use Add linked object to traverse through another level of linked objects.

5. Configure aggregation (if needed)

If any link in your chain has a "many" cardinality (one object linking to multiple objects), you must select an Aggregation to combine the values:

Available aggregations:

• Count: Count the number of linked objects.
• Average: Calculate the average of numeric values.
• Sum: Calculate the sum of numeric values.
• Minimum: Select the minimum value.
• Maximum: Select the maximum value.
• Approximate cardinality: Estimate the number of unique values.
• Exact cardinality: Count the exact number of unique values.
• Collect list: Collect all values into an ordered list (preserves duplicates).
• Collect set: Collect all unique values into an unordered set.

6. Select the property to derive

After selecting a link type (and aggregation if needed), choose which property from the linked object type you want to derive:

• The dropdown menu shows all available properties from the final object type in your link chain.
• For Count aggregation, you do not need to select a property as objects are automatically counted.

7. Configure collection limit (for collect aggregations)

If you selected Collect list or Collect set as your aggregation, you can optionally set a limit on the number of items collected. The default limit is 10 items.

Multi-hop derived properties

Derived properties support traversing up to 3 levels of linked objects. This allows you to derive properties from objects that are indirectly connected to your starting object type.

For example:

• A Department object type could derive "Project names" by traversing through Employee objects to their linked Project objects.
• The link chain would be: Department → Employee → Project

To configure multi-hop:

1. Select your first link type.
2. Select Add linked object to add another level.
3. Select the next link type from the newly-connected object type.
4. Repeat up to 3 levels total.

Known limitations

• OSv1 support: Queries with derived properties may not contain any object types indexed using OSv1.
• Text search: Derived properties cannot be used in text search or keyword filters.
• Structs in OSDK: In current versions of the TypeScript OSDK, queries with derived properties may not contain any struct property types. You can use a $select operation to exclude struct properties.
• Inline actions: Properties with inline actions configured cannot be converted to derived properties.
• Value types: Properties with value types cannot be converted to derived properties.
• Required properties: Derived properties cannot be marked as required (non-nullable).
• Property type constraints: Derived properties cannot have property type constraints.
• Display formatting: Derived properties cannot have rule set bindings or base formatters.
• Primary keys: Primary key properties cannot be derived properties.
• Ontology condition: Derived properties are not supported for the Default ontology.

---

中文翻译

---

配置派生属性

:::callout{theme="neutral" title="Beta"} 派生属性（Derived properties）目前处于测试版开发阶段，您的实例可能尚未支持。功能在活跃开发期间可能会发生变化。 :::

概述

派生属性是在运行时基于关联对象的值计算得出的属性。派生属性不直接存储数据，而是通过链接类型（link types）从关联对象中提取信息，并可选择性地应用聚合操作，例如求平均值、计数或将值收集到列表中。

例如：

• Department 对象类型可以有一个"员工平均薪资"的派生属性，该属性汇总所有关联 Employee 对象的薪资值。
• Project 对象类型可以有一个"首席工程师姓名"的派生属性，该属性从单个关联的 Engineer 对象中检索姓名。
• Order 对象类型可以有一个"产品名称"的派生属性，该属性将所有关联 Product 对象的产品名称收集到一个列表中。

派生属性是只读的，无法通过函数或操作（actions）进行编辑。这些属性使用计算中涉及的所有对象的安全上下文，确保用户只能看到其有权访问的信息。

配置派生属性

请按照以下步骤在对象类型上配置派生属性。

1. 打开属性配置面板

在对象类型的属性选项卡中，选择新建属性或点击现有属性进行编辑。这将打开属性配置侧面板。

2. 导航至"来源"选项卡

在属性配置侧面板中，选择来源选项卡，以配置属性值的获取来源。

3. 选择"关联对象"来源类型

在来源类型部分，选择关联对象选项。这将启用派生属性配置。

4. 选择链接类型

在关联对象部分，从下拉菜单中选择一个链接类型。这将决定属性将从哪些对象派生值。

• 下拉菜单显示当前对象类型的所有可用链接类型。
• 选择链接类型后，您可以选择添加额外的链接类型，以遍历多个层级（最多3层）的连接。
• 使用添加关联对象来遍历另一层级的关联对象。

5. 配置聚合（如需要）

如果链接链中的任何一环具有"多"基数（一个对象链接到多个对象），则必须选择一种聚合方式来合并这些值：

可用聚合方式：

• 计数（Count）： 统计关联对象的数量。
• 平均值（Average）： 计算数值的平均值。
• 总和（Sum）： 计算数值的总和。
• 最小值（Minimum）： 选取最小值。
• 最大值（Maximum）： 选取最大值。
• 近似基数（Approximate cardinality）： 估算唯一值的数量。
• 精确基数（Exact cardinality）： 精确统计唯一值的数量。
• 收集为列表（Collect list）： 将所有值收集到一个有序列表中（保留重复项）。
• 收集为集合（Collect set）： 将所有唯一值收集到一个无序集合中。

6. 选择要派生的属性

选择链接类型（以及聚合方式，如需要）后，选择要从关联对象类型派生的属性：

• 下拉菜单显示链接链中最终对象类型的所有可用属性。
• 对于计数聚合，无需选择属性，因为对象会被自动计数。

7. 配置收集限制（适用于收集类聚合）

如果您选择了收集为列表或收集为集合作为聚合方式，可以选择设置收集项目的数量限制。默认限制为10个项目。

多跳派生属性

派生属性支持遍历最多3层关联对象。这允许您从与起始对象类型间接关联的对象派生属性。

例如：

• Department 对象类型可以通过 Employee 对象遍历到其关联的 Project 对象，从而派生"项目名称"。
• 链接链为：Department → Employee → Project

配置多跳的步骤：

1. 选择您的第一个链接类型。
2. 选择添加关联对象以添加另一个层级。
3. 从新连接的对象类型中选择下一个链接类型。
4. 重复此操作，最多总计3层。

已知限制

• OSv1 支持： 包含派生属性的查询可能无法包含任何使用 OSv1 索引的对象类型。
• 文本搜索： 派生属性不能用于文本搜索或关键词过滤器。
• OSDK 中的结构体（Structs）： 在当前版本的 TypeScript OSDK 中，包含派生属性的查询可能无法包含任何结构体属性类型。您可以使用 $select 操作来排除结构体属性。
• 内联操作（Inline actions）： 配置了内联操作的属性无法转换为派生属性。
• 值类型（Value types）： 具有值类型的属性无法转换为派生属性。
• 必填属性： 派生属性不能标记为必填（非空）。
• 属性类型约束： 派生属性不能有属性类型约束。
• 显示格式： 派生属性不能有规则集绑定或基础格式化器。
• 主键： 主键属性不能是派生属性。
• 本体条件： 默认本体（Default ontology）不支持派生属性。