API: Objects and links（API：对象与链接（Objects and links））¶
Every object type imported into your project is converted to a TypeScript API so you can easily access and manipulate objects available in Foundry.
Properties¶
Properties of each object type are converted to fields on the TypeScript interface generated for each object type. The generated field name uses the API Name specified in the ontology.
You can access the fields for each property with simple dot notation:
const firstName = employee.firstName;
Note that because properties may not have a concrete value set, the returned type when accessing a property value could be undefined. The TypeScript compiler will give an error unless you explicitly handle the undefined case. See this guide for more details on this.
Array properties¶
Array properties on an object type are converted to ReadOnlyArray types. This is so that the semantics for editing an array property are clear—the only way to modify the values of an array property is to update it with an entirely new array value.
If you want to manipulate the values of an array property, make a copy of it:
// Copy to a new array
let arrayCopy = [...myObject.myArrayProperty];
// Now you can modify the copied array
arrayCopy.push(newItem);
Link types¶
Link types between object types are also converted to fields on the TypeScript interface for each object type. To traverse the link, access the field and then call one of the methods used to load the objects. Link type field names are generated using the API Name specified in the ontology.
The Foundry Ontology supports defining 1-to-1, 1-to-many, and many-to-many link types. When accessing the 1 side of a link, the generated field is of the SingleLink type. You can access the linked object using the get() or getAsync() methods:
const manager = employee.manager.get();
As with properties, when you traverse a 1-to-1 or many-to-1 link, the return value may be undefined if there is no linked object. Follow the guide for handling undefined values for these links.
When accessing the many side of a link, the generated field is of the MultiLink type. You can access an Array of linked objects using the all() or allAsync() methods. If there are no linked objects, these methods will return an empty Array.
const employees = employee.reports.all();
Traversing links can be expensive because it requires loading which objects are linked in the backend. For details about how to perform link traversals more efficiently, see this section.
The array of linked objects returned from calling .all() or .allAsync() is a ReadOnlyArray. If you want to modify the array, make a copy of it first:
let copiedEmployees = [...employee.reports.all()];
You can traverse links as an ObjectSet to avoid loading linked object instances in the memory. When links are created in the Ontology, APIs will be generated on an object set of this type to "search around" to other linked object sets.
import { ObjectSet, Employee } from "@foundry/ontology-api";
// Assume you have an object set available:
// const employee_id = "123";
// const employeeObjectSet : ObjectSet<Employee> = Objects.search().employee().filter(exactMatch(employee_id));
const linkedObjs: ObjectSet<OtherObjectType> = employeeObjectSet.searchAroundToOtherObjectType();
If you operate on a single instance of an object and search around from there, you will get a MultiLink<objectType>. You cannot convert this MultiLink to an ObjectSet; you must convert the object instance to an object set to pivot to other object sets.
// Assuming:
// const employee: Employee
// MultiLink can be loaded in memory to process further.
const linkedObjs: MultiLink<objectType> = employee.reports
// Convert a sole object instance to an object set. This statement will take longer than an `employee().filter()` statement.
const employeeObjectSet : ObjectSet<Employee> = Objects.search().employee([employee])
// From there, you can use the above "searchAroundToOtherObjectType" to process only object sets.
Ontology metadata¶
Functions provides access to the available Ontology by providing the list of objects and properties. Ontology metadata information is available by accessing the constant types of each object type. See the sections below for more details.
Object property metadata¶
Object properties also include type metadata, which provides programmatic access to the type of each property. You can use this functionality for advanced workflows like identifying all properties of a given type or validating that a given property name has a specific type.
For instance, for an Ontology that contains an employee object type, you can access the type information on that object type's property as follows:
import { Employee } from "@foundry/ontology-api";
...
const type = Employee.properties.firstName;
In this case, if firstName is a string property on the Employee object type, then its type will be a StringPropertyBaseType.
The following property types are available:
BooleanPropertyBaseTypeBytePropertyBaseTypeDatePropertyBaseTypeFloatPropertyBaseTypeTimestampPropertyBaseTypeShortPropertyBaseTypeGeohashPropertyBaseType(To be used withgeopointproperties, previously namedgeohashproperties.)DecimalPropertyBaseTypeStringPropertyBaseTypeLongPropertyBaseTypeIntegerPropertyBaseTypeDoublePropertyBaseTypeArrayPropertyBaseTypeVectorPropertyBaseType
中文翻译¶
API：对象与链接（Objects and links）¶
导入到项目中的每个对象类型都会被转换为 TypeScript API，以便您可以轻松访问和操作 Foundry 中的可用对象。
属性（Properties）¶
每个对象类型的属性都会被转换为该对象类型生成的 TypeScript 接口中的字段。生成的字段名称使用本体（ontology）中指定的 API 名称（API Name）。
您可以使用简单的点号表示法访问每个属性的字段：
const firstName = employee.firstName;
请注意，由于属性可能没有具体的值设置，因此访问属性值时返回的类型可能是 undefined。除非您显式处理 undefined 的情况，否则 TypeScript 编译器会报错。有关此问题的更多详细信息，请参阅本指南。
数组属性（Array properties）¶
对象类型上的数组属性会被转换为 ReadOnlyArray 类型。这样做是为了明确编辑数组属性的语义——修改数组属性值的唯一方法是使用一个全新的数组值进行更新。
如果您想操作数组属性的值，请先复制一份：
// 复制到一个新数组
let arrayCopy = [...myObject.myArrayProperty];
// 现在您可以修改复制的数组
arrayCopy.push(newItem);
链接类型（Link types）¶
对象类型之间的链接类型也会被转换为每个对象类型的 TypeScript 接口中的字段。要遍历链接，请访问该字段，然后调用用于加载对象的方法之一。链接类型字段名称使用本体中指定的 API 名称生成。
Foundry 本体支持定义 1 对 1、1 对多和多对多链接类型。当访问链接的 1 端时，生成的字段类型为 SingleLink。您可以使用 get() 或 getAsync() 方法访问链接的对象：
const manager = employee.manager.get();
与属性类似，当您遍历 1 对 1 或多对 1 链接时，如果没有链接的对象，返回值可能是 undefined。请遵循指南处理这些链接的 undefined 值。
当访问链接的 多 端时，生成的字段类型为 MultiLink。您可以使用 all() 或 allAsync() 方法访问链接对象的数组。如果没有链接的对象，这些方法将返回一个空数组。
const employees = employee.reports.all();
遍历链接可能开销较大，因为它需要加载后端中哪些对象被链接。有关如何更高效地执行链接遍历的详细信息，请参阅本节。
从调用 .all() 或 .allAsync() 返回的链接对象数组是一个 ReadOnlyArray。如果您想修改该数组，请先复制一份：
let copiedEmployees = [...employee.reports.all()];
您可以将链接作为 ObjectSet 进行遍历，以避免将链接的对象实例加载到内存中。当在本体中创建链接时，将在此类型的对象集上生成 API，以"搜索周围"的其他链接对象集。
import { ObjectSet, Employee } from "@foundry/ontology-api";
// 假设您有一个可用的对象集：
// const employee_id = "123";
// const employeeObjectSet : ObjectSet<Employee> = Objects.search().employee().filter(exactMatch(employee_id));
const linkedObjs: ObjectSet<OtherObjectType> = employeeObjectSet.searchAroundToOtherObjectType();
如果您操作的是单个对象实例并从该实例进行搜索，您将得到一个 MultiLink<objectType>。您不能将此 MultiLink 转换为 ObjectSet；您必须将对象实例转换为对象集，才能转向其他对象集。
// 假设：
// const employee: Employee
// MultiLink 可以加载到内存中以进一步处理。
const linkedObjs: MultiLink<objectType> = employee.reports
// 将单个对象实例转换为对象集。此语句比 `employee().filter()` 语句耗时更长。
const employeeObjectSet : ObjectSet<Employee> = Objects.search().employee([employee])
// 然后，您可以使用上述的 "searchAroundToOtherObjectType" 仅处理对象集。
本体元数据（Ontology metadata）¶
Functions 通过提供对象和属性列表来访问可用的本体。本体元数据信息可通过访问每个对象类型的常量类型来获取。有关更多详细信息，请参阅以下各节。
对象属性元数据（Object property metadata）¶
对象属性还包括类型元数据，它提供了对每个属性类型的编程访问。您可以将此功能用于高级工作流，例如识别给定类型的所有属性，或验证给定属性名称是否具有特定类型。
例如，对于包含员工对象类型的本体，您可以按如下方式访问该对象类型属性上的类型信息：
import { Employee } from "@foundry/ontology-api";
...
const type = Employee.properties.firstName;
在这种情况下，如果 firstName 是 Employee 对象类型上的一个字符串属性，那么其类型将是 StringPropertyBaseType。
以下属性类型可用：
BooleanPropertyBaseTypeBytePropertyBaseTypeDatePropertyBaseTypeFloatPropertyBaseTypeTimestampPropertyBaseTypeShortPropertyBaseTypeGeohashPropertyBaseType（用于geopoint属性，以前称为geohash属性。）DecimalPropertyBaseTypeStringPropertyBaseTypeLongPropertyBaseTypeIntegerPropertyBaseTypeDoublePropertyBaseTypeArrayPropertyBaseTypeVectorPropertyBaseType