uip df 实体

“uip df实体”的语法和选项，可浏览和变异 Data Fabric 实体架构。

uip df entities browses and mutates Data Fabric entity schemas. An entity is a typed data model — a row shape with named fields and types. The verbs cover discovery (list, get), authoring (create, update), and removal (delete); record-level operations live on uip df records.

大纲

uip df entities list [--native-only] [--folder-key <key> | --include-folders]
uip df entities get <id> [--folder-key <key>]
uip df entities create <name> (-f <path> | --body <json>) [--folder-key <key>]
uip df entities update <id> (-f <path> | --body <json>) [-y --reason <text>] [--folder-key <key>]
uip df entities delete <id> -y --reason <text> [--folder-key <key>]

动词

动词	用途
list	List entities. Defaults to tenant-level entities; --folder-key scopes to one folder, --include-folders includes every folder's entities alongside tenant-level ones.
get	返回单个实体的架构（包括所有字段）。
create	根据 JSON 定义新建实体。
update	Update an entity's metadata or schema — add fields, update field metadata, or remove fields (destructive, requires -y/--reason).
delete	Delete an entity outright (destructive, requires -y/--reason).

--folder-key, --native-only, --include-folders

--folder-key <key> (a folder GUID) scopes a verb to a folder-level entity instead of the tenant. It's accepted on every verb in this group. On list, it's mutually exclusive with --include-folders (which lists tenant-level entities together with every folder's entities in one call). --native-only (on list only) filters out federated entities — those backed by an external connector connection (identified by a non-empty externalFields array).

uip df 实体列表

List Data Fabric entities.

选项

短	长	值	默认	描述
—	--native-only	标记	关闭	Show only native entities; exclude federated entities with external connections.
—	--folder-key	键值	—	Folder key (GUID) to scope the listing to a specific folder. Mutually exclusive with --include-folders.
—	--include-folders	标记	关闭	List tenant-level entities together with entities from every folder you can see. Mutually exclusive with --folder-key.

示例

uip df entities list --native-only

uip df entities list --folder-key f1000000-0000-0000-0000-000000000001

数据形状（--输出 json）

{
  "Code": "EntityList",
  "Data": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "name": "Invoice",
      "displayName": "Invoice",
      "entityType": "Standard",
      "description": "Invoice records",
      "folderId": "f1000000-0000-0000-0000-000000000001",
      "isRbacEnabled": false,
      "fields": [
        { "id": "f1000000-0000-0000-0000-000000000001", "name": "amount" }
      ],
      "externalFields": []
    }
  ]
}

重要提示：

Data rows here are the raw SDK objects, in camelCase — unlike get's response below, list does not PascalCase field names or reshape the payload. Each row's folderId is the value to pass as --folder-key on follow-up commands targeting that entity.

uip df 实体获取

返回单个实体的架构，包括所有字段。

参数

名称	必填	用途
<id>	是	实体 ID (UUID)。使用entities list查找。

选项

短	长	值	默认	描述
—	--folder-key	键值	—	Folder key (GUID) of the folder containing the entity, for folder-scoped entities.

示例

uip df entities get a1b2c3d4-0000-0000-0000-000000000001

数据形状（--输出 json）

{
  "Code": "EntitySchema",
  "Data": {
    "Id": "a1b2c3d4-0000-0000-0000-000000000001",
    "Name": "Invoice",
    "DisplayName": "Invoice",
    "EntityType": "Standard",
    "Description": "Invoice records",
    "IsRbacEnabled": false,
    "Fields": [
      {
        "Id": "f1000000-0000-0000-0000-000000000002",
        "Name": "amount",
        "DisplayName": "Amount",
        "FieldDataType": {
          "Name": "DECIMAL",
          "DecimalPrecision": 2,
          "MinValue": 0,
          "MaxValue": 999999
        },
        "IsRequired": true,
        "IsUnique": false,
        "IsEncrypted": false,
        "IsRbacEnabled": false,
        "IsPrimaryKey": false,
        "IsSystemField": false
      }
    ]
  }
}

Unlike list, this response is PascalCase. A field's type name and its constraints (DecimalPrecision, MinValue, MaxValue, LengthLimit, and so on, depending on type) live nested under FieldDataType, not as flat properties on the field.

uip df 实体创建

Create a new entity. The entity name must start with a letter and contain only letters, numbers, and underscores. Pass the definition either inline (--body) or from a file (--file).

参数

名称	必填	用途
<name>	是	实体名称（以字母开头；仅限字母、数字和下划线）。

选项

短	长	值	默认	描述
-f	--file	路径	—	Path to a JSON file with the entity definition (fields array required; displayName, description, isRbacEnabled, isAnalyticsEnabled optional).
—	--body	JSON	—	Inline JSON entity definition, same shape as --file.
—	--folder-key	键值	—	Folder key (GUID) of the target folder, to create a folder-scoped entity instead of a tenant-level one.

实体定义对象：

{
  "displayName": "Invoice",
  "description": "Invoice records",
  "isRbacEnabled": false,
  "fields": [
    { "name": "title", "type": "STRING" }
  ]
}

重要提示：

Each field object requires name, not fieldName — passing fieldName fails with the validation error Each field must include a 'name' string. A field object copied verbatim from entities get's output (which uses Name/FieldDataType, PascalCase) is also accepted here and normalized automatically to this flat write shape.

Valid type values come from the SDK's EntityFieldDataType enum — an invalid type fails with a ValidationError listing the full allowed set. Beyond the simple scalar types (STRING, DECIMAL, GUID, BOOLEAN, DATE, DATETIME, …), several types take extra required properties on the field object:

类型	Extra required properties
CHOICE_SET_SINGLE / CHOICE_SET_MULTIPLE	choiceSetId — UUID from df choice-sets list.
RELATIONSHIP	referenceEntityId (UUID of the target entity, from entities list) and referenceFieldId (UUID of a field on the target entity, from entities get <target-id>). Optionally referenceFolderKey when the target entity lives in a different folder.
FILE	Only name and type — the server auto-wires the internal attachment reference. Populate the value later with uip df files upload.
MULTILINE_MAX	Optional lengthLimit (UTF-16 byte budget, 1–131072; defaults to roughly 65,536 characters). Not filterable or sortable; records list/query return only a size marker for it — read full content with records get. Gated by the tenant's MultilineMax feature flag.

A RELATIONSHIP column on a record always stores the target record's Id (a UUID), regardless of which referenceFieldId configured the join — see records insert for how to write the value.

示例

uip df entities create Invoice --file ./invoice.entity.json

uip df entities create Invoice \
    --body '{"displayName":"Invoice","fields":[{"name":"amount","type":"DECIMAL"}]}'

# choice-set, relationship, file, and large-text fields
uip df entities create Expense \
    --body '{"displayName":"Expense","fields":[{"name":"category","type":"CHOICE_SET_SINGLE","choiceSetId":"c1d2e3f4-0000-0000-0000-000000000001","isRequired":true},{"name":"submitter","type":"RELATIONSHIP","referenceEntityId":"a1b2c3d4-0000-0000-0000-000000000010","referenceFieldId":"f1000000-0000-0000-0000-000000000100","isRequired":true},{"name":"receipt","type":"FILE"},{"name":"notes","type":"MULTILINE_MAX"}]}'

数据形状（--输出 json）

{
  "Code": "EntityCreated",
  "Data": { "ID": "a1b2c3d4-0000-0000-0000-000000000001" }
}

uip df 实体更新

Update an entity's metadata or schema. The body accepts addFields, updateFields, removeFields, displayName, description, and isAnalyticsEnabled/isRbacEnabled. The entity name itself is immutable — it cannot be included in the update body.

参数

名称	必填	用途
<id>	是	实体 ID (UUID)。

选项

短	长	值	默认	描述
-f	--file	路径	—	包含更新选项的 JSON 文件的路径。
—	--body	JSON	—	内联 JSON 更新选项。
-y	--yes	标记	—	Required when removeFields is non-empty — acknowledges the field deletion is irreversible.
—	--reason	text	—	Required when removeFields is non-empty — echoed back in the response so the caller can log it.
—	--folder-key	键值	—	Folder key (GUID) of the folder containing the entity, for folder-scoped entities.

• addFields — array of new fields, flat write shape (name + type, plus type-specific extras — see the create section above). A field object copied from entities get is also accepted and normalized.
• updateFields — array keyed by field id (from entities get), with the metadata properties being changed (for example displayName, description, isRequired, isRbacEnabled, isEncrypted, isHiddenField, defaultValue, constraints). Do not paste a full copied field object here — pass id plus only the flat properties being changed. updateFields cannot change a field's type or its isUnique setting.
• removeFields — array of {"name": "<fieldName>"} objects, identified by name, not id. Requires -y/--yes and --reason "<text>" — the operation deletes the field's stored values and cannot be undone.
• Updating entity metadata (description, isRbacEnabled, isAnalyticsEnabled) requires displayName to also be present in the same body, even if it's unchanged — fetch the current displayName with entities get first if you don't already have it.

示例

# Add a field
uip df entities update a1b2c3d4-0000-0000-0000-000000000001 \
    --body '{"addFields":[{"name":"note","type":"STRING","lengthLimit":200}]}'

# Rename an existing field's display name
uip df entities update a1b2c3d4-0000-0000-0000-000000000001 \
    --body '{"updateFields":[{"id":"f1000000-0000-0000-0000-000000000002","displayName":"Amount (USD)","isRequired":true}]}'

# Remove a field — destructive, requires --yes and --reason
uip df entities update a1b2c3d4-0000-0000-0000-000000000001 \
    --body '{"removeFields":[{"name":"oldColumn"}]}' \
    --yes --reason "quarterly cleanup"

数据形状（--输出 json）

{
  "Code": "EntityUpdated",
  "Data": { "ID": "a1b2c3d4-0000-0000-0000-000000000001" }
}

When the update includes removeFields, the response also echoes what was removed:

{
  "Code": "EntityUpdated",
  "Data": {
    "ID": "a1b2c3d4-0000-0000-0000-000000000001",
    "RemovedFields": ["oldColumn"],
    "Reason": "quarterly cleanup"
  }
}

uip df entities delete

Delete an entity outright. This is irreversible and removes the entity's schema along with all its records.

参数

名称	必填	用途
<id>	是	实体 ID (UUID)。

选项

短	长	值	默认	描述
-y	--yes	标记	—	Required. Acknowledges this is an irreversible operation.
—	--reason	text	—	Required. Reason for the deletion — echoed back in the response so the caller can log it.
—	--folder-key	键值	—	Folder key (GUID) of the folder containing the entity, for folder-scoped entities.

示例

uip df entities delete a1b2c3d4-0000-0000-0000-000000000001 \
    --yes --reason "test entity cleanup"

数据形状（--输出 json）

{
  "Code": "EntityDeleted",
  "Data": {
    "Id": "a1b2c3d4-0000-0000-0000-000000000001",
    "Reason": "test entity cleanup"
  }
}

相关内容

• uip df records — 管理这些实体拥有的行。
• uip df files — 记录上的文件附件。
• uip df choice-sets — the choice sets referenced by CHOICE_SET_SINGLE/CHOICE_SET_MULTIPLE fields.
• uip vss generate — 从 Data Fabric 架构导出文件生成 TypeScript 类型。

另请参阅

• Data Fabric 工具概述
• 全局选项
• 退出代码