> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/llms.txt

# dataset.listItems()

**新增於：** `@mastra/core@1.4.0`

列出資料集中的項目。只提供 `version` 時，會傳回該版本所有項目的純 `DatasetItem[]` 快照。其他情況（沒有參數，或提供 `search`／`page`／`perPage`，不論有否提供 `version`）則會傳回分頁 `{ items, pagination }` 結構。

## 使用範例

```typescript
import { Mastra } from '@mastra/core'

const mastra = new Mastra({/* storage config */})

const dataset = await mastra.datasets.get({ id: 'dataset-id' })

// Paginated list (default: page 0, 20 per page)
const result = await dataset.listItems()

// List with search
const filtered = await dataset.listItems({ search: 'TypeScript', page: 0, perPage: 10 })

// Paginated list scoped to a specific version
const versionedPage = await dataset.listItems({ version: 2, page: 0, perPage: 20 })

// Version-only snapshot returns a bare DatasetItem[] (deprecated form —
// prefer passing page/perPage to receive the paginated shape).
const versionedItems = await dataset.listItems({ version: 2 })
```

## 參數

**version** (`number`): 要列出項目的資料集版本。單獨傳入時，會以純 DatasetItem\[] 快照傳回該版本的所有項目。將 search／page／perPage 與 version 一併傳入，便會改用分頁結構。

**page** (`number`): 分頁頁碼。預設為 0。

**perPage** (`number`): 每頁的項目數目。預設為 20。

**search** (`string`): 用於篩選項目的搜尋字串。

## 傳回值

只提供 `version`（沒有 `search`、`page` 或 `perPage`）時：

**result** (`Promise<DatasetItem[]>`): 指定資料集版本中所有項目的純陣列。此結構只為向後兼容而保留，現已棄用；傳入 page／perPage（或 search）即可一律接收下方的分頁結構。

其他所有情況（沒有參數，或提供 `search`／`page`／`perPage`，不論有否提供 `version`）時：

**result** (`Promise<object>`): 分頁回應。

**result.items** (`DatasetItem[]`): 目前頁面的項目陣列。

**result.pagination** (`object`): 分頁元資料。

**result.pagination.total** (`number`): 項目總數。

**result.pagination.page** (`number`): 目前頁碼。

**result.pagination.perPage** (`number | false`): 每頁項目數目；如不分頁則為 false。

**result.pagination.hasMore** (`boolean`): 是否仍有更多頁面。