Object identifiers（对象标识符）

The identity of an object in Foundry is represented in a few different ways, and understanding these different representations can be important for writing correct code in functions. This section explains the various ways that objects are identified and the implications for your code.

Types of identifiers

Object RIDs

A "RID" refers to a Resource Identifier ↗, Palantir’s open-source specification used to identify an entity. Ontology objects have a RID assigned to them when they are created, either from indexing a backing dataset or as part of an Action.

In functions, every Ontology object has a rid field of type string | undefined. The reason a RID may be undefined is that it’s possible to create a new object in functions using the object creation API. Newly created objects always have a rid value of undefined, while existing objects always have a defined rid.

Primary keys

Objects can also be uniquely identified by their object type and primary key. A primary key is a unique propertyId and value pair. For example, an Employee object type may be uniquely identified by a string property called employeeId.

All Ontology objects always have a typeId and primaryKey field that is present, including newly created objects. This is because you are required to provide the primary key when creating a new object.

Implications for code

Checking for equality

Within functions, each Ontology object is represented using a JavaScript object ↗. It’s possible for one Ontology object to be represented as multiple JavaScript objects. For example, this can happen if you load the Ontology object from an Object search multiple times, or load an object from an Object search in addition to having it passed in as a parameter:

public myFunction(employee: Employee): void {
    const employee2 = Objects.search().employee()
        .filter(e => e.id.exactMatch(employee.id))
        .all()[0];
    console.log(employee == employee2); // false
    console.log(employee === employee2); // false
    console.log(employee.id === employee2.id); // true
}

Even though both employee and employee2 refer to the same conceptual Ontology object in the above example, comparing them using the == and === operators returns false because the variables refer to two distinct JavaScript objects. Simply comparing the rid fields can be problematic because newly created objects have a rid of undefined.

As a result, the best way to compare two Ontology objects for equality is to compare the typeId and primaryKey:

function isEqual(o1: OntologyObject, o2: OntologyObject) {
    return o1.typeId === o2.typeId
        && JSON.stringify(o1.primaryKey) == JSON.stringify(o2.primaryKey);
}

Object mappings

It can often be useful to store a mapping from an object to some value. For example, you may want to iterate through an array of objects and store values for more efficient lookup.

Because of the equality checking issues described above, you cannot simply use a JavaScript Map to store values for each object. Instead, you can use a FunctionsMap which is specifically designed to support OntologyObjects as keys.

---

中文翻译

对象标识符

Foundry 中对象的身份通过几种不同方式表示，理解这些不同的表示形式对于在函数中编写正确的代码至关重要。本节将解释对象被识别的各种方式及其对代码的影响。

标识符类型

对象 RID

"RID" 指的是资源标识符 ↗，这是 Palantir 用于标识实体的开源规范。本体论(Ontology)对象在创建时（无论是通过索引底层数据集还是作为操作(Action)的一部分）都会被分配一个 RID。

在函数中，每个本体论对象都有一个类型为 string | undefined 的 rid 字段。RID 可能为 undefined 的原因是，可以使用对象创建 API 在函数中创建新对象。新创建的对象始终具有 undefined 的 rid 值，而现有对象始终具有已定义的 rid。

主键

对象也可以通过其对象类型和主键唯一标识。主键是一个唯一的 propertyId 和值对。例如，员工(Employee)对象类型可以通过名为 employeeId 的 string 属性唯一标识。

所有本体论对象始终具有 typeId 和 primaryKey 字段，包括新创建的对象。这是因为在创建新对象时需要提供主键。

对代码的影响

检查相等性

在函数内部，每个本体论对象都使用 JavaScript 对象 ↗ 表示。一个本体论对象可能被表示为多个 JavaScript 对象。例如，如果您多次从对象搜索加载本体论对象，或者除了将其作为参数传入外还从对象搜索加载对象，就可能发生这种情况：

public myFunction(employee: Employee): void {
    const employee2 = Objects.search().employee()
        .filter(e => e.id.exactMatch(employee.id))
        .all()[0];
    console.log(employee == employee2); // false
    console.log(employee === employee2); // false
    console.log(employee.id === employee2.id); // true
}

尽管在上面的示例中 employee 和 employee2 都指向同一个概念上的本体论对象，但使用 == 和 === 运算符比较它们会返回 false，因为这些变量指向两个不同的 JavaScript 对象。简单地比较 rid 字段可能会出现问题，因为新创建的对象的 rid 为 undefined。

因此，比较两个本体论对象是否相等的最佳方法是比较 typeId 和 primaryKey：

function isEqual(o1: OntologyObject, o2: OntologyObject) {
    return o1.typeId === o2.typeId
        && JSON.stringify(o1.primaryKey) == JSON.stringify(o2.primaryKey);
}

对象映射

存储从对象到某个值的映射通常非常有用。例如，您可能希望遍历对象数组并存储值以实现更高效的查找。

由于上述相等性检查的问题，您不能简单地使用 JavaScript Map 为每个对象存储值。相反，您可以使用专门设计用于支持 OntologyObjects 作为键的 FunctionsMap。