属性与基础类型

属性是什么

上一节定好了对象类型的骨架，这一节看骨架上的每一根骨头：属性。属性（Property）是对象某一方面特征的定义，相当于数据表的一列；属性值是某个对象在这一列上的取值。

除了名字和类型，一个属性还带着一组元数据，让人和智能体读得懂它：

• name：API name，camelCase，最多 64 个字符，同一个对象类型里不能重复。
• title 和 comment：显示名和说明，写给人看。
• unit：单位，最多 16 个字符。数值有了单位，读的人就不用猜。
• synonyms：同义词。智能体靠它按业务说法找到属性，比如把 goodQty 找成「良品数」。
• visibility 和 status：让应用知道这个属性该多显眼、能不能依赖。

元数据写全的属性长这样。它的值大多来自数据源里的一列，也可以只在语义层维护，那是第 7 节的内容。

{ "name": "goodQty", "type": "integer", "title": "Good quantity", "unit": "pcs",
  "synonyms": ["yield", "good count"], "comment": "Units that passed final inspection." }

应用和 Action 按 API name 引用属性，所以改类型、删属性都是破坏性改动，要走分支和提案；只改显示名、说明和同义词，不会打断任何引用。

基础类型：一张全表

基础类型（base type）决定属性存什么形状的值，也决定应用能对它做什么。AIDC 支持 string、integer、long、short、byte、boolean、float、double、decimal、date、timestamp、array、struct、vector、geopoint、geoshape、attachment、mediaReference、timeseries、geotimeSeriesReference、cipherText、marking。最常被问的是：哪个类型能做主键，哪个能做标题键？

「不能」的，在定义时就会被拒绝；「不建议」的，能保存，但会给一个警告。

这些类型也决定了 Semantic 数据库里的列类型：string、marking、cipherText 是 text；integer、short、byte、long 是 bigint；float、double 是 double precision；decimal 是 numeric；boolean 是 boolean；date、timestamp 分别是 date、timestamptz；其余类型是 jsonb。

给一个属性选类型的四个问题

遇到一个新字段，不用背表，按顺序问四个问题：

1. 它是名字还是数？

   编号、代码是 string，计数是 integer，金额是 decimal，测量值和评分是 double。

2. 只有日期，还是精确到时刻？

   承诺交期只要日期，用 date；工单的开始和到期要精确到时刻，用 timestamp。

3. 一个值，还是多个值？

   多个同类值用 array；几个有名字的字段用结构体，后面的课会讲。

4. 它要做主键或标题键吗？

   回到上面的表查一遍，再决定。

最常见的坑是全部写成 string。ERP 导出的文本里什么都是字符串，照单全收的话，数量没法求和，日期没法比较，排序也会按字母来。类型在定义里选对一次，比在每个应用里各转换一遍划算得多。

选类型时会踩的坑

数组要同时写 arraySubType：客户的标签是 array 加 string。数组里不能有 null，不能嵌套，vector 和 timeseries 也不能放进数组。下面是 SalesOrder 的定义和读回来的一个对象，注意 totalUsd 的写法。

{
  "kind": "objectType",
  "apiName": "SalesOrder",
  "title": "Sales order",
  "schema": {
    "titleColumn": "orderNo",
    "columns": [
      { "name": "orderNo", "type": "string", "primaryKey": true, "title": "Order no." },
      { "name": "orderDate", "type": "date", "title": "Order date" },
      { "name": "promisedDate", "type": "date", "title": "Promised date" },
      { "name": "totalUsd", "type": "decimal", "title": "Order total", "unit": "USD" },
      { "name": "customerId", "type": "string", "title": "Customer", "references": { "entity": "Customer", "column": "customerId" } }
    ]
  }
}

{
  "__apiName": "SalesOrder",
  "__primaryKey": "SO-2026-0412",
  "__title": "SO-2026-0412",
  "orderNo": "SO-2026-0412",
  "orderDate": "2026-09-02",
  "promisedDate": "2026-10-15",
  "totalUsd": "18450.00",
  "customerId": "C-1008"
}

下一节讲那些不是「一个数字或一段文字」的类型：位置、时间序列、向量、附件。