Manage and use datasets in scripts

The pm.datasets function provides access to datasets from a script (supported in collection runs, monitors, and private runners, including runs started with the Postman CLI) or mock. You can query datasets using SQL to retrieve data when your script or mock runs. This enables your scripts and mocks 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 querying datasets in scripts and mocks.

pm.datasets

The pm.datasets function provides access to datasets from a script or mock. 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.

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.

const ds = pm.datasets('menu-id');
const result = await ds.executeView(
  'view-id',
  ['pizza']
);
const allRows = [];
for await (const row of result.rows) {
  allRows.push(row);
}

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.

const ds = pm.datasets('menu-id');
const result = await ds.executeQuery(
  'SELECT * FROM menu WHERE category = ?',
  ['pizza']
);
const allRows = [];
for await (const row of result.rows) {
  allRows.push(row);
}

Query a database source directly

Pass a third options argument of { source } to run the SQL against one of the dataset’s database sources, instead of against the copy of the dataset that Postman keeps in sync. Use it when you need the source’s own SQL dialect, or its current rows. The source value is a non-empty string, and it accepts the source’s name, ID, or slug.

const ds = pm.datasets('menu-id');
const result = await ds.executeQuery(
  'SELECT * FROM menu WHERE category = ?',
  ['pizza'],
  { source: 'Orders DB' }
);

If the source value doesn’t match a database source in the dataset, or matches more than one, the query fails instead of falling back to the synced copy. The dataset.executeView method doesn’t take an options argument.