Python 온톨로지 편집 컨테이너

Python 함수는 FoundryClient의 편집 컨테이너에서 변경을 모아 list[OntologyEdit]로 반환합니다. 실제 편집은 함수 기반 액션이 적용합니다. 변경 뒤 검색과 집계에 새 값이 필요하면 적용 대기 쓰기를 사용합니다.

선언과 수정 가능한 객체

function의 edits에 객체 유형과 필요한 다대다 링크를 선언하고 반환 타입을 명시합니다. 일반 OSDK 객체는 읽기 전용이며 직접 속성을 바꾸면 예외가 발생합니다.

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


@function(edits=[Employee])
def update_employee_last_name(employee: Employee, new_name: str) -> list[OntologyEdit]:
    edits = FoundryClient().ontology.edits()
    editable = edits.objects.Employee.edit(employee)
    editable.last_name = new_name
    return edits.get_edits()

edit에는 객체 대신 기본 키를 전달할 수도 있습니다. 수정 가능한 객체에서 값을 다시 읽으면 새 값이 보이지만, 원래의 읽기 전용 객체는 바뀌지 않습니다.

배열은 다시 대입

수정 가능한 객체의 배열은 Python list이지만 제자리 수정만 하면 편집이 기록되지 않습니다. 복사하여 바꾼 뒤 속성에 대입해야 합니다. 아래는 tags가 문자열 배열인 Employee의 예제입니다.

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


@function(edits=[Employee])
def append_employee_tag(employee: Employee, new_tag: str) -> list[OntologyEdit]:
    edits = FoundryClient().ontology.edits()
    editable = edits.objects.Employee.edit(employee)
    tags = list(editable.tags or [])
    tags.append(new_tag)
    editable.tags = tags
    return edits.get_edits()

기존 객체의 기본 키는 바꿀 수 없습니다.

구조체 속성, Beta

구조체 편집은 function의 beta=True로 활성화합니다. OSDK가 만든 객체별 모듈의 구조체 클래스를 사용해야 하며 사용자 dataclass로 대체할 수 없습니다.

가상의 MyObjectType.my_struct_property에 first_field String과 second_field Boolean이 있고 생성된 클래스가 MyStructPropertyClass라고 가정합니다.

from functions.api import OntologyEdit, function
from ontology_sdk import FoundryClient
from ontology_sdk.ontology.objects import MyObjectType
from ontology_sdk.ontology.objects.my_object_type import MyStructPropertyClass


@function(beta=True, edits=[MyObjectType])
def create_object(primary_key: str) -> list[OntologyEdit]:
    edits = FoundryClient().ontology.edits()
    created = edits.objects.MyObjectType.create(primary_key)
    created.my_struct_property = MyStructPropertyClass(
        first_field="Example value",
        second_field=True,
    )
    return edits.get_edits()

구조체는 create의 키워드 인수로 직접 넘기지 못합니다. 객체를 만든 뒤 반환한 수정 가능한 객체에 대입해야 합니다. 생성 클래스는 Python 필드 이름을 온톨로지 API 이름으로 변환합니다.

기존 구조체의 필드를 바꾼 뒤에도 전체 구조체를 다시 속성에 대입해야 편집을 기록합니다.

from functions.api import OntologyEdit, UserFacingError, function
from ontology_sdk import FoundryClient
from ontology_sdk.ontology.objects import MyObjectType


@function(beta=True, edits=[MyObjectType])
def update_struct_field(my_object: MyObjectType, new_value: str) -> list[OntologyEdit]:
    edits = FoundryClient().ontology.edits()
    editable = edits.objects.MyObjectType.edit(my_object)
    value = editable.my_struct_property
    if value is None:
        raise UserFacingError("수정할 구조체 값이 없습니다.")
    value.first_field = new_value
    editable.my_struct_property = value
    return edits.get_edits()

editable.my_struct_property.first_field = new_value만 수행하는 제자리 변경은 온톨로지 편집으로 등록되지 않습니다.

링크와 선언

수정 가능한 객체의 단일 링크는 set과 clear, 다중 링크는 add와 remove를 사용합니다. 예를 들어 editable_employee.supervisor.set(new_supervisor)로 상사를 지정하고 clear로 해제하거나, reports.add(new_report)와 reports.remove(old_report)로 보고자를 바꿀 수 있습니다. 수정 가능한 객체의 다음 링크 접근은 변경을 반영합니다.

다대다 링크는 OntologyLinkType(Employee, "assignedTickets")처럼 출발 유형과 온톨로지 링크 API 이름을 edits에 선언합니다. Python 접근 속성 assigned_tickets와 같은 문자열이라고 가정하면 안 됩니다.

일대일과 일대다는 외래 키 속성을 바꾸는 객체 편집이므로 외래 키를 가진 유형을 선언합니다.

생성과 연결

다음 가상 Ticket은 Integer 기본 키 ticket_id와 Date 속성 due_date를 갖고 Employee.assigned_tickets가 다대다 관계입니다. 날짜는 UTC 기준 7일 뒤로 설정합니다.

from datetime import datetime, timedelta, timezone
from functions.api import Integer, OntologyEdit, OntologyLinkType, function
from ontology_sdk import FoundryClient
from ontology_sdk.ontology.objects import Employee, Ticket


@function(edits=[Ticket, OntologyLinkType(Employee, "assignedTickets")])
def create_new_ticket_and_assign_to_employee(employee: Employee, ticket_id: Integer) -> list[OntologyEdit]:
    edits = FoundryClient().ontology.edits()
    ticket = edits.objects.Ticket.create(ticket_id)
    ticket.due_date = datetime.now(timezone.utc).date() + timedelta(days=7)
    edits.objects.Employee.edit(employee).assigned_tickets.add(ticket)
    return edits.get_edits()

일반 비구조체 속성은 기본 키 외의 create 키워드 인수로도 전달할 수 있습니다. 위 예제에서는 edits.objects.Ticket.create(ticket_id, due_date=new_due_date)가 같은 생성 방식입니다. new_due_date에는 계산한 Date 값을 전달합니다.

삭제

컨테이너의 객체 유형 delete에 객체나 기본 키를 넘깁니다. 아래 함수는 읽기 전용 Employee의 링크 메서드로 연결된 객체 집합을 얻고 페이지별로 읽어 모든 Ticket 객체를 삭제합니다. 수정 가능한 객체의 링크 편집 속성과 달리, 읽기 전용 링크는 assigned_tickets()처럼 호출합니다.

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


@function(edits=[Ticket])
def delete_assigned_tickets(employee: Employee) -> list[OntologyEdit]:
    edits = FoundryClient().ontology.edits()
    for ticket in employee.assigned_tickets().iterate():
        edits.objects.Ticket.delete(ticket)
    return edits.get_edits()

기본 키만 알고 있다면 edits.objects.Ticket.delete(ticket_id)를 사용할 수 있습니다. 객체 삭제와 링크 제거는 다른 동작입니다.