Use datasets in Postman

After you create a dataset, you can use it across your API workflows in Postman. You can run data-driven collection tests, power dynamic mock server responses, and validate API responses in scripts. Datasets enable you to reuse the same data across workflows and work with consistent, queryable data instead of duplicating or hardcoding values.

Datasets can be backed by local or cloud data files or live data sources such as databases. Views enable you to filter, transform, and subset that data for specific scenarios. This enables you to test against current data, target specific test cases, and control the data used by collection runs, scripts, and mock servers.

Use datasets in collection runs

You can use datasets as iteration data when manually running a collection. Dataset fields are automatically exposed as variables during the run. You can access them using the {{variableName}} syntax in your requests. You can also access them in pre-request and post-response scripts using pm.iterationData. Additionally, you can use the pm.datasets function in scripts to query data from the dataset during a run.

Each row returned by the selected view becomes an iteration in the collection run. Views enable you to control which data is used during a run, such as filtering a large dataset to a specific set of test scenarios.

Use the following example to use datasets in your collection runs:

1. Create a dataset with a local file data source that includes userId, email, and name fields in CSV format.

   1
   userId,email,name
   2
   1,user1@example.com,User One
   3
   2,user2@example.com,User Two
   4
   3,user3@example.com,User Three
   5
   4,user4@example.com,User Four

2. Click Items in the sidebar.

3. Click Collections and select the collection you want to run against the dataset.

4. Reference the fields in your requests using variables that match the field names in your dataset.

   You can access iteration data in your requests using the {{variableName}} syntax. For example, if your dataset has a userId field, you can reference it in your request URL as {{userId}}. Learn more about using variables.

   1
   GET /user?userId={{userId}}&email={{email}}&name={{name}}

   You can access the values from the current iteration in pre-request and post-response scripts using pm.iterationData. Learn more about using iteration data variables in scripts.

   1
   console.log(pm.iterationData.get("email"));

   You can also use the pm.datasets function in pre-request and post-response scripts to query additional data from the dataset using values from the current iteration. Learn more about using datasets in scripts.

   1
   const ds = pm.datasets("users-dataset-id");
   2
   3
   const result = await ds.executeQuery(
   4
     "SELECT * FROM users WHERE email = ?",
   5
     [pm.iterationData.get("email")]
   6
   );
   7
   8
   const allRows = [];
   9
   10
   for await (const row of result.rows) {
   11
     allRows.push(row);
   12
   }
   13
   14
   console.log(JSON.stringify(allRows));

5. Select the collection again and click Run in the upper right.

6. Select Run manually.

7. Configure the collection run as needed.

8. Under Dataset, select the dataset you’d like to use for the run. Then select a view with the data you want to run against.

   You can click Create a new dataset or Create a new view to create and select a dataset or view without leaving the collection run configuration.

9. (Optional) Click the Data tab in the left pane to preview and edit the view you selected.

10. Click Start run.

During the run, Postman assigns values from each row returned by the selected view to your variables. Each row is used as iteration data for a single iteration, allowing the same requests to run with different inputs. The collection run summary shows the data used for each iteration.

When using the pm.datasets function, query results return rows as an async iterable, so use the for await...of loop to read the returned rows. You can also use executeView() to validate responses against a predefined view instead of writing a custom query in the script.

Use datasets in mock servers

You can use the pm.datasets function in a local mock server to return dynamic responses based on queryable data. This enables you to use the same dataset across requests, filter data for specific endpoints, and simulate more realistic API behavior instead of returning only static responses.

Use the following example to use a dataset in a local mock server:

1. Create a dataset with a local file data source that includes userId, email, and name fields in CSV format.

   1
   userId,email,name
   2
   1,user1@example.com,User One
   3
   2,user2@example.com,User Two
   4
   3,user3@example.com,User Three
   5
   4,user4@example.com,User Four

2. In your local mock server implementation file, load the dataset using pm.datasets().

3. Run a query against the dataset in your request handler and return the matching row in the response.

   1
   const http = require("http");
   2
   const url = require("url");
   3
   const PORT = process.env.PORT || 4500;
   4
   5
   const server = http.createServer(async (req, res) => {
   6
     const { method } = req;
   7
     const { pathname, query } = url.parse(req.url, true);
   8
   9
     // @endpoint GET /user
   10
     if (method === "GET" && pathname === "/user") {
   11
       const ds = pm.datasets("users-dataset-id");
   12
   13
       const result = await ds.executeQuery(
   14
         "SELECT userId, email, name FROM users WHERE userId = ?",
   15
         [query.userId]
   16
       );
   17
   18
       const allRows = [];
   19
   20
       for await (const row of result.rows) {
   21
         allRows.push(row);
   22
       }
   23
   24
       if (allRows.length === 0) {
   25
         res.writeHead(404, { "Content-Type": "application/json" });
   26
         return res.end(JSON.stringify({ error: "User not found" }));
   27
       }
   28
   29
       res.writeHead(200, { "Content-Type": "application/json" });
   30
       return res.end(JSON.stringify(allRows[0]));
   31
     }
   32
   33
     res.writeHead(404, { "Content-Type": "application/json" });
   34
     res.end(JSON.stringify({ error: "Endpoint not defined" }));
   35
   });
   36
   37
   server.listen(PORT, () => {
   38
     console.log(`Mock server running on port ${PORT}`);
   39
   });

4. Start the mock server and send a request to the endpoint. For example, you can send a GET request to the following:

   1
   http://localhost:4500/user?userId=2

The mock server queries the dataset when the request runs and returns the matching data in the response. Query results return rows as an async iterable, so use the for await...of loop to read the returned rows. You can also use views with executeView() to reuse predefined queries across endpoints.

Learn more about local mock servers and using datasets in scripts.

Use datasets in scripts

You can use the pm.datasets function in pre-request and post-response scripts to validate response data against queryable data stored in a dataset. This enables you to compare API responses with expected values, test multiple scenarios, and reuse the same data across requests and workflows.

Use the following example to use a dataset in a post-response script:

1. Create a dataset with a local file data source that includes userId, email, and name fields in CSV format.

   1
   userId,email,name
   2
   1,user1@example.com,User One
   3
   2,user2@example.com,User Two
   4
   3,user3@example.com,User Three
   5
   4,user4@example.com,User Four

2. Send a request to an endpoint that returns user data, such as:

   1
   GET /user?userId=2

3. In the request’s Scripts > Post-response tab, load the dataset and query it using a value from the response.

   1
   const ds = pm.datasets("users-dataset-id");
   2
   const responseJson = pm.response.json();
   3
   4
   const result = await ds.executeQuery(
   5
     "SELECT userId, email, name FROM users WHERE userId = ?",
   6
     [responseJson.userId]
   7
   );
   8
   9
   const allRows = [];
   10
   11
   for await (const row of result.rows) {
   12
     allRows.push(row);
   13
   }
   14
   15
   pm.test("Response matches dataset", function () {
   16
     pm.expect(allRows.length).to.eql(1);
   17
     pm.expect(responseJson.email).to.eql(allRows[0].email);
   18
     pm.expect(responseJson.name).to.eql(allRows[0].name);
   19
   });

4. Click Send.

When the request runs, the script queries the dataset and compares the response data with the matching row. Query results return rows as an async iterable, so use the for await...of loop to read the returned rows. You can also use executeView() to validate responses against a predefined view instead of writing a custom query in the script.

Learn more about writing pre-request scripts and post-response scripts, and using datasets in scripts.