# 字段 (/docs/api/native/database/fields)



[指南 →](/docs/cloud/services/database/quickstart)

[基础地址与鉴权](/docs/api/native/database)

添加、更新和删除字段均返回完整 Table。字段 type 不可修改；link 的关联目标不可修改。json 的 schema 更新仅约束之后的写入。

新增带 default 的字段时，已有行一律用 default 回填（无论是否 required），行的 \_version 不变；不带 default 的新字段在已有行上为 null。在已有行的表上新增 required 字段时必须提供 default，没有 default 时返回 400 VALIDATION\_FAILED。把字段改为 required 时，若仍有行在该字段为空，返回 400 VALIDATION\_FAILED 并在 message 中给出空行数。空请求体、只含被忽略键或所有值都与当前相同的 PATCH 不修改 updated\_at 与 schema\_revision、不产生事件，直接返回当前对象。

datetime 的 default 可以是字符串 "now()"，插入时生成服务器当前 UTC 时间；读回字段定义仍是 "now()"。例如 `{"name":"created_at","type":"datetime","default":"now()"}`。string/json 的 "now()" 保持字面量；其他类型仍按原校验规则处理。新增字段回填已有行时也会求值。

## 添加字段 [#添加字段]

`POST /database/v1/databases/{database_id}/tables/{table}/fields`

| 参数 | 位置 | 说明 |
| --- | --- | --- |
| database_id | path | 库 ID。 |
| table | path | 表 ID 或名称。 |

### 请求体 [#请求体]

"string" / "integer" / "number" / "boolean" / "datetime"

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| name | string | 是 | 字段名；只保留 id；新字段不能以下划线开头。created_at、updated_at、version 可作为用户字段名；已有下划线字段照常使用，且优先于同名元数据。; ^(?!id$)[a-z][a-z0-9_]{0,62}$ |
| description | string | 否 | 描述 |
| required | boolean | 否 | 是否必填 |
| unique | boolean | 否 | 是否唯一 |
| indexed | boolean | 否 | 是否索引 |
| type | "string" / "integer" / "number" / "boolean" / "datetime" | 是 | 类型 |
| options | object | 否 | json：schema；link：linked_table_id 与 multiple |
| default | JSON | 否 | 省略插入值时的默认值；datetime 的 now() 在写入时取服务器时间，字段定义仍读回 now()。string/json 中为字面量。显式 null 不使用默认值。 |

"json"

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| name | string | 是 | 字段名；只保留 id；新字段不能以下划线开头。created_at、updated_at、version 可作为用户字段名；已有下划线字段照常使用，且优先于同名元数据。; ^(?!id$)[a-z][a-z0-9_]{0,62}$ |
| description | string | 否 | 描述 |
| required | boolean | 否 | 是否必填 |
| unique | boolean | 否 | 是否唯一 |
| indexed | boolean | 否 | 是否索引 |
| type | "json" | 是 | 类型 |
| options | object | 是 | json：schema；link：linked_table_id 与 multiple |
| default | JSON | 否 | 省略插入值时的默认值；datetime 的 now() 在写入时取服务器时间，字段定义仍读回 now()。string/json 中为字面量。显式 null 不使用默认值。 |

"link"

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| name | string | 是 | 字段名；只保留 id；新字段不能以下划线开头。created_at、updated_at、version 可作为用户字段名；已有下划线字段照常使用，且优先于同名元数据。; ^(?!id$)[a-z][a-z0-9_]{0,62}$ |
| description | string | 否 | 描述 |
| required | boolean | 否 | 是否必填 |
| unique | boolean | 否 | 是否唯一 |
| indexed | boolean | 否 | 是否索引 |
| type | "link" | 是 | 类型 |
| options | object | 是 | json：schema；link：linked_table_id 与 multiple |

返回: `Table`.

### 响应 [#响应]

#### HTTP 201 [#http-201]

Success

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Table identifier, prefixed tbl_. Stable across renames and accepted wherever a table path parameter takes an id or name. |
| name | string | Current table name, usable in the rows path; may change when the table is renamed. |
| description | string | null | Free-text note about the table, or null when none was set. |
| fields | array<object> | Field definitions of the table, in display order. Row values are keyed by each field's name. |
| fields[].id | string | Field identifier, prefixed fld_. Stable across renames; accepted wherever a field path parameter takes an id or name. |
| fields[].name | string | Current field name; rows are keyed by it in requests and responses. May change when the field is renamed. |
| fields[].description | string | null | Free-text note about the field, or null when none was set. |
| fields[].required | boolean | Whether every row must hold a non-null value for this field. |
| fields[].unique | boolean | Whether values must be distinct across rows; fixed at creation. A unique field is indexed, and a violation returns 409 UNIQUE_VIOLATION. |
| fields[].indexed | boolean | Whether an index is maintained for faster filters and ordering. Always false for json and link fields. |
| fields[].type | string | Scalar data type of the field; it cannot be changed after the field is created. / Type json: the value is any JSON document validated against options.schema. It cannot be changed after the field is created. / Type link: the value is the id of a row in another table (an array of ids when options.multiple is true). It cannot be changed after the field is created. |
| fields[].options | object | Scalar fields take no options; always an empty object. / Settings of a json field. schema is required. / Settings of a link field. Both linked_table_id and multiple are required. |
| fields[].default | any | Default JSON value for omitted insert fields; must match the field type and JSON schema. A datetime default of "now()" evaluates to server time on insertion and reads back as "now()" in the field definition. For string and json fields it is a literal string. Explicit null remains null. Link fields do not support defaults. |
| schema_revision | integer | Counter that starts at 1 and increases by one each time the table's name, description or fields change; use it to detect schema changes. |
| created_at | string | Time the table was created, as an RFC 3339 UTC timestamp. |
| updated_at | string | Time of the last schema change to the table, as an RFC 3339 UTC timestamp. |
| row_count | integer | Number of rows currently stored. Returned only by databaseGetTable; absent from list, create and field responses. |

```bash
curl -X POST "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}/tables/tasks/fields" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"priority","type":"integer"}'
```

响应示例 — HTTP 201

```json
{
  "id": "tbl_2b3431c772754599",
  "name": "tasks",
  "description": "Tasks for an agent",
  "schema_revision": 3,
  "created_at": "2026-10-11T17:41:44.246Z",
  "updated_at": "2026-10-11T17:41:45.420Z",
  "fields": [
    {
      "id": "fld_bc71f7c6a1a848d2",
      "name": "title",
      "type": "string",
      "description": null,
      "required": true,
      "unique": true,
      "indexed": true
    },
    {
      "id": "fld_c7879883dfe04ca0",
      "name": "done",
      "type": "boolean",
      "description": null,
      "required": false,
      "unique": false,
      "indexed": true
    },
    {
      "id": "fld_4c3e63869e35458c",
      "name": "priority",
      "type": "integer",
      "description": null,
      "required": false,
      "unique": false,
      "indexed": true
    }
  ]
}
```

## 更新字段 [#更新字段]

`PATCH /database/v1/databases/{database_id}/tables/{table}/fields/{field}`

| 参数 | 位置 | 说明 |
| --- | --- | --- |
| database_id | path | 库 ID。 |
| table | path | 表 ID 或名称。 |
| field | path | 字段 ID 或名称。 |

### 请求体 [#请求体-1]

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| name | string | 否 | 名称 |
| description | string / null | 否 | 描述 |
| required | boolean | 否 | 是否必填 |
| indexed | boolean | 否 | 是否索引 |
| options | object | 否 | json：schema；link：linked_table_id 与 multiple |
| default | JSON | 否 | 省略插入值时的默认值；datetime 的 now() 在写入时取服务器时间，字段定义仍读回 now()。string/json 中为字面量。显式 null 不使用默认值。 |

返回: `Table`.

### 响应 [#响应-1]

#### HTTP 200 [#http-200]

Success

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Table identifier, prefixed tbl_. Stable across renames and accepted wherever a table path parameter takes an id or name. |
| name | string | Current table name, usable in the rows path; may change when the table is renamed. |
| description | string | null | Free-text note about the table, or null when none was set. |
| fields | array<object> | Field definitions of the table, in display order. Row values are keyed by each field's name. |
| fields[].id | string | Field identifier, prefixed fld_. Stable across renames; accepted wherever a field path parameter takes an id or name. |
| fields[].name | string | Current field name; rows are keyed by it in requests and responses. May change when the field is renamed. |
| fields[].description | string | null | Free-text note about the field, or null when none was set. |
| fields[].required | boolean | Whether every row must hold a non-null value for this field. |
| fields[].unique | boolean | Whether values must be distinct across rows; fixed at creation. A unique field is indexed, and a violation returns 409 UNIQUE_VIOLATION. |
| fields[].indexed | boolean | Whether an index is maintained for faster filters and ordering. Always false for json and link fields. |
| fields[].type | string | Scalar data type of the field; it cannot be changed after the field is created. / Type json: the value is any JSON document validated against options.schema. It cannot be changed after the field is created. / Type link: the value is the id of a row in another table (an array of ids when options.multiple is true). It cannot be changed after the field is created. |
| fields[].options | object | Scalar fields take no options; always an empty object. / Settings of a json field. schema is required. / Settings of a link field. Both linked_table_id and multiple are required. |
| fields[].default | any | Default JSON value for omitted insert fields; must match the field type and JSON schema. A datetime default of "now()" evaluates to server time on insertion and reads back as "now()" in the field definition. For string and json fields it is a literal string. Explicit null remains null. Link fields do not support defaults. |
| schema_revision | integer | Counter that starts at 1 and increases by one each time the table's name, description or fields change; use it to detect schema changes. |
| created_at | string | Time the table was created, as an RFC 3339 UTC timestamp. |
| updated_at | string | Time of the last schema change to the table, as an RFC 3339 UTC timestamp. |
| row_count | integer | Number of rows currently stored. Returned only by databaseGetTable; absent from list, create and field responses. |

```bash
curl -X PATCH "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}/tables/tasks/fields/priority" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description":"Task priority"}'
```

响应示例 — HTTP 200

```json
{
  "id": "tbl_2b3431c772754599",
  "name": "tasks",
  "description": "Tasks for an agent",
  "schema_revision": 4,
  "created_at": "2026-10-11T17:41:44.246Z",
  "updated_at": "2026-10-11T17:41:46.276Z",
  "fields": [
    {
      "id": "fld_bc71f7c6a1a848d2",
      "name": "title",
      "type": "string",
      "description": null,
      "required": true,
      "unique": true,
      "indexed": true
    },
    {
      "id": "fld_c7879883dfe04ca0",
      "name": "done",
      "type": "boolean",
      "description": null,
      "required": false,
      "unique": false,
      "indexed": true
    },
    {
      "id": "fld_4c3e63869e35458c",
      "name": "priority",
      "type": "integer",
      "description": "Task priority",
      "required": false,
      "unique": false,
      "indexed": true
    }
  ]
}
```

## 删除字段 [#删除字段]

`DELETE /database/v1/databases/{database_id}/tables/{table}/fields/{field}`

| 参数 | 位置 | 说明 |
| --- | --- | --- |
| database_id | path | 库 ID。 |
| table | path | 表 ID 或名称。 |
| field | path | 字段 ID 或名称。 |

返回: `Table`.

### 响应 [#响应-2]

#### HTTP 200 [#http-200-1]

Success

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Table identifier, prefixed tbl_. Stable across renames and accepted wherever a table path parameter takes an id or name. |
| name | string | Current table name, usable in the rows path; may change when the table is renamed. |
| description | string | null | Free-text note about the table, or null when none was set. |
| fields | array<object> | Field definitions of the table, in display order. Row values are keyed by each field's name. |
| fields[].id | string | Field identifier, prefixed fld_. Stable across renames; accepted wherever a field path parameter takes an id or name. |
| fields[].name | string | Current field name; rows are keyed by it in requests and responses. May change when the field is renamed. |
| fields[].description | string | null | Free-text note about the field, or null when none was set. |
| fields[].required | boolean | Whether every row must hold a non-null value for this field. |
| fields[].unique | boolean | Whether values must be distinct across rows; fixed at creation. A unique field is indexed, and a violation returns 409 UNIQUE_VIOLATION. |
| fields[].indexed | boolean | Whether an index is maintained for faster filters and ordering. Always false for json and link fields. |
| fields[].type | string | Scalar data type of the field; it cannot be changed after the field is created. / Type json: the value is any JSON document validated against options.schema. It cannot be changed after the field is created. / Type link: the value is the id of a row in another table (an array of ids when options.multiple is true). It cannot be changed after the field is created. |
| fields[].options | object | Scalar fields take no options; always an empty object. / Settings of a json field. schema is required. / Settings of a link field. Both linked_table_id and multiple are required. |
| fields[].default | any | Default JSON value for omitted insert fields; must match the field type and JSON schema. A datetime default of "now()" evaluates to server time on insertion and reads back as "now()" in the field definition. For string and json fields it is a literal string. Explicit null remains null. Link fields do not support defaults. |
| schema_revision | integer | Counter that starts at 1 and increases by one each time the table's name, description or fields change; use it to detect schema changes. |
| created_at | string | Time the table was created, as an RFC 3339 UTC timestamp. |
| updated_at | string | Time of the last schema change to the table, as an RFC 3339 UTC timestamp. |
| row_count | integer | Number of rows currently stored. Returned only by databaseGetTable; absent from list, create and field responses. |

```bash
curl -X DELETE "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}/tables/tasks/fields/priority" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

响应示例 — HTTP 200

```json
{
  "id": "tbl_2b3431c772754599",
  "name": "tasks",
  "description": "Tasks for an agent",
  "schema_revision": 5,
  "created_at": "2026-10-11T17:41:44.246Z",
  "updated_at": "2026-10-11T17:41:47.136Z",
  "fields": [
    {
      "id": "fld_bc71f7c6a1a848d2",
      "name": "title",
      "type": "string",
      "description": null,
      "required": true,
      "unique": true,
      "indexed": true
    },
    {
      "id": "fld_c7879883dfe04ca0",
      "name": "done",
      "type": "boolean",
      "description": null,
      "required": false,
      "unique": false,
      "indexed": true
    }
  ]
}
```

## Field [#field]

"string" / "integer" / "number" / "boolean" / "datetime"

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | string | 是 | 资源 ID |
| name | string | 是 | 名称 |
| description | string / null | 是 | 描述 |
| required | boolean | 是 | 是否必填 |
| unique | boolean | 是 | 是否唯一 |
| indexed | boolean | 是 | 是否索引 |
| type | "string" / "integer" / "number" / "boolean" / "datetime" | 是 | 类型 |
| options | object | 否 | json：schema；link：linked_table_id 与 multiple |
| default | JSON | 否 | 省略插入值时的默认值；datetime 的 now() 在写入时取服务器时间，字段定义仍读回 now()。string/json 中为字面量。显式 null 不使用默认值。 |

"json"

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | string | 是 | 资源 ID |
| name | string | 是 | 名称 |
| description | string / null | 是 | 描述 |
| required | boolean | 是 | 是否必填 |
| unique | boolean | 是 | 是否唯一 |
| indexed | boolean | 是 | 是否索引 |
| type | "json" | 是 | 类型 |
| options | object | 是 | json：schema；link：linked_table_id 与 multiple |
| default | JSON | 否 | 省略插入值时的默认值；datetime 的 now() 在写入时取服务器时间，字段定义仍读回 now()。string/json 中为字面量。显式 null 不使用默认值。 |

"link"

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | string | 是 | 资源 ID |
| name | string | 是 | 名称 |
| description | string / null | 是 | 描述 |
| required | boolean | 是 | 是否必填 |
| unique | boolean | 是 | 是否唯一 |
| indexed | boolean | 是 | 是否索引 |
| type | "link" | 是 | 类型 |
| options | object | 是 | json：schema；link：linked_table_id 与 multiple |

## NewField [#newfield]

"string" / "integer" / "number" / "boolean" / "datetime"

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| name | string | 是 | 字段名；只保留 id；新字段不能以下划线开头。created_at、updated_at、version 可作为用户字段名；已有下划线字段照常使用，且优先于同名元数据。; ^(?!id$)[a-z][a-z0-9_]{0,62}$ |
| description | string | 否 | 描述 |
| required | boolean | 否 | 是否必填 |
| unique | boolean | 否 | 是否唯一 |
| indexed | boolean | 否 | 是否索引 |
| type | "string" / "integer" / "number" / "boolean" / "datetime" | 是 | 类型 |
| options | object | 否 | json：schema；link：linked_table_id 与 multiple |
| default | JSON | 否 | 省略插入值时的默认值；datetime 的 now() 在写入时取服务器时间，字段定义仍读回 now()。string/json 中为字面量。显式 null 不使用默认值。 |

"json"

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| name | string | 是 | 字段名；只保留 id；新字段不能以下划线开头。created_at、updated_at、version 可作为用户字段名；已有下划线字段照常使用，且优先于同名元数据。; ^(?!id$)[a-z][a-z0-9_]{0,62}$ |
| description | string | 否 | 描述 |
| required | boolean | 否 | 是否必填 |
| unique | boolean | 否 | 是否唯一 |
| indexed | boolean | 否 | 是否索引 |
| type | "json" | 是 | 类型 |
| options | object | 是 | json：schema；link：linked_table_id 与 multiple |
| default | JSON | 否 | 省略插入值时的默认值；datetime 的 now() 在写入时取服务器时间，字段定义仍读回 now()。string/json 中为字面量。显式 null 不使用默认值。 |

"link"

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| name | string | 是 | 字段名；只保留 id；新字段不能以下划线开头。created_at、updated_at、version 可作为用户字段名；已有下划线字段照常使用，且优先于同名元数据。; ^(?!id$)[a-z][a-z0-9_]{0,62}$ |
| description | string | 否 | 描述 |
| required | boolean | 否 | 是否必填 |
| unique | boolean | 否 | 是否唯一 |
| indexed | boolean | 否 | 是否索引 |
| type | "link" | 是 | 类型 |
| options | object | 是 | json：schema；link：linked_table_id 与 multiple |