Tests and scriptsPostman CLICLI commands

Dataset commands

Beta
View as Markdown

This topic covers dataset commands for the Postman CLI.

Datasets enable you to define reusable data sources and views for use in Postman workflows. You can use dataset commands to create and manage datasets, configure data sources, run SQL queries, and run saved views.

In your CI/CD script, you can use the --iteration-data-dataset, --iteration-data-view, and --dataset options with the postman collection run command to run a collection with a dataset or a saved view. To learn more, see Collection commands.

postman dataset create

Creates a new dataset.

Usage

$postman dataset create <dataset-path> [options]
<dataset-path>

Path where the dataset file will be created.

Options

-n, --name <name>

The dataset name.

-d, --description <description>

A description for the dataset.

--id <uuid>
Defaults to Random v4 UUID

Unique identifier for the dataset. If not provided, a random v4 UUID is generated.

--force

Overwrites an existing dataset file.

Examples

$postman dataset create ./postman/datasets/customers.dataset.yaml \
>  -n "Customer Data"

postman dataset source

Dataset source commands enable you to manage the data sources associated with a dataset.

postman dataset source list

Lists the data sources configured for a dataset.

Usage

$postman dataset source list <dataset-path> [options]
<dataset-path>

Path to a dataset file.

Options

--json

Displays results in JSON format.

Examples

$postman dataset source list ./postman/datasets/customers.dataset.yaml

postman dataset source add

Adds a data source to a dataset.

Usage

$postman dataset source add <dataset-path> [options]
<dataset-path>

Path to a dataset file.

Options

-n, --name <name>

The data source name.

--id <uuid>
Defaults to Random v4 UUID

Unique identifier for the data source. If not provided, a random v4 UUID is generated.

--format <format>
'csv' | 'json' | 'mysql' | 'postgres'

Update the default format for the data source.

--type <type>
'local' | 'mysql' | 'postgresql'

Specifies the source type. If not provided, the type is inferred from --file.

--file <path>

Path to a local CSV or JSON file to add as a source. If you specify a file, the data source type is set to local.

--ref-only

References the source file without copying it into the dataset resources directory.

--force

Overwrites an existing file when copying a data source file.

--host <host>

Database host name.

--port <port>

Database port number.

--user <user>

Database user name.

--password <password>

Database password.

--database <database>

Database name.

--table <table>

Database table name.

--slug <slug>

Slug for the data source.

Examples

$postman dataset source add ./postman/datasets/customers.dataset.yaml \
>  --name customers \
>  --file customers.csv
$
$postman dataset source add ./postman/datasets/customers.dataset.yaml \
>  --name customers \
>  --file customers.csv \
>  --ref-only
$
$postman dataset source add ./postman/datasets/customers.dataset.yaml \
>  --name production-db \
>  --type postgresql \
>  --host db.example.com \
>  --port 5432 \
>  --database customers \
>  --table customer_records

postman dataset source update

Updates an existing data source. Only the options you provide are updated.

Usage

$postman dataset source update <dataset-path> <data-source> [options]
<dataset-path>

Path to a dataset file.

<data-source>

The data source name or unique identifier.

Options

The postman dataset source update command supports the same options as postman dataset source add for updating the data source configuration. You can use this command to modify connection details for a database source or change the file path for a file-based source.

Examples

$postman dataset source update ./postman/datasets/customers.dataset.yaml \
>  production-db \
>  --host new-db.example.com
$
$postman dataset source update ./postman/datasets/customers.dataset.yaml \
>  production-db \
>  --port 5433

postman dataset source remove

Removes a data source from a dataset.

Usage

$postman dataset source remove <dataset-path> <data-source> [options]
<dataset-path>

Path to a dataset file.

<data-source>

The data source name or unique identifier.

Options

--purge-file

Deletes the local file.

Examples

$postman dataset source remove ./postman/datasets/customers.dataset.yaml customers
$
$postman dataset source remove ./postman/datasets/customers.dataset.yaml \
>  customers \
>  --purge-file

postman dataset list

Lists datasets in a directory or displays summary information for a single dataset.

Usage

$postman dataset list <dataset-path> [options]
<dataset-path>

A path to a dataset file or a directory with one or more dataset files.

Options

--json

Displays results in JSON format.

Examples

$postman dataset list ./postman/datasets
$
$postman dataset list ./postman/datasets/customers.dataset.yaml

postman dataset get

Displays metadata for a dataset.

Usage

$postman dataset get <dataset-path> [options]
<dataset-path>

Path to a dataset file.

Options

--json

Displays results in JSON format.

Examples

$postman dataset get ./postman/datasets/customers.dataset.yaml

postman dataset query

Runs a SQL query against a dataset.

Usage

$postman dataset query <dataset-path> [options]
<dataset-path>

Path to a dataset file.

Options

-q, --query <query>

The SQL query to run.

-p, --param <parameter>

Positional parameters for queries. You can specify multiple parameters by repeating this option. For example: -p value1 -p value2.

--json

Displays query results in JSON format.

Examples

$postman dataset query ./postman/datasets/customers.dataset.yaml \
>  -q "SELECT * FROM customers LIMIT 10"
$
$postman dataset query ./postman/datasets/customers.dataset.yaml \
>  -q "SELECT * FROM customers WHERE status = ?" \
>  -p active

postman dataset view

Dataset view commands enable you to create, manage, and run saved SQL queries. To learn more, see Example dataset views in Postman.

postman dataset view list

Lists saved views in a dataset.

Usage

$postman dataset view list <dataset-path> [options]
<dataset-path>

Path to a dataset file.

Options

--json

Displays results in JSON format.

Examples

$postman dataset view list ./postman/datasets/customers.dataset.yaml

postman dataset view create

Saves a view to a dataset.

Usage

$postman dataset view create <dataset-path> [options]
<dataset-path>

Path to a dataset file.

Options

-n, --name <name>

The view name.

-q, --query <query>

The SQL query.

--id <uuid>
Defaults to Random v4 UUID

Unique identifier for the view. If not provided, a random v4 UUID is generated.

Examples

$postman dataset view create ./postman/datasets/customers.dataset.yaml \
>  -n "active-customers" \
>  -q "SELECT * FROM customers WHERE active = true"

postman dataset view update

Updates a saved view.

Usage

$postman dataset view update <dataset-path> <view> [options]
<dataset-path>

Path to a dataset file.

<view>

The view name or unique identifier.

Options

-n, --name <name>

The view name.

-q, --query <query>

The SQL query.

Examples

$postman dataset view update ./postman/datasets/customers.dataset.yaml \
>  active-customers \
>  --name current-customers
$
$postman dataset view update ./postman/datasets/customers.dataset.yaml \
>  active-customers \
>  --query "SELECT * FROM customers WHERE status='active'"

postman dataset view delete

Deletes a saved view from a dataset.

Usage

$postman dataset view delete <dataset-path> <view>
<dataset-path>

Path to a dataset file.

<view>

The view name or unique identifier.

Examples

$postman dataset view delete ./postman/datasets/customers.dataset.yaml active-customers

postman dataset view run

Runs a saved view against a dataset and displays the rows.

Usage

$postman dataset view run <dataset-path> <view> [options]
<dataset-path>

Path to a dataset file.

<view>

The view name or unique identifier.

Options

-p, --param <parameter>

Positional parameters for queries. You can specify multiple parameters by repeating this option. For example: -p value1 -p value2.

--json

Displays query results in JSON format.

Examples

$postman dataset view run ./postman/datasets/customers.dataset.yaml active-customers

postman dataset delete

Deletes a dataset.

Usage

$postman dataset delete <dataset-path> [options]
<dataset-path>

Path to a dataset file.

Options

-y, --yes

Skips the confirmation prompt.

--keep-resources

Deletes the dataset file but preserves the associated resources directory.

Examples

$postman dataset delete ./postman/datasets/customers.dataset.yaml
$
$postman dataset delete ./postman/datasets/customers.dataset.yaml \
>  -y \
>  --keep-resources