> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coze.cn/llms.txt
> Use this file to discover all available pages before exploring further.

创建扣子数据库。
扣子编程提供了类似传统软件开发中数据库的功能，允许用户以表格结构存储数据。这种数据存储方式非常适合组织和管理结构化数据，例如客户信息、产品列表、订单记录等。
你可以根据自己的业务需求，创建数据库以及数据表，定义字段和数据类型，并设置相应的规则，以确保数据的安全性和完整性。
## 基础信息 {#基础信息}
<!-- @cols-width: 180,680 -->
| | | \
|**请求方式** |POST |
|---|---|
| | | \
|**请求地址** |```Plain Text |\
| |https://api.coze.cn/v1/databases |\
| |``` |\
| | |
| | | \
|**权限** |:::tip 说明 |\
| |* 如需在工作空间资源库中创建扣子数据库，需开通`Workspace.createDatabase`权限。 |\
| |* 如需在低代码应用中创建扣子数据库，需同时开通`Workspace.createDatabase`和`Project.createDatabase`权限。详细信息参考[鉴权方式](https://docs.coze.cn/developer_guides/authentication)。 |\
| |::: |
| | | \
|**接口说明** |在指定工作空间下创建一个新的扣子数据库，支持定义字段、索引、读写模式等。 |

## 请求参数 {#请求参数}
### Header {#Header}
<!-- @cols-width: 144,165,551 -->
| | | | \
|**参数** |**取值** |**说明** |
|---|---|---|
| | | | \
|Authorization |Bearer *$Access_Token* |用于验证客户端身份的访问令牌。你可以在扣子编程中生成访问令牌，详细信息，参考[准备工作](https://www.coze.cn/docs/developer_guides/preparation)。 |
| | | | \
|Content-Type |application/json |请求正文的方式。 |

### Body {#Body}
<!-- @cols-width: 203,120,85,163,274 -->
| | | | | | \
|**参数** |**类型** |**是否必选** |**示例** |**说明** |
|---|---|---|---|---|
| | | | | | \
|workspace_id |String |必选 |749820488328041**** |工作空间 ID。你可以通过调用[查看工作空间列表](https://docs.coze.cn/developer_guides/list_workspace)接口获取。 |
| | | | | | \
|app_id |String |可选 |761257394935226**** |低代码应用 ID。进入低代码应用编排页面，页面 URL 中 `project-ide` 参数后的数字即为应用 ID。例如`https://www.coze.cn/space/749820488328041****/project-ide/761257394935226****`，应用 ID 为 `761257394935226****`。 |\
| | | | |:::tip 说明 |\
| | | | |如果指定`app_id`，将在对应低代码应用内创建扣子数据库。如果未指定`app_id`，默认在 `workspace_id` 对应的工作空间下的资源库中创建扣子数据库。 |\
| | | | |::: |
| | | | | | \
|table_name |String |必选 |user_info |数据表名称。 |
| | | | | | \
|table_desc |String |可选 |存储用户基本信息的数据库 |数据表描述。 |
| | | | | | \
|fields |Array of [OpenFieldItem](#openfielditem) |必选 |[{"name": "user_id", "desc": "姓名", "type": "string", "is_required": true},{"name":"level","desc":"等级","type":"integer","is_required":true}] |字段信息列表。 |
| | | | | | \
|rw_mode |String |必选 |unlimited_read_write |设置数据表查询模式。 |\
| | | | | |\
| | | | |* `limited_read_write`（单用户模式）：开发者和用户都可以添加记录，但仅能读/修改/删除自己创建的来自同渠道的数据。 |\
| | | | |* `unlimited_read_write`（多用户模式）：开发者和用户都可读/写/修改/删除表中来自同渠道的任何数据，由业务逻辑控制读写权限。 |
| | | | | | \
|indexs |Array of [OpenIndexItem](#openindexitem) |可选 |[{"index_name": "idx_level", "field_names": ["level"]}] |索引列表（目前只支持单字段的索引）。 |
| | | | | | \
|connector_rw_config |Array of [OpenConnectorInfo](#openconnectorinfo) |可选 |[{"connector_id":"10000011","connector_rw_mode":"online"}] |为渠道（通过 `connector_id` 标识）配置读写模式，实现对数据访问规则的精细化管控。 |
| | | | | | \
|connector_read_mode |String |可选 |independent_connector |配置渠道模式。 |\
| | | | | |\
| | | | |* independent_connector（渠道隔离，默认值）：各个不同渠道的数据相互隔离，对应渠道仅可访问对应渠道的数据。 |\
| | | | |* shared_coze_connectors（扣子站内渠道共享，其他渠道隔离）：扣子编程调试台、商店和模板渠道的测试数据共享；扣子商店和模板渠道的线上数据共享。其他不同渠道之间数据相互隔离，对应渠道仅可访问对应渠道的数据。 |\
| | | | |* shared_all_connectors（渠道共享）：不同渠道之间的数据共享，支持跨渠道访问数据。 |
| | | | | | \
|icon_file_id |String |可选 |761258606549234**** |数据库图标文件 ID。 |\
| | | | | |\
| | | | |* 未指定文件 ID 时，扣子编程默认为数据库指定一个头像。 |\
| | | | |* 如需使用自定义图标文件，应先通过[上传文件](https://docs.coze.cn/developer_guides/upload_files)接口上传本地文件，从接口响应中获取文件 ID。 |

### OpenFieldItem {#openfielditem}
<!-- @cols-width: 170,121,86,88,369 -->
| | | | | | \
|**参数** |**类型** |**是否必选** |**示例** |**说明** |
|---|---|---|---|---|
| | | | | | \
|type |String |可选 |string |存储字段的数据类型，大语言模型会按照选择的数据类型对用户输入的内容进行处理和保存。目前支持的数据类型包括 String、Integer、Time、Number、Boolean。 |
| | | | | | \
|is_required |Boolean |可选 |true |存储字段是否为必要字段。枚举值如下： |\
| | | | | |\
| | | | |* `true`：必要字段。 |\
| | | | |* `false`：非必要字段。 |
| | | | | | \
|is_system_field |Boolean |可选 |false |标识字段是否为系统字段。系统默认字段为 `true`，用户自定义字段均为 `false`。 |
| | | | | | \
|is_primary_key |Boolean |可选 |false |标识字段是否为表主键。仅系统生成的 `id` 字段为 `true`，用户自定义字段均为 `false`。 |
| | | | | | \
|name |String |可选 |name |存储字段名称，只能包含小写字母、数字、下划线（`_`）、必须以英文字母开头，最多 64 字符，不支持使用数据库关键词或保留字作为字段名称。 |\
| | | | |扣子编程关键词和保留字列表，请参考[扣子数据库关键词和保留字有哪些？](https://docs.coze.cn/guides/database_faq#22ad0019)。 |
| | | | | | \
|desc |String |可选 |用户姓名 |存储字段的补充说明，可以是对存储字段的自然语言描述、示例数据，也可以是格式说明等。 |

### OpenIndexItem {#openindexitem}
<!-- @cols-width: 132,122,87,165,341 -->
| | | | | | \
|**参数** |**类型** |**是否必选** |**示例** |**说明** |
|---|---|---|---|---|
| | | | | | \
|index_name |String |可选 |idx_level |索引的名称，需确保唯一性。如果未传入该字段，服务端将按照一定规则自动生成。 |
| | | | | | \
|field_names |Array of String |可选 |["level"] |当前仅支持单字段索引，即数组中只能包含一个字段名。 |
| | | | | | \
|comment |String |可选 |等级 |索引描述。 |

### OpenConnectorInfo {#openconnectorinfo}
<!-- @cols-width: 188,120,86,163,289 -->
| | | | | | \
|**参数** |**类型** |**是否必选** |**示例** |**说明** |
|---|---|---|---|---|
| | | | | | \
|connector_id |String |可选 |10000011 |渠道 ID。扣子编程的渠道 ID 包括： |\
| | | | | |\
| | | | |* 1024（默认值）：API 渠道。 |\
| | | | |* 999：Chat SDK。 |\
| | | | |* 10000122：扣子商店。 |\
| | | | |* 10000113：微信客服。 |\
| | | | |* 10000120：微信服务号。 |\
| | | | |* 10000121：微信订阅号。 |\
| | | | |* 10000126：抖音小程序。 |\
| | | | |* 10000127：微信小程序。 |\
| | | | |* 10000011：飞书。 |\
| | | | |* 998：WebSDK。 |\
| | | | |* 自定义渠道 ID。自定义渠道 ID 的获取方式如下：在扣子编程左下角单击头像，在**账号设置** > **发布渠道** > **企业自定义渠道管理**页面查看渠道 ID。 |
| | | | | | \
|connector_rw_mode |String |可选 |online |渠道读写配置。取值如下： |\
| | | | | |\
| | | | |* `draft`：读写测试数据。 |\
| | | | |* `online`：读写线上数据。 |\
| | | | | |\
| | | | |:::tip 说明 |\
| | | | |扣子站内渠道（编程调试台、商店、模板渠道）默认`draft`，其他渠道默认`online`。 |\
| | | | |::: |


## 返回参数 {#返回参数}
<!-- @cols-width: 148,147,165,400 -->
| | | | | \
|**参数** |**类型** |**示例** |**说明** |
|---|---|---|---|
| | | | | \
|data |Object of [OpenCreateDatabaseRet](#opencreatedatabaseret) |{"database_id":"761261440756196****"} |已创建的扣子数据库信息。 |
| | | | | \
|code |Long |0 |调用状态码。 |\
| | | | |\
| | | |* 0 表示调用成功。 |\
| | | |* 其他值表示调用失败。你可以通过 msg 字段判断详细的错误原因。 |
| | | | | \
|msg |String |"" |状态信息。API 调用失败时可通过此字段查看详细错误信息。 |\
| | | |状态码为 0 时，msg 默认为空。 |
| | | | | \
|detail |Object of [ResponseDetail](#responsedetail) |{"logid":"20260302191950FA84144C90A8818E****"} |包含请求的详细信息的对象，主要用于记录请求的日志 ID 以便于排查问题。 |

### OpenCreateDatabaseRet {#opencreatedatabaseret}
<!-- @cols-width: 133,148,165,414 -->
| | | | | \
|**参数** |**类型** |**示例** |**说明** |
|---|---|---|---|
| | | | | \
|database_id |String |761262627636433**** |数据表 ID。 |

### ResponseDetail {#responsedetail}
<!-- @cols-width: 100,149,166,445 -->
| | | | | \
|**参数** |**类型** |**示例** |**说明** |
|---|---|---|---|
| | | | | \
|logid |String |20241210152726467C48D89D6DB2**** |本次请求的日志 ID。如果遇到异常报错场景，且反复重试仍然报错，可以根据此`logid`及错误码联系扣子团队获取帮助。详细说明可参考[获取帮助和技术支持](https://docs.coze.cn/guides/help_and_support)。 |

## 示例 {#示例}
### 请求示例 {#请求示例}
```JSON
curl --location --request POST 'https://api.coze.cn/v1/databases' \
--header 'Authorization : Bearer pat_O****' \
--header 'Content-Type: application/json' \
--data-raw '{
    "workspace_id": "749820488328041****",
    "app_id": "761257394935226****",
    "icon_file_id": "761258606549234****",
    "table_name": "user_info",
    "table_desc": "存储用户基本信息的数据库",    
    "fields": [
      {"name": "user_id", "desc": "姓名", "type": "string", "is_required": true},
      {"name":"level","desc":"等级","type":"integer","is_required":true}
    ], 
    "rw_mode": "unlimited_read_write",       
    "indexs": [ 
        {
            "index_name": "idx_level",
            "field_names": [
                "level"  
            ],
            "comment": "等级"
        }
    ],
    "connector_rw_config": [
        {
            "connector_id": "10000011",
            "connector_rw_mode": "online"
        }
    ],
    "connector_read_mode": "independent_connector"
}'
```

### 返回示例 {#返回示例}
```JSON
{
    "code": 0,
     "msg": "",
    "data": {
        "database_id": "761262627636433****"
    },   
    "detail": {
        "logid": "20260302200207F17DBC7387F656A3****"
    }
}
```

## 错误码 {#错误码}
如果成功调用扣子编程的 API，返回信息中 code 字段为 0。如果状态码为其他值，则表示接口调用失败。此时 msg 字段中包含详细错误信息，你可以参考[错误码](https://docs.coze.cn/developer_guides/coze_error_codes)文档查看对应的解决方法。