Ontology edits（本体编辑 (Ontology edits)）

In addition to writing functions that read data from the Ontology, you can also write functions that create objects and edit the properties and links between objects. This page documents the object edit APIs available to you in functions. For more details about how edit functions work, refer to the overview page.

For the edits created in a function to actually be applied, Ontology edit functions must be configured as a function-backed Action. Configuring an Action in this way allows you to provide additional metadata, configure permissions, and access the Action in various operational interfaces. As noted in the documentation, running an edit function outside of an Action will not actually modify any object data.

:::callout{theme="warning" title="Warning"} Searching for objects immediately after editing them may return unexpected results. See the Caveats section for details. :::

Define an edit function

Functions that edit the Ontology must:

• Be decorated with the @function(edits=[MyObjectType]) decorator imported from functions.api to specify the object types that will be edited.
• Have an explicit list[OntologyEdit] return type hint imported from functions.api.

Construct an Ontology edits container

To perform Ontology edits in a Python function, first construct an Ontology edits container from the OSDK client. For example:

ontology_edits = FoundryClient().ontology.edits()

This container is used to keep track of all edits made in a function.

Update properties

Ontology objects in Python functions are read-only by default. Attempts to modify their properties will raise an exception.

In order to edit an object, first obtain an editable view of that object using an Ontology edits container, either from an existing object instance:

editable_object = ontology_edits.objects.MyObjectType.edit(my_object)

or given an object primary key:

editable_object = ontology_edits.objects.MyObjectType.edit(object_primary_key)

Once you have an editable object, you can edit property values by reassigning the property value for an object. For example:

editable_employee.last_name = new_name

Subsequent access to the last_name property value of editable_employee later in the same function execution will yield the new value that was just set. However, the original non-editable object will not reflect the changes.

Array properties on editable objects are read-only. To modify an array, create a copy of it, modify the copy, then update the property:

# Copy to a new array
array_copy = list(editable_object.my_array_property)
# Now you can modify the copied array
array_copy.append(new_item)
# Then overwrite the property value
editable_object.my_array_property = array_copy

Note that the primary key property value of an existing object cannot be updated.

Update links

Single-link and multi-link properties have various methods for updating links:

# Set an Employee's supervisor
editable_employee.supervisor.set(new_supervisor)

# Clear an Employee's supervisor
editable_employee.supervisor.clear()

# Add a new report to the given employee
editable_employee.reports.add(new_report)

# Remove an old report associated with the given employee
editable_employee.reports.remove(new_report)

As with updating properties, accessing links of editable_employee after they have been updated will reflect the updates you have made.

Create objects

You can create new objects using the MyObjectType.create() method on the Ontology edits container. When creating a new object, you must specify a value for its primary key.

In this example, we create a new Ticket object with the given ID, set its due_date property, and assign it to the given Employee by modifying the assigned_tickets link.

from datetime import datetime, timedelta

from functions.api import function, Integer, Array, OntologyEdit
from ontology_sdk import FoundryClient
from ontology_sdk.ontology.objects import Employee, Ticket

@function(edits=[Employee, Ticket])
def create_new_ticket_and_assign_to_employee(
    employee: Employee,
    ticket_id: Integer
) -> list[OntologyEdit]:
    ontology_edits = FoundryClient().ontology.edits()

    new_ticket = ontology_edits.objects.Ticket.create(ticket_id)
    new_ticket.due_date = datetime.now() + timedelta(days=7)

    editable_employee = ontology_edits.objects.Employee.edit(employee)
    editable_employee.assigned_tickets.add(new_ticket)

    return ontology_edits.get_edits()

Property values may also be passed directly to the create method in addition to the primary key. For example:

new_due_date = datetime.now() + timedelta(days=7)
new_ticket = ontology_edits.objects.Ticket.create(ticket_id, due_date=new_due_date)

Delete objects

You can delete an object by calling the MyObjectType.delete() method on the Ontology edits container.

In this example, we delete all the tickets assigned to the given employee:

for ticket in employee.tickets:
    ontology_edits.objects.Ticket.delete(ticket)

Objects may also be deleted using a primary key instead of an instance:

ontology_edits.objects.Ticket.delete(ticket_id)

---

中文翻译

---

本体编辑 (Ontology edits)

除了编写从本体 (Ontology) 读取数据的函数外，您还可以编写创建对象以及编辑对象属性和链接的函数。 本文档记录了函数中可用的对象编辑 API。 有关编辑函数工作原理的更多详细信息，请参阅概述页面。

要使函数中创建的编辑实际生效，本体编辑函数 必须配置为函数支持的操作 (function-backed Action)。 以这种方式配置操作 (Action) 允许您提供额外的元数据、配置权限，并在各种操作界面中访问该操作。 如文档所述，在操作 (Action) 之外运行编辑函数不会实际修改任何对象数据。

:::callout{theme="warning" title="警告"} 在编辑对象后立即搜索对象可能会返回意外结果。详情请参阅注意事项部分。 :::

定义编辑函数 (Define an edit function)

编辑本体的函数必须：

• 使用从 functions.api 导入的 @function(edits=[MyObjectType]) 装饰器来指定将被编辑的对象类型。
• 具有从 functions.api 导入的显式 list[OntologyEdit] 返回类型提示。

构建本体编辑容器 (Construct an Ontology edits container)

要在 Python 函数中执行本体编辑，首先从 OSDK 客户端构建一个本体编辑容器。例如：

ontology_edits = FoundryClient().ontology.edits()

此容器用于跟踪函数中执行的所有编辑。

更新属性 (Update properties)

Python 函数中的本体对象默认是只读的。尝试修改其属性将引发异常。

为了编辑一个对象，首先使用本体编辑容器获取该对象的可编辑视图，可以从现有对象实例获取：

editable_object = ontology_edits.objects.MyObjectType.edit(my_object)

或者通过对象主键 (primary key) 获取：

editable_object = ontology_edits.objects.MyObjectType.edit(object_primary_key)

一旦您有了可编辑对象，就可以通过重新分配对象的属性值来编辑属性值。例如：

editable_employee.last_name = new_name

在同一函数执行的后续部分中，访问 editable_employee 的 last_name 属性值将返回刚刚设置的新值。但是，原始的不可编辑对象将不会反映这些更改。

可编辑对象上的数组属性 (Array properties) 是只读的。要修改数组，请创建它的副本，修改副本，然后更新属性：

# 复制到新数组
array_copy = list(editable_object.my_array_property)
# 现在您可以修改复制的数组
array_copy.append(new_item)
# 然后覆盖属性值
editable_object.my_array_property = array_copy

请注意，现有对象的主键属性值无法更新。

更新链接 (Update links)

单链接 (single-link) 和多链接 (multi-link) 属性有多种更新链接的方法：

# 设置员工的上级主管
editable_employee.supervisor.set(new_supervisor)

# 清除员工的上级主管
editable_employee.supervisor.clear()

# 为给定员工添加新的汇报对象
editable_employee.reports.add(new_report)

# 移除与给定员工关联的旧汇报对象
editable_employee.reports.remove(new_report)

与更新属性一样，在更新后访问 editable_employee 的链接将反映您所做的更新。

创建对象 (Create objects)

您可以使用本体编辑容器上的 MyObjectType.create() 方法创建新对象。创建新对象时，必须为其主键指定一个值。

在此示例中，我们使用给定的 ID 创建一个新的 Ticket 对象，设置其 due_date 属性，并通过修改 assigned_tickets 链接将其分配给给定的 Employee。

from datetime import datetime, timedelta

from functions.api import function, Integer, Array, OntologyEdit
from ontology_sdk import FoundryClient
from ontology_sdk.ontology.objects import Employee, Ticket

@function(edits=[Employee, Ticket])
def create_new_ticket_and_assign_to_employee(
    employee: Employee,
    ticket_id: Integer
) -> list[OntologyEdit]:
    ontology_edits = FoundryClient().ontology.edits()

    new_ticket = ontology_edits.objects.Ticket.create(ticket_id)
    new_ticket.due_date = datetime.now() + timedelta(days=7)

    editable_employee = ontology_edits.objects.Employee.edit(employee)
    editable_employee.assigned_tickets.add(new_ticket)

    return ontology_edits.get_edits()

除了主键之外，属性值也可以直接传递给 create 方法。例如：

new_due_date = datetime.now() + timedelta(days=7)
new_ticket = ontology_edits.objects.Ticket.create(ticket_id, due_date=new_due_date)

删除对象 (Delete objects)

您可以通过调用本体编辑容器上的 MyObjectType.delete() 方法来删除对象。

在此示例中，我们删除分配给给定员工的所有工单：

for ticket in employee.tickets:
    ontology_edits.objects.Ticket.delete(ticket)

也可以使用主键而不是实例来删除对象：

ontology_edits.objects.Ticket.delete(ticket_id)