# 查看 SQL 历史与画像

使用 AI Studio SDK 分页查询工作区的 SQL 执行历史，获取目标语句 ID，并按语句 ID 读取执行详情与执行画像。

(sdk-ai-studio-sql-history-flow)=
## 任务流程

先通过工作区 SQL 服务分页读取执行历史并记录目标语句 ID，再用同一语句 ID 查询单条 SQL 的执行状态、报错信息与执行画像。

```text
工作区 SQL 服务
      │
      ▼
分页查询 SQL 执行历史（偏移量 + 每页条数）
      │
      ▼
    语句 ID
  ├── 读取执行详情（语句状态与错误信息）
  └── 读取执行画像（画像获取标志与画像消息）
```

(sdk-ai-studio-sql-history-prepare)=
## 准备

1. 已完成 [使用 SDK](../../../quickstart/ai-studio/sdk.md) 中的服务地址、个人访问令牌与工作区配置。
2. **语句 ID**（读取详情与画像时）：从下文 SQL 执行历史列表中获取，或使用 [执行 SQL 查询](../数据处理/执行SQL查询.md) 提交查询后保存返回的语句 ID。

(sdk-ai-studio-sql-history-s1)=
## 查询 SQL 执行历史

以下示例从偏移量 `0` 开始读取最近 20 条 SQL 执行记录，输出总记录数及每条记录的语句 ID、数据库名、状态与报错信息。继续向后翻页时，将偏移量累加本页实际返回的记录条数；当返回记录列表为空时停止翻页。

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

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

```python
import os

import moi_product_sdk as sdk

client = sdk.new_with_personal_access_token(
    os.environ["PRODUCT_API_BASE_URL"],
    os.environ["PRODUCT_API_KEY"],
)
workspace = client.workspace(os.environ["WORKSPACE_ID"])
service = workspace.sql()

page = service.query_history(
    sdk.with_query_history_offset(0),
    sdk.with_query_history_limit(20),
)
print("总数:", page.total, "偏移:", page.offset, "数量:", page.limit)
for record in page.query_list:
    print(record.statement_id, record.database, record.status, record.error)
```

::::

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

```go
package main

import (
	"context"
	"fmt"
	"os"

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

func main() {
	ctx := context.Background()
	client, err := sdk.NewWithPersonalAccessToken(
		os.Getenv("PRODUCT_API_BASE_URL"),
		os.Getenv("PRODUCT_API_KEY"),
	)
	if err != nil {
		panic(err)
	}
	workspace, err := client.Workspace(os.Getenv("WORKSPACE_ID"))
	if err != nil {
		panic(err)
	}
	service := workspace.SQL()

	page, err := service.QueryHistory(
		ctx,
		sdk.WithQueryHistoryOffset(0),
		sdk.WithQueryHistoryLimit(20),
	)
	if err != nil {
		panic(err)
	}
	fmt.Println("总数:", page.GetTotal(), "偏移:", page.GetOffset(), "数量:", page.GetLimit())
	for _, record := range page.GetQueryList() {
		fmt.Println(record.GetStatementId(), record.GetDatabase(), record.GetStatus(), record.GetError())
	}
}
```

::::

:::::

(sdk-ai-studio-sql-history-action-2)=
## 读取执行详情与画像

从历史记录中选取目标语句 ID，复用工作区 SQL 服务依次读取执行详情与执行画像。详情反映语句的当前状态与错误文本，画像响应指示执行画像是否生成成功并返回画像内容。

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

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

```python
if not page.query_list:
    raise SystemExit("当前工作区没有 SQL 执行记录")

statement_id = page.query_list[0].statement_id
detail = service.query_detail(statement_id)
if detail is not None:
    print("详情:", detail.statement_id, detail.status, detail.error)

profile = service.query_profile(statement_id)
print("画像:", profile.statement_id, profile.profile.success, profile.profile.message)
```

::::

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

```go
if len(page.GetQueryList()) == 0 {
	fmt.Println("当前工作区没有 SQL 执行记录")
	return
}

statementID := page.GetQueryList()[0].GetStatementId()
detail, err := service.QueryDetail(ctx, statementID)
if err != nil {
	panic(err)
}
if detail != nil {
	fmt.Println("详情:", detail.GetStatementId(), detail.GetStatus(), detail.GetError())
}

profile, err := service.QueryProfile(ctx, statementID)
if err != nil {
	panic(err)
}
fmt.Println("画像:", profile.GetStatementId(), profile.GetProfile().GetSuccess(), profile.GetProfile().GetMessage())
```

::::

:::::

(sdk-ai-studio-sql-history-next)=
## 下一步

- [执行 SQL 查询](../数据处理/执行SQL查询.md)
- [查看任务执行概览](查看任务执行概览.md)
