字段

添加、更新和删除字段均返回完整 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

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.

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

{
  "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 或名称。

请求体

字段	类型	必填	说明
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.

响应

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.

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

{
  "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.

响应

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.

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

响应示例 — HTTP 200

{
  "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

"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

"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

字段

本页内容