Manage and use datasets in scripts

The pm.datasets function provides access to datasets from a script or local mock server. You can query datasets using SQL to retrieve data when your script or mock server runs. This enables your scripts and mock servers to return dynamic, data-driven responses instead of static values.

All methods are asynchronous and return Promises, so use await to access their results. Query results return rows as an async iterable, so use the for await...of loop to read the returned rows.

Learn more about testing with datasets.

pm.datasets

The pm.datasets function provides access to datasets from a script or local mock server. You can load a dataset by its ID and then use methods to query the dataset or manage views.

pm.datasets(datasetId:String)

Loads a dataset and returns a handle you can use to interact with the dataset.

1
const ds = pm.datasets('menu-id');

dataset.executeView(viewId:String, params?:String[])

Runs a view that’s already defined in the dataset and returns the results. Query rows are returned as an async iterable, so use the for await...of loop to read the rows.

1
const ds = pm.datasets('menu-id');
2
3
const result = await ds.executeView(
4
  'view-id',
5
  ['pizza']
6
);
7
8
const rows = [];
9
10
for await (const row of result.rows) {
11
  rows.push(row);
12
}
13
14
// Use the rows in a script
15
console.log(rows);
16
17
// In a local mock server, you can return the rows in the response
18
// res.writeHead(200, { 'Content-Type': 'application/json' });
19
// return res.end(JSON.stringify({ items: rows }));

dataset.executeQuery(sql:String, params?:String[])

Runs a custom SQL query against the dataset and returns the results. Query rows are returned as an async iterable, so use the for await...of loop to read the rows.

1
const ds = pm.datasets('menu-id');
2
3
const result = await ds.executeQuery(
4
  'SELECT * FROM menu WHERE category = ?',
5
  ['pizza']
6
);
7
8
const rows = [];
9
10
for await (const row of result.rows) {
11
  rows.push(row);
12
}
13
14
// Use the rows in a script
15
console.log(rows);
16
17
// In a local mock server, you can return the rows in the response
18
// res.writeHead(200, { 'Content-Type': 'application/json' });
19
// return res.end(JSON.stringify({ items: rows }));

dataset.addView(options:Object)

Creates a reusable SQL view on the dataset.

1
const ds = pm.datasets('menu-id');
2
3
await ds.addView({
4
  name: 'expensive_items',
5
  sql: 'SELECT * FROM menu WHERE price > 15'
6
});

dataset.removeView(viewId:String)

Removes a view from the dataset.

1
const ds = pm.datasets('menu-id');
2
3
await ds.removeView('view-id');