> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/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`): 是否還有更多頁面。