Query datasets from scripts and mocks in Postman

You can query a dataset at runtime with the pm.datasets function in pre-request and post-response scripts and in mock implementations. This is useful when you need data beyond what a selected view exposes as iteration variables, such as looking up a row by a value from the current request, response, or iteration.

Use executeQuery() to run a SQL query, or executeView() to run a saved view instead of writing a query in the script. Query results return rows as an async iterable, so use a for await...of loop to read them. Learn more in the pm.datasets reference.

Example dataset

In the following examples, assume you have a dataset named users-dataset with a local CSV file data source that includes userId, email, and name fields:

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

Reference a dataset in a script

To query a dataset, load it with pm.datasets() using the dataset’s ID. You can reference a dataset, source, or view anywhere in a request, including the base URL, auth, path parameters, headers, and body. Use the {{variable}} syntax, where variable is the name of the entity. For example, you can enter {{users-dataset}} as a path parameter in your request URL GET /users/{{users-dataset}}. Postman resolves the variable to the entity’s ID when the request runs, so you can access it in a script without hard-coding the ID.

const datasetId = // Get the dataset ID from the URL, headers, or another source
const ds = pm.datasets(datasetId);

Query a dataset in a script

During a collection run or monitor run, you can query the dataset using values from the current iteration. Use executeQuery() to run a SQL query with parameters, then read the returned rows with a for await...of loop.

const ds = pm.datasets("users-dataset-id");
const result = await ds.executeQuery(
  "SELECT * FROM users WHERE email = ?",
  [pm.iterationData.get("email")]
);
const allRows = [];
for await (const row of result.rows) {
  allRows.push(row);
}
console.log(JSON.stringify(allRows));

You can also use executeView() to run a saved view instead of writing a custom query in the script.

Validate a response against a dataset

You can query a dataset in a post-response script to validate response data against the data stored in the dataset. This works in individual requests and monitors, enabling you to compare API responses with expected values, test multiple scenarios, and reuse the same data across workflows.

Use the following example to validate a response against a dataset:

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

   GET /user?userId=2

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

   const ds = pm.datasets("users-dataset-id");
   const responseJson = pm.response.json();
   const result = await ds.executeQuery(
     "SELECT userId, email, name FROM users WHERE userId = ?",
     [responseJson.userId]
   );
   const allRows = [];
   for await (const row of result.rows) {
     allRows.push(row);
   }
   pm.test("Response matches dataset", function () {
     pm.expect(allRows.length).to.eql(1);
     pm.expect(responseJson.email).to.eql(allRows[0].email);
     pm.expect(responseJson.name).to.eql(allRows[0].name);
   });

3. Click Send.

When the request runs, the script queries the dataset and compares the response data with the matching row.

Query a dataset in a mock

You can use pm.datasets in a mock 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 query a dataset in a mock:

1. In your mock implementation file, load the dataset using pm.datasets().

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

   const http = require("http");
   const url = require("url");
   const PORT = process.env.PORT || 4500;
   const server = http.createServer(async (req, res) => {
     const { method } = req;
     const { pathname, query } = url.parse(req.url, true);
     // @endpoint GET /user
     if (method === "GET" && pathname === "/user") {
       const ds = pm.datasets("users-dataset-id");
       const result = await ds.executeQuery(
         "SELECT userId, email, name FROM users WHERE userId = ?",
         [query.userId]
       );
       const allRows = [];
       for await (const row of result.rows) {
         allRows.push(row);
       }
       if (allRows.length === 0) {
         res.writeHead(404, { "Content-Type": "application/json" });
         return res.end(JSON.stringify({ error: "User not found" }));
       }
       res.writeHead(200, { "Content-Type": "application/json" });
       return res.end(JSON.stringify(allRows[0]));
     }
     res.writeHead(404, { "Content-Type": "application/json" });
     res.end(JSON.stringify({ error: "Endpoint not defined" }));
   });
   server.listen(PORT, () => {
     console.log(`Mock server running on port ${PORT}`);
   });

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

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

The mock queries the dataset when the request runs and returns the matching data in the response.

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