0
# Dataset Management
1

2
Dataset creation, management, and versioning system for AI evaluation and experimentation workflows. Supports structured examples with input/output pairs and metadata for comprehensive evaluation datasets.
3

4
## Capabilities
5

6
### Dataset Creation
7

8
Create new datasets with structured examples for AI model evaluation and experimentation.
9

10
```typescript { .api }
11
/**
12
 * Create a new dataset with examples
13
 * @param params - Dataset creation parameters
14
 * @returns Promise resolving to dataset creation response
15
 */
16
function createDataset(params: {
17
  client?: PhoenixClient;
18
  name: string;
19
  description: string;
20
  examples: Example[];
21
}): Promise<CreateDatasetResponse>;
22

23
interface Example {
24
  input: Record<string, unknown>;
25
  output?: Record<string, unknown> | null;
26
  metadata?: Record<string, unknown> | null;
27
}
28

29
interface CreateDatasetResponse {
30
  datasetId: string;
31
}
32
```
33

34
**Usage Example:**
35

36
```typescript
37
import { createDataset } from "@arizeai/phoenix-client/datasets";
38

39
const response = await createDataset({
40
  name: "customer-support-qa",
41
  description: "Customer support Q&A dataset for evaluation",
42
  examples: [
43
    {
44
      input: { question: "How do I reset my password?" },
45
      output: { answer: "Click 'Forgot Password' on the login page and follow the instructions." },
46
      metadata: { category: "authentication", difficulty: "easy" }
47
    },
48
    {
49
      input: { question: "What are your business hours?" },
50
      output: { answer: "We are open Monday-Friday 9AM-6PM EST." },
51
      metadata: { category: "general", difficulty: "easy" }
52
    }
53
  ]
54
});
55

56
console.log(`Created dataset with ID: ${response.datasetId}`);
57
```
58

59
### Dataset Retrieval
60

61
Retrieve complete datasets by ID or name, with optional version specification.
62

63
```typescript { .api }
64
/**
65
 * Get a dataset by selector with optional version
66
 * @param params - Dataset retrieval parameters
67
 * @returns Promise resolving to complete dataset
68
 */
69
function getDataset(params: {
70
  client?: PhoenixClient;
71
  dataset: DatasetSelector;
72
  versionId?: string;
73
}): Promise<Dataset>;
74

75
type DatasetSelector =
76
  | { datasetId: string }
77
  | { datasetName: string };
78

79
interface Dataset extends DatasetInfo {
80
  examples: ExampleWithId[];
81
  versionId: string;
82
}
83

84
interface DatasetInfo {
85
  id: string;
86
  name: string;
87
  description?: string | null;
88
  metadata?: Record<string, unknown>;
89
}
90

91
interface ExampleWithId extends Example {
92
  id: string;
93
  updatedAt: Date;
94
}
95
```
96

97
**Usage Examples:**
98

99
```typescript
100
import { getDataset } from "@arizeai/phoenix-client/datasets";
101

102
// Get dataset by ID
103
const dataset = await getDataset({
104
  dataset: { datasetId: "dataset_123" }
105
});
106

107
// Get dataset by name
108
const dataset = await getDataset({
109
  dataset: { datasetName: "customer-support-qa" }
110
});
111

112
// Get specific version
113
const dataset = await getDataset({
114
  dataset: { datasetName: "customer-support-qa" },
115
  versionId: "version_456"
116
});
117

118
console.log(`Dataset ${dataset.name} has ${dataset.examples.length} examples`);
119
```
120

121
### Dataset Examples Retrieval
122

123
Retrieve only the examples from a dataset without full dataset metadata.
124

125
```typescript { .api }
126
/**
127
 * Get examples from a dataset
128
 * @param params - Dataset examples retrieval parameters
129
 * @returns Promise resolving to dataset examples
130
 */
131
function getDatasetExamples(params: {
132
  client?: PhoenixClient;
133
  dataset: DatasetSelector;
134
  versionId?: string;
135
}): Promise<DatasetExamples>;
136

137
interface DatasetExamples {
138
  examples: ExampleWithId[];
139
  versionId: string;
140
}
141
```
142

143
**Usage Example:**
144

145
```typescript
146
import { getDatasetExamples } from "@arizeai/phoenix-client/datasets";
147

148
const { examples, versionId } = await getDatasetExamples({
149
  dataset: { datasetName: "eval-dataset" }
150
});
151

152
// Process examples for evaluation
153
for (const example of examples) {
154
  console.log(`Input: ${JSON.stringify(example.input)}`);
155
  if (example.output) {
156
    console.log(`Expected output: ${JSON.stringify(example.output)}`);
157
  }
158
}
159
```
160

161
### Dataset Examples Appending
162

163
Add new examples to an existing dataset, creating a new version.
164

165
```typescript { .api }
166
/**
167
 * Append examples to an existing dataset
168
 * @param params - Dataset append parameters
169
 * @returns Promise resolving to append operation response
170
 */
171
function appendDatasetExamples(params: {
172
  client?: PhoenixClient;
173
  dataset: DatasetSelector;
174
  examples: Example[];
175
}): Promise<void>;
176
```
177

178
**Usage Example:**
179

180
```typescript
181
import { appendDatasetExamples } from "@arizeai/phoenix-client/datasets";
182

183
await appendDatasetExamples({
184
  dataset: { datasetName: "customer-support-qa" },
185
  examples: [
186
    {
187
      input: { question: "How do I cancel my subscription?" },
188
      output: { answer: "Visit your account settings and click 'Cancel Subscription'." },
189
      metadata: { category: "billing", difficulty: "medium" }
190
    }
191
  ]
192
});
193
```
194

195
### Dataset Information
196

197
Get dataset metadata without examples for lightweight operations.
198

199
```typescript { .api }
200
/**
201
 * Get dataset metadata without examples
202
 * @param params - Dataset info parameters
203
 * @returns Promise resolving to dataset information
204
 */
205
function getDatasetInfo(params: {
206
  client?: PhoenixClient;
207
  dataset: DatasetSelector;
208
}): Promise<DatasetInfo>;
209
```
210

211
**Usage Example:**
212

213
```typescript
214
import { getDatasetInfo } from "@arizeai/phoenix-client/datasets";
215

216
const info = await getDatasetInfo({
217
  dataset: { datasetName: "large-evaluation-set" }
218
});
219

220
console.log(`Dataset: ${info.name}`);
221
console.log(`Description: ${info.description}`);
222
console.log(`Metadata:`, info.metadata);
223
```
224

225
### Dataset Information by Name
226

227
Get dataset metadata by name without the full dataset selector interface.
228

229
```typescript { .api }
230
/**
231
 * Get dataset information by name only
232
 * @param params - Dataset info by name parameters
233
 * @returns Promise resolving to dataset information
234
 */
235
function getDatasetInfoByName(params: {
236
  client?: PhoenixClient;
237
  datasetName: string;
238
}): Promise<DatasetInfo>;
239
```
240

241
**Usage Example:**
242

243
```typescript
244
import { getDatasetInfoByName } from "@arizeai/phoenix-client/datasets";
245

246
const info = await getDatasetInfoByName({
247
  datasetName: "customer-support-qa"
248
});
249

250
console.log(`Found dataset: ${info.name} (ID: ${info.id})`);
251
```
252

253
### List All Datasets
254

255
Retrieve information about all available datasets with creation and update timestamps.
256

257
```typescript { .api }
258
/**
259
 * List all datasets available to the client
260
 * @param params - List datasets parameters
261
 * @returns Promise resolving to array of dataset information with timestamps
262
 */
263
function listDatasets(params: {
264
  client?: PhoenixClient;
265
}): Promise<FullDatasetInfo[]>;
266

267
interface FullDatasetInfo extends DatasetInfo {
268
  startDate: Date;
269
  endDate: Date;
270
}
271
```
272

273
**Usage Example:**
274

275
```typescript
276
import { listDatasets } from "@arizeai/phoenix-client/datasets";
277

278
const datasets = await listDatasets({});
279

280
console.log(`Found ${datasets.length} datasets:`);
281
for (const dataset of datasets) {
282
  console.log(`- ${dataset.name}: ${dataset.description || 'No description'}`);
283
  console.log(`  Created: ${dataset.startDate.toISOString()}`);
284
  console.log(`  Updated: ${dataset.endDate.toISOString()}`);
285
}
286
```
287

288
### Dataset Versioning
289

290
Datasets support versioning to track changes over time and maintain reproducible experiments.
291

292
```typescript { .api }
293
/**
294
 * Dataset version selector for retrieving specific versions
295
 */
296
interface DatasetVersionSelector {
297
  dataset: DatasetSelector;
298
  versionId?: string;
299
}
300

301
/**
302
 * Information about a specific dataset version
303
 */
304
interface DatasetVersionInfo {
305
  id: string;
306
  description?: string | null;
307
  metadata?: Record<string, unknown>;
308
  createdAt: Date;
309
}
310

311
/**
312
 * Dataset with version information
313
 */
314
interface DatasetWithVersion extends Dataset {
315
  versionInfo: DatasetVersionInfo;
316
}
317
```
318

319
### Example Structure
320

321
Dataset examples follow a flexible structure supporting various AI use cases.
322

323
**Example Components:**
324

325
- **input**: Required input data for the AI task (any JSON structure)
326
- **output**: Optional expected output or ground truth (any JSON structure)
327
- **metadata**: Optional additional information for categorization and analysis
328

329
**Common Example Patterns:**
330

331
```typescript
332
// Question-answering
333
{
334
  input: { question: "What is the capital of France?" },
335
  output: { answer: "Paris" },
336
  metadata: { category: "geography", difficulty: "easy" }
337
}
338

339
// Text classification
340
{
341
  input: { text: "This product is amazing!" },
342
  output: { sentiment: "positive", confidence: 0.95 },
343
  metadata: { source: "reviews", language: "en" }
344
}
345

346
// Function calling
347
{
348
  input: {
349
    query: "What's the weather in New York?",
350
    tools: ["get_weather", "get_location"]
351
  },
352
  output: {
353
    function_call: "get_weather",
354
    arguments: { location: "New York, NY" }
355
  },
356
  metadata: { use_case: "function_calling" }
357
}
358

359
// Multi-modal
360
{
361
  input: {
362
    image_url: "https://example.com/image.jpg",
363
    question: "What objects are in this image?"
364
  },
365
  output: { objects: ["car", "tree", "building"] },
366
  metadata: { modality: "vision", source: "coco" }
367
}
368
```
369

370
### Best Practices
371

372
- **Structured Input**: Use consistent input structure within a dataset
373
- **Meaningful Metadata**: Include categorization and source information
374
- **Version Management**: Create new versions when adding significant examples
375
- **Validation**: Ensure output format matches expected evaluation criteria
376
- **Documentation**: Provide clear dataset descriptions for team collaboration