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

# 表格管理

> 管理文件类别下的表格配置

<Tip>
  表格是文件类别中用于抽取结构化表格数据的配置。每个表格可以包含多个字段，用于定义表格的列。本文介绍如何通过 API 管理文件类别下的表格。
</Tip>

## 获取表格列表

获取指定文件类别下的所有表格列表：

<CodeGroup>
  ```bash curl icon=terminal wrap theme={null}
  curl \
    -H "x-ti-app-id: <your-app-id>" \
    -H "x-ti-secret-code: <your-secret-code>" \
    "https://docflow.textin.com/api/app-api/sip/platform/v2/category/tables/list?workspace_id=<your-workspace-id>&category_id=<category-id>"
  ```

  ```python Python icon=python expandable lines theme={null}
  import requests

  ti_app_id = "<your-app-id>"
  ti_secret_code = "<your-secret-code>"
  workspace_id = "<your-workspace-id>"
  category_id = "<category-id>"

  host = "https://docflow.textin.com"
  url = "/api/app-api/sip/platform/v2/category/tables/list"

  resp = requests.get(
      url=f"{host}{url}",
      params={
          "workspace_id": workspace_id,
          "category_id": category_id
      },
      headers={
          "x-ti-app-id": ti_app_id,
          "x-ti-secret-code": ti_secret_code,
      },
      timeout=30,
  )

  result = resp.json()
  if result.get("code") == 200:
      tables = result.get("result", {}).get("tables", [])
      print(f"共找到 {len(tables)} 个表格")
      for table in tables:
          print(f"表格ID: {table.get('id')}, 名称: {table.get('name')}")
          print(f"  提示词: {table.get('prompt')}")
          print(f"  多表合并: {table.get('collect_from_multi_table')}")
  else:
      print(f"获取失败: {result.get('msg')}")
  ```
</CodeGroup>

**请求参数：**

* `workspace_id` (必填): 工作空间 ID
* `category_id` (必填): 文件类别 ID

**响应示例：**

```json theme={null}
{
  "code": 200,
  "msg": "success",
  "result": {
    "tables": [
      {
        "id": "table_123",
        "name": "货物明细",
        "prompt": "请抽取每行的品名、数量和金额",
        "collect_from_multi_table": true
      },
      {
        "id": "table_456",
        "name": "费用明细",
        "prompt": "请抽取每行的费用项目和金额",
        "collect_from_multi_table": false
      }
    ]
  }
}
```

## 新增表格

在指定文件类别下批量新增表格：

<CodeGroup>
  ```bash curl icon=terminal wrap theme={null}
  curl -X POST \
    -H "x-ti-app-id: <your-app-id>" \
    -H "x-ti-secret-code: <your-secret-code>" \
    -H "Content-Type: application/json" \
    -d '{
      "workspace_id": "<your-workspace-id>",
      "category_id": "<category-id>",
      "tables": [
        {
          "name": "货物明细",
          "prompt": "请抽取每行的品名、数量和金额",
          "collect_from_multi_table": true,
          "fields": [
            {"name": "货物名称", "description": "货物或服务名称"},
            {"name": "数量", "description": "货物数量"},
            {"name": "单价", "description": "货物单价"},
            {"name": "金额", "description": "货物金额"}
          ]
        }
      ]
    }' \
    "https://docflow.textin.com/api/app-api/sip/platform/v2/category/tables/batch_add"
  ```

  ```python Python icon=python expandable lines theme={null}
  import requests

  ti_app_id = "<your-app-id>"
  ti_secret_code = "<your-secret-code>"
  workspace_id = "<your-workspace-id>"
  category_id = "<category-id>"

  host = "https://docflow.textin.com"
  url = "/api/app-api/sip/platform/v2/category/tables/batch_add"

  payload = {
      "workspace_id": workspace_id,
      "category_id": category_id,
      "tables": [
          {
              "name": "货物明细",
              "prompt": "请抽取每行的品名、数量和金额",
              "collect_from_multi_table": True,  # 是否合并文档中的多个表格
              "fields": [
                  {"name": "货物名称", "description": "货物或服务名称"},
                  {"name": "数量", "description": "货物数量"},
                  {"name": "单价", "description": "货物单价"},
                  {"name": "金额", "description": "货物金额"}
              ]
          }
      ]
  }

  resp = requests.post(
      url=f"{host}{url}",
      json=payload,
      headers={
          "x-ti-app-id": ti_app_id,
          "x-ti-secret-code": ti_secret_code,
      },
      timeout=30,
  )

  result = resp.json()
  if result.get("code") == 200:
      table_ids = result.get("result", {}).get("table_ids", [])
      print(f"表格创建成功，IDs: {table_ids}")
  else:
      print(f"创建失败: {result.get('msg')}")
  ```
</CodeGroup>

**请求参数：**

* `workspace_id` (必填): 工作空间 ID
* `category_id` (必填): 文件类别 ID
* `tables` (必填): 表格数组，每个元素包含以下属性：
  * `name` (必填): 表格名称，最大长度 50
  * `prompt` (选填): 表格语义抽取提示词，最大长度 200
  * `collect_from_multi_table` (选填): 是否多表合并，默认为 false
  * `fields` (选填): 表格字段数组，可在创建表格时直接内嵌字段定义

**响应示例：**

```json theme={null}
{
  "code": 200,
  "msg": "success",
  "result": {
    "table_ids": ["table_new_789"]
  }
}
```

<Note>
  **多表合并说明**：当文档中存在多个结构相同的表格时，开启 `collect_from_multi_table` 可以将它们合并为一个表格结果。例如，发票明细表格可能跨页显示，开启多表合并后会将所有页的明细合并到一起。
</Note>

## 更新表格

批量更新指定表格的信息：

<CodeGroup>
  ```bash curl icon=terminal wrap theme={null}
  curl -X POST \
    -H "x-ti-app-id: <your-app-id>" \
    -H "x-ti-secret-code: <your-secret-code>" \
    -H "Content-Type: application/json" \
    -d '{
      "workspace_id": "<your-workspace-id>",
      "category_id": "<category-id>",
      "tables": [
        {
          "table_id": "<table-id>",
          "name": "更新后的表格名称",
          "prompt": "更新后的提示词",
          "collect_from_multi_table": true
        }
      ]
    }' \
    "https://docflow.textin.com/api/app-api/sip/platform/v2/category/tables/batch_update"
  ```

  ```python Python icon=python expandable lines theme={null}
  import requests

  ti_app_id = "<your-app-id>"
  ti_secret_code = "<your-secret-code>"
  workspace_id = "<your-workspace-id>"
  category_id = "<category-id>"
  table_id = "<table-id>"

  host = "https://docflow.textin.com"
  url = "/api/app-api/sip/platform/v2/category/tables/batch_update"

  payload = {
      "workspace_id": workspace_id,
      "category_id": category_id,
      "tables": [
          {
              "table_id": table_id,
              "name": "更新后的表格名称",
              "prompt": "更新后的提示词",
              "collect_from_multi_table": True
          }
      ]
  }

  resp = requests.post(
      url=f"{host}{url}",
      json=payload,
      headers={
          "x-ti-app-id": ti_app_id,
          "x-ti-secret-code": ti_secret_code,
      },
      timeout=30,
  )

  result = resp.json()
  if result.get("code") == 200:
      print("表格更新成功")
  else:
      print(f"更新失败: {result.get('msg')}")
  ```
</CodeGroup>

**请求参数：**

* `workspace_id` (必填): 工作空间 ID
* `category_id` (必填): 文件类别 ID
* `tables` (必填): 表格数组，每个元素包含以下属性：
  * `table_id` (必填): 表格 ID
  * `name` (选填): 表格名称，最大长度 50
  * `prompt` (选填): 表格语义抽取提示词，最大长度 200
  * `collect_from_multi_table` (必填): 是否多表合并

## 删除表格

删除指定的表格，支持批量删除：

<CodeGroup>
  ```bash curl icon=terminal wrap theme={null}
  curl -X POST \
    -H "x-ti-app-id: <your-app-id>" \
    -H "x-ti-secret-code: <your-secret-code>" \
    -H "Content-Type: application/json" \
    -d '{
      "workspace_id": "<your-workspace-id>",
      "category_id": "<category-id>",
      "table_ids": ["table_123", "table_456"]
    }' \
    "https://docflow.textin.com/api/app-api/sip/platform/v2/category/tables/delete"
  ```

  ```python Python icon=python expandable lines theme={null}
  import requests

  ti_app_id = "<your-app-id>"
  ti_secret_code = "<your-secret-code>"
  workspace_id = "<your-workspace-id>"
  category_id = "<category-id>"

  host = "https://docflow.textin.com"
  url = "/api/app-api/sip/platform/v2/category/tables/delete"

  payload = {
      "workspace_id": workspace_id,
      "category_id": category_id,
      "table_ids": ["table_123", "table_456"]
  }

  resp = requests.post(
      url=f"{host}{url}",
      json=payload,
      headers={
          "x-ti-app-id": ti_app_id,
          "x-ti-secret-code": ti_secret_code,
      },
      timeout=30,
  )

  result = resp.json()
  if result.get("code") == 200:
      print("表格删除成功")
  else:
      print(f"删除失败: {result.get('msg')}")
  ```
</CodeGroup>

**请求参数：**

* `workspace_id` (必填): 工作空间 ID
* `category_id` (必填): 文件类别 ID
* `table_ids` (必填): 要删除的表格 ID 数组

<Warning>
  删除表格会同时删除该表格下的所有字段，请谨慎操作。
</Warning>

## 表格字段管理

使用 `tables/batch_add` 接口可以在创建表格时直接内嵌字段定义，无需分步调用。也可以单独通过[字段管理](./fields_management)的批量接口为已有表格添加字段。

### 示例：一次性创建表格及其字段

```python Python icon=python expandable theme={null}
import requests

ti_app_id = "<your-app-id>"
ti_secret_code = "<your-secret-code>"
workspace_id = "<your-workspace-id>"
category_id = "<category-id>"
host = "https://docflow.textin.com"

# 创建表格并内嵌字段（一次调用完成）
resp = requests.post(
    url=f"{host}/api/app-api/sip/platform/v2/category/tables/batch_add",
    json={
        "workspace_id": workspace_id,
        "category_id": category_id,
        "tables": [
            {
                "name": "货物明细",
                "prompt": "请抽取每行的品名、数量和金额",
                "collect_from_multi_table": True,
                "fields": [
                    {"name": "货物名称", "description": "货物或服务名称"},
                    {"name": "数量", "description": "货物数量"},
                    {"name": "单价", "description": "货物单价"},
                    {"name": "金额", "description": "货物金额"}
                ]
            }
        ]
    },
    headers={
        "x-ti-app-id": ti_app_id,
        "x-ti-secret-code": ti_secret_code,
    },
)

result = resp.json()
if result.get("code") == 200:
    table_ids = result.get("result", {}).get("table_ids", [])
    print(f"表格及字段创建完成，表格IDs: {table_ids}")
else:
    print(f"创建失败: {result.get('msg')}")
```

## 表格配置说明

### 表格属性

* **name**: 表格名称，必填
* **prompt**: 表格语义抽取提示词，用于指导 AI 进行表格抽取
* **collect\_from\_multi\_table**: 是否多表合并

### 多表合并场景

以下场景适合开启多表合并：

1. **跨页表格**：表格内容跨越多页显示
2. **重复表格**：文档中存在多个结构相同的表格
3. **分段表格**：表格被其他内容分隔成多段

示例：发票货物明细表格如果跨越多页，开启多表合并后，所有页的货物明细会合并成一个完整的表格结果。

## 下一步

* 学习[字段管理](./fields_management) - 为表格添加字段
* 学习[样本管理](./samples_management) - 管理文件类别的样本文件
* 返回[文件类别快速启动](./quickstart) - 查看文件类别基础操作