uip df 记录

“uip df 记录”的语法和选项，用于管理 Data Fabric 实体中的行，包括单记录和批量操作。

uip df records 管理 Data Fabric 实体保存的行。Verbs 涵盖读取（list、get、query）、写入（insert、update、import、delete）和从 CSV 批量导入。单记录动词返回受影响的记录；批处理动词返回成功/失败计数，并在部分失败时以非零值退出。list 和 query 支持基于光标的分页。

大纲

uip df records list <id> [-l <n>] [-o <n> | --cursor <cursor>] [--folder-key <key>]
uip df records get <id> <key> [--folder-key <key>]
uip df records insert <id> (-f <path> | --body <json>) [--folder-key <key>]
uip df records update <id> (-f <path> | --body <json>) [--folder-key <key>]
uip df records query <id> (-f <path> | --body <json>) [-l <n>] [-o <n> | --cursor <cursor>] [--folder-key <key>]
uip df records import <id> -f <csv-path> [--folder-key <key>]
uip df records delete <id> <key...> -y --reason <text> [--folder-key <key>]

每个动词还接受 --folder-key <key>（文件夹 GUID，适用于属于文件夹作用域实体的记录）。

动词

动词	用途
list	列出实体中的记录，使用基于光标的分页。
get	按 ID 获取单个记录。
insert	插入一个记录（对象）或多个记录（数组）。
update	更新一个记录（对象）或多个记录（数组）；每个项目都必须包含Id 。
query	使用 JSON 查询正文对记录进行筛选、排序、聚合和项目记录。
import	从 CSV 文件批量导入记录。
delete	按 ID 删除一条或多条记录（具有破坏性，需要 -y/--reason）。

uip df 记录列表

列出实体中的记录。支持基于光标的分页。

参数

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

选项

短	长	值	默认	描述
-l	--limit	数字	50	每页要返回的记录数。
-o	--offset	数字	—	从包含此记录索引的页面开始（向下舍入到页面边界）。与--cursor互斥。
—	--cursor	光标	—	上一个响应的 nextCursor.value 中的分页光标值。与 --offset 互斥。
—	--folder-key	键值	—	对于文件夹范围内的实体，包含实体的文件夹的文件夹密钥 (GUID)。

示例

uip df records list a1b2c3d4-0000-0000-0000-000000000001 --limit 2

# Continue paging — pass the string from the previous response's Data.nextCursor.value
uip df records list a1b2c3d4-0000-0000-0000-000000000001 \
    --cursor "eyJwYWdlIjoyfQ=="

# Just the IDs
uip df records list a1b2c3d4-0000-0000-0000-000000000001 \
    --output-filter 'Data.items[].Id'

数据形状（--输出 json）

{
  "Code": "RecordList",
  "Data": {
    "items": [
      {
        "Id": "b2c3d4e5-0000-0000-0000-000000000001",
        "amount": 1500,
        "notes": "HasValue=true Length=20000"
      },
      { "Id": "b2c3d4e5-0000-0000-0000-000000000002", "amount": 2750, "notes": null }
    ],
    "totalCount": 2,
    "hasNextPage": false
  }
}

重要提示：

分页信封键（ items 、 totalCount 、 hasNextPage和— nextCursor 、 previousCursor 、 currentPage 、 totalPages ）使用驼峰式命名法，这与记录行自己的Id不同字段。当 hasNextPage 为 true 时，将 Data.nextCursor.value（字符串）传递回 --cursor，而非整个 nextCursor 对象。

MULTILINE_MAX 上的 list 字段仅返回大小标记 ("HasValue=true Length=20000"，如果为空，则返回 null)，而不是全文 — 阅读下面带有 get 的完整值。

获取 uip df 记录

按 ID 获取单个记录。

参数

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

选项

短	长	值	默认	描述
—	--folder-key	键值	—	对于文件夹范围内的实体，包含实体的文件夹的文件夹密钥 (GUID)。

示例

uip df records get a1b2c3d4-0000-0000-0000-000000000001 \
    b2c3d4e5-0000-0000-0000-000000000001

数据形状（--输出 json）

{
  "Code": "RecordDetails",
  "Data": {
    "Id": "b2c3d4e5-0000-0000-0000-000000000001",
    "amount": 1500,
    "status": "Paid"
  }
}

与 list 不同，此处的 MULTILINE_MAX 字段会返回其完整值，而不是大小标记。

uip df 记录插入

插入一条或多条记录。输入可以是单个 JSON 对象，也可以是对象数组。

参数

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

选项

短	长	值	默认	描述
-f	--file	路径	—	包含记录数据（对象或对象数组）的 JSON 文件的路径。
—	--body	JSON	—	内联 JSON 记录数据（使用 - 从 标准输入 读取）。
—	--folder-key	键值	—	对于文件夹范围内的实体，包含实体的文件夹的文件夹密钥 (GUID)。

特殊类型的字段值：

• CHOICE_SET_SINGLE — 选项值的numberId （整数，而不是名称字符串）— 使用df choice-sets list-values <id>进行查找。
• CHOICE_SET_MULTIPLE — 由numberId整数组成的数组。
• RELATIONSHIP — 始终是目标记录的Id (UUID)，无论架构使用哪个referenceFieldId用于联接。 referenceFieldId仅配置联接，不是存储的值。
• FILE — 无法通过insert / update设置；系统会从实体的架构中自动检测到该字段；如果有效负载中存在该字段，则系统会拒绝该字段。然后使用uip df files upload填充它。

示例

# Single record
uip df records insert a1b2c3d4-0000-0000-0000-000000000001 \
    --body '{"amount":1500,"status":"New"}'

# Choice-set and relationship fields
uip df records insert a1b2c3d4-0000-0000-0000-000000000004 \
    --body '{"category":0,"tags":[1,3],"submitter":"e1f2a3b4-0000-0000-0000-000000000001","amount":250}'

# Batch from file
uip df records insert a1b2c3d4-0000-0000-0000-000000000001 \
    --file ./invoices.json

数据形状（--输出 json）

单条记录插入返回Code: "RecordInserted"和创建的记录。批量插入返回Code: "RecordsBatchInserted" ：

{
  "Code": "RecordsBatchInserted",
  "Data": {
    "SuccessCount": 1,
    "FailureCount": 0,
    "SuccessRecords": [ { "Id": "b2c3d4e5-0000-0000-0000-000000000010" } ],
    "FailureRecords": []
  }
}

如果批处理中的任何记录失败，该命令将非零退出，同时仍会发出完整结果。

uip df 记录更新

更新一条或多条记录。每条记录都必须包含一个Id （或id ）字段。

参数

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

选项

短	长	值	默认	描述
-f	--file	路径	—	包含记录数据的 JSON 文件的路径（必须包含Id字段）。
—	--body	JSON	—	内联 JSON 记录数据（必须包含 Id 字段；使用 - 从标准输入读取）。
—	--folder-key	键值	—	对于文件夹范围内的实体，包含实体的文件夹的文件夹密钥 (GUID)。

示例

uip df records update a1b2c3d4-0000-0000-0000-000000000001 \
    --body '{"Id":"b2c3d4e5-0000-0000-0000-000000000001","status":"Paid"}'

数据形状（--输出 json）

单个更新发出Code: "RecordUpdated" ；批量更新发出形状与Code: "RecordsBatchUpdated"相同的RecordsBatchInserted 。任何写入之前缺少Id字段，都会失败并显示Failure 。

uip df 记录查询

通过筛选、排序、聚合和字段选择来查询记录。支持基于光标的分页。正文是 JSON 对象，具有可选键 filterGroup、sortOptions、selectedFields、aggregates 和 groupBy。

参数

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

选项

短	长	值	默认	描述
-f	--file	路径	—	包含查询选项的 JSON 文件路径。
—	--body	JSON	—	内联 JSON 查询选项（使用 - 从 标准输入 读取）。
-l	--limit	数字	50	页面大小。
-o	--offset	数字	—	从包含此记录索引的页面开始。与--cursor互斥。
—	--cursor	光标	—	上一个响应的 nextCursor.value 中的分页光标值。
—	--folder-key	键值	—	对于文件夹范围内的实体，包含实体的文件夹的文件夹密钥 (GUID)。

查询正文键

• filterGroup — { "logicalOperator": "AND" | "OR" | 0 | 1, "queryFilters": [...], "filterGroups": [...] } 。logicalOperator 接受字符串形式（不区分大小写）或整数形式（0 = AND，1 = OR）； filterGroups 会针对复合条件嵌套相同形状的组。

• queryFilters条目为{ "fieldName": "<field>", "operator": "<op>", "value": ... } （对于in / not in ，为"valueList": [...] ）。fieldName 必须以字母开头，并且仅包含字母、数字、下划线和点。

  重要提示：

  支持的运算符如下：=、!=、>、<、>=、<=、contains、not contains、startswith、endswith、in、not in。没有eq 、 == 、 Equals 、 like 、 BETWEEN或正则表达式运算符 — 服务器拒绝此集合之外的任何内容。在同一 >= 组中将“之间”编写为 <= + queryFilters。

• sortOptions — 属于{ "fieldName": "<field>", "isDescending": true | false }的数组。

• selectedFields — 要项目的字段名称数组。

• aggregates — 最多包含 5 个{ "function": "COUNT" | "SUM" | "AVG" | "MIN" | "MAX", "field": "<field>", "alias": "<name>" }对象的数组。alias 是可选的，如果给定，则必须以字母开头（仅限字母、数字和下划线，且不超过 128 个字符）。

• groupBy — 最多包含 5 个字段名称的数组，这是对聚合进行分组的依据。

示例

# Filter by status
uip df records query a1b2c3d4-0000-0000-0000-000000000001 \
    --body '{"filterGroup":{"logicalOperator":0,"queryFilters":[{"fieldName":"status","operator":"=","value":"Paid"}]}}'

# Sort newest first, project two fields
uip df records query a1b2c3d4-0000-0000-0000-000000000001 \
    --body '{"sortOptions":[{"fieldName":"createdAt","isDescending":true}],"selectedFields":["Id","amount"]}'

# Aggregate — COUNT grouped by a field
uip df records query a1b2c3d4-0000-0000-0000-000000000001 \
    --body '{"aggregates":[{"function":"COUNT","field":"Id","alias":"total"}],"groupBy":["status"]}'

数据形状（--输出 json）

{
  "Code": "RecordQuery",
  "Data": {
    "items": [ { "Id": "b2c3d4e5-0000-0000-0000-000000000001", "status": "Paid" } ],
    "totalCount": 1,
    "hasNextPage": false
  }
}

聚合查询的行包含 groupBy 字段值加上每个聚合的 alias，而不是完整的记录字段：

{
  "Code": "RecordQuery",
  "Data": {
    "items": [
      { "status": "Paid", "total": 12 },
      { "status": "Pending", "total": 3 }
    ]
  }
}

uip df 记录导入

从 CSV 文件批量导入记录。

参数

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

选项

短	长	值	默认	描述
-f	--file	路径	必填	要导入的 CSV 文件的路径。
—	--folder-key	键值	—	对于文件夹范围内的实体，包含实体的文件夹的文件夹密钥 (GUID)。

示例

uip df records import a1b2c3d4-0000-0000-0000-000000000001 \
    --file ./invoices.csv

数据形状（--输出 json）

{
  "Code": "RecordsImported",
  "Data": {
    "InsertedRecords": 42,
    "TotalRecords": 42
  }
}

如果服务器记录行级错误，则响应还包含ErrorFileLink指向可下载的错误报告。

uip df 记录删除

按 ID 删除一条或多条记录。此操作无法撤销。

参数

名称	必填	用途
<id>	是	实体 ID (UUID)。
<key...>	是	要删除的一个或多个记录 ID。

选项

短	长	值	默认	描述
-y	--yes	标记	—	必需。确认这是一个不可逆的操作。
—	--reason	text	—	必需。删除原因 — 在响应中回显，以便调用者可以记录。
—	--folder-key	键值	—	对于文件夹范围内的实体，包含实体的文件夹的文件夹密钥 (GUID)。

示例

uip df records delete a1b2c3d4-0000-0000-0000-000000000001 \
    b2c3d4e5-0000-0000-0000-000000000001 \
    --yes --reason "test cleanup"

# Bulk delete
uip df records delete a1b2c3d4-0000-0000-0000-000000000001 \
    b2c3d4e5-0000-0000-0000-000000000001 \
    b2c3d4e5-0000-0000-0000-000000000002 \
    b2c3d4e5-0000-0000-0000-000000000003 \
    --yes --reason "test cleanup"

数据形状（--输出 json）

{
  "Code": "RecordsDeleted",
  "Data": {
    "SuccessCount": 1,
    "FailureCount": 0,
    "SuccessRecords": [ { "Id": "b2c3d4e5-0000-0000-0000-000000000001" } ],
    "FailureRecords": [],
    "Reason": "test cleanup"
  }
}

部分失败仍会发出完整响应，但会设置退出代码1 。

相关内容

• uip df entities — 首先发现实体 ID；在编写查询之前检查架构。
• uip df files — 管理此处记录中的文件附件。
• uip df choice-sets — 查找CHOICE_SET_SINGLE / CHOICE_SET_MULTIPLE字段的numberId值。

另请参阅

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