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 Customer Dataset with a local CSV file source named source_customers that includes the following data:

customer_id,first_name,last_name,email,country,signup_date,status
cus_001,Avery,Johnson,avery.johnson001@example.com,United States,2025-01-01,active
cus_002,Mina,Johnson,mina.johnson002@example.com,India,2025-01-02,active
cus_003,Leo,Johnson,leo.johnson003@example.com,France,2025-01-03,active
cus_004,Sofia,Johnson,sofia.johnson004@example.com,Spain,2025-01-04,inactive
cus_005,Noah,Johnson,noah.johnson005@example.com,Canada,2025-01-05,pending

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 {{Customer Dataset}} as a path parameter in your request URL GET /customers/{{Customer 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

Use executeQuery() to run a SQL query with parameters, then read the returned rows with a for await...of loop. The following example uses an email from the current iteration, so it runs during a collection run, monitor run, or private runner run, including runs started with the Postman CLI. Values from pm.iterationData are available only during a run.

const ds = pm.datasets("customer-dataset-id");
const result = await ds.executeQuery(
  "SELECT * FROM source_customers 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.

Write to a database source

When your dataset includes a database source, you can run write statements against it, such as INSERT, UPDATE, and DELETE, in addition to reads. This is useful when you need to prepare data in a database before a run, such as seeding the records your API reads during a test.

To run a write against a database source, pass the { source } option with the source’s name. The statement runs directly against the connected database, in its native SQL dialect, and changes its live data. For more information, see Query a database source directly.

The following example inserts a row into an orders database source in the dataset:

const ds = pm.datasets("customer-dataset-id");
await ds.executeQuery(
  "INSERT INTO orders (order_id, customer_id, amount) VALUES (?, ?, ?)",
  ["ord_104", "cus_005", 40.00],
  { source: "orders" }
);

Postman uses the connected database’s own access control to determine what a query can do. To prevent writes, connect the database source with a database user that has read-only permissions.

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. Set up a request to an endpoint that returns customer data, such as:

   GET /customers/cus_002

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("customer-dataset-id");
   const responseJson = pm.response.json();
   const result = await ds.executeQuery(
     "SELECT customer_id, first_name, last_name, email, status FROM source_customers WHERE customer_id = ?",
     [responseJson.customer_id]
   );
   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.first_name).to.eql(allRows[0].first_name);
     pm.expect(responseJson.status).to.eql(allRows[0].status);
   });

3. Click Send.

When the request runs, the script queries the dataset and compares the response data with the matching row. The Response matches dataset test passes when the response’s email, first_name, and status match the dataset row. It fails if any value differs, or if no row matches the response’s customer_id, which flags a mismatch between the API and the expected data.

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 /customer
     if (method === "GET" && pathname === "/customer") {
       const ds = pm.datasets("customer-dataset-id");
       const result = await ds.executeQuery(
         "SELECT customer_id, first_name, last_name, email, country, status FROM source_customers WHERE customer_id = ?",
         [query.customerId]
       );
       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: "Customer 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/customer?customerId=cus_002

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.