# 管理 Catalog、数据库和表

在工作区内按名称准备 Catalog 和数据库，再创建一张表并读取其数据。完成后会得到表资源，后续读取、预览、清空或删除都在这个资源上进行。

(sdk-ai-studio-catalog-table-flow)=
## 任务流程

1. 调用方提供工作区、Catalog 名称、数据库名称、表名称和列定义。
2. SDK 在工作区内查找同名 Catalog 和数据库；没有匹配项时创建它们。
3. SDK 在该数据库中创建表，并返回这张表对应的资源。
4. 使用返回的资源读取表数据。

(sdk-ai-studio-catalog-table-prepare)=
## 准备

| 需要的内容 | 在本页中的作用 |
| --- | --- |
| 已认证的客户端和已选择的工作区 | 确定本次资源操作的作用域。 |
| Catalog、数据库和表名称 | 选择或创建目标位置。 |
| 列定义 | 创建表结构。 |
| 创建权限 | 允许在目标位置创建不存在的资源。 |

本页不会创建客户端或选择工作区。先在开发者快速开始中完成首次连接，再将已选择的工作区交给下面的示例。

(sdk-ai-studio-catalog-table-create)=
## 创建表

下面的函数在一个已有工作区中准备 Catalog 和数据库，然后创建表。按名称准备不是只读查询：没有同名资源时会产生创建操作。

:::::{tab-set}
:sync-group: sdk-language

::::{tab-item} Python
:sync: python

```python
import moi_product_sdk as sdk


def create_orders_table(workspace):
    catalog = workspace.prepare_catalog("analytics")
    database = catalog.prepare_database("sales")
    table, _ = database.create_table_from_columns(
        "orders",
        [
            sdk.TableColumn("order_id", "INT"),
            sdk.TableColumn("customer_name", "VARCHAR"),
        ],
    )
    return table
```

::::

::::{tab-item} Go
:sync: go

```go
import (
	"context"

	sdk "github.com/matrixorigin/matrixflow/sdk/go-sdk"
)

func createOrdersTable(ctx context.Context, workspace *sdk.WorkspaceHandle) (*sdk.TableHandle, error) {
	catalog, err := workspace.PrepareCatalog(ctx, "analytics")
	if err != nil {
		return nil, err
	}
	database, err := catalog.PrepareDatabase(ctx, "sales")
	if err != nil {
		return nil, err
	}
	table, _, err := database.CreateTable(ctx, "orders", []sdk.TableColumn{
		{Name: "order_id", Type: "INT"},
		{Name: "customer_name", Type: "VARCHAR"},
	})
	if err != nil {
		return nil, err
	}
	return table, nil
}
```

::::

:::::

(sdk-ai-studio-catalog-table-read)=
## 读取表数据

创建函数返回的表资源可直接用于读取数据。下面的代码只读取当前返回的数据；它不证明后续写入、导入或查询已经完成。

:::::{tab-set}
:sync-group: sdk-language

::::{tab-item} Python
:sync: python

```python
rows = table.data()
```

::::

::::{tab-item} Go
:sync: go

```go
rows, err := table.Data(ctx)
if err != nil {
	return err
}
_ = rows
```

::::

:::::

(sdk-ai-studio-catalog-table-result)=
## 结果确认

保留创建函数返回的表资源，或使用创建、列表和调用方明确提供的资源标识重新取得它。读取结果只能确认这次读取；导入、查询和其他写入操作应在各自页面按任务状态或结果确认。

(sdk-ai-studio-catalog-table-limit)=
## 限制

- 表名称和列定义必须由调用方提供；SDK 不会从文件名或显示名称推断表结构。
- 删除或清空表会改变数据。执行前确认目标工作区、Catalog、数据库和表。

(sdk-ai-studio-catalog-table-next)=
## 下一步

- [管理卷和文件](catalog-tables-volumes-files.md)
- [创建数据传输任务](connectors-import-export.md)