Dataset commands

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.

Each dataset command works with either a local dataset file or a cloud dataset stored in a Postman workspace:

Local — Specify the path to a .dataset.yaml file.
Cloud — Specify the dataset’s ID.

A dataset stores a definition, not your data: where the data lives, what each source is named, and the SQL that shapes your views. It doesn’t copy your rows into the manifest, which is why a .dataset.yaml file stays small.

A view stores only its query. Rows are recomputed from the source each time you run it.
A source is a pointer to your data: a database connection or a file path. Two cases store a copy instead:
- Adding a local file copies it into a .resources/ folder next to the dataset.
- Uploading a file to a cloud dataset stores the file in Postman.

To run a collection with a dataset or a saved view, use the --iteration-data-dataset, --iteration-data-view, and --dataset options with the postman collection run command. To learn more, see Collection commands.

`postman dataset create`

Creates a new dataset.

To use this command with a cloud dataset, sign in to Postman with the postman login command, or pass the --api-key <key> option to use a specific API key.

Usage

$ postman dataset create [local-dataset-path] [options]

[local-dataset-path]

To create a local dataset file, provide the path where you want to create it. To create a cloud dataset, omit this argument and use the -w, --workspace option instead.

Options

-n, --name <name>

Required

The dataset name.

-d, --description <description>

A description for the dataset.

--dataset-id <uuid>

Defaults to Random v4 UUID

(Local only) Unique identifier for the dataset. If not provided, a random v4 UUID is generated. A cloud dataset assigns its own ID.

-w, --workspace <id>

The Postman workspace ID in which to create a cloud dataset.

--force

Overwrites an existing dataset file.

Examples

$ postman dataset create ./postman/datasets/customers.dataset.yaml \
>   -n "Customer Data"
$ 
$ postman dataset create \
>   -w 12345678-90ab-cdef-1234-567890abcdef \
>   -n "Customer Data"

`postman dataset list`

Lists datasets.

To use this command with a cloud dataset, sign in to Postman with the postman login command, or pass the --api-key <key> option to use a specific API key.

Usage

$ postman dataset list [local-dataset-path] [options]

[local-dataset-path]

To list local datasets, provide the path to a dataset file or a directory that contains one or more dataset files. To list cloud datasets, omit this argument and use the -w, --workspace option instead.

Options

-w, --workspace <id>

The Postman workspace ID whose cloud datasets you want to list.

--json

Displays results in JSON format.

Examples

$ postman dataset list ./postman/datasets
$ 
$ postman dataset list ./postman/datasets/customers.dataset.yaml
$ 
$ postman dataset list -w 12345678-90ab-cdef-1234-567890abcdef

`postman dataset get`

Displays metadata and a structure summary for a dataset.

To use this command with a cloud dataset, sign in to Postman with the postman login command, or pass the --api-key <key> option to use a specific API key.

Usage

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

<dataset-path-or-id>

Path to a local dataset file or a cloud dataset ID.

Options

--no-populate

(Cloud only) Skips fetching the dataset’s data sources and views, returning only its top-level metadata. If you don’t need the full structure, this can help make the command faster.

--json

Displays results in JSON format.

Examples

$ postman dataset get ./postman/datasets/customers.dataset.yaml
$ 
$ postman dataset get 14e30f6c-1234-1234-1234-cafef00dc0de

`postman dataset query`

Runs a SQL query against a dataset.

To use this command with a cloud dataset, sign in to Postman with the postman login command, or pass the --api-key <key> option to use a specific API key.

Usage

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

<dataset-path-or-id>

Path to a local dataset file or a cloud dataset ID.

Options

-q, --query <query>

Required

The SQL query to run.

-p, --param <parameter>

Provides a value for a positional placeholder in the query. The first -p value fills $1, the second fills $2, and so on. Repeat the option to pass multiple values, 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 id = $1" \
>   -p 42
$ 
$ postman dataset query 14e30f6c-1234-1234-1234-cafef00dc0de \
>   -q "SELECT * FROM customers LIMIT 10"

`postman dataset source`

Manage the data sources associated with a dataset.

A dataset can contain multiple data sources. You specify the dataset with the -d, --dataset option, and commands that act on a specific source also take its name or ID as an argument.

To use these commands with a cloud dataset, sign in to Postman with the postman login command, or pass the --api-key <key> option to use a specific API key.

`postman dataset source list`

Lists the data sources associated with a dataset.

Usage

$ postman dataset source list [options]

Options

-d, --dataset <dataset-path-or-id>

Required

Path to a local dataset file or a cloud dataset ID.

--json

Displays results in JSON format.

Examples

$ postman dataset source list -d ./postman/datasets/customers.dataset.yaml
$ 
$ postman dataset source list -d 14e30f6c-1234-1234-1234-cafef00dc0de

`postman dataset source add`

Adds a data source to a dataset.

Usage

$ postman dataset source add [options]

Options

-d, --dataset <dataset-path-or-id>

Required

Path to a local dataset file or a cloud dataset ID.

-n, --name <name>

Required

The data source name. This becomes the SQL table name.

--source-id <uuid>

Defaults to Random v4 UUID

(Local only) Unique identifier for the data source. If not provided, a random v4 UUID is generated. A cloud dataset assigns its own source ID.

--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. For a cloud dataset, the file is registered as a local file source unless you also pass --upload.

--format <format>

'csv' | 'json' | 'mysql' | 'postgres'

Overrides the format the CLI infers for the data source. By default, the format comes from the file extension (.csv or .json) or the source type.

--upload

(Cloud only) Uploads the file from --file to Postman and stores it as a cloud file source. Without --upload, the file stays on your computer and is registered as a local file source instead.

--ref-only

(Local only) References the source file in place without copying it into the dataset resources directory.

--force

(Local only) Overwrites a file of the same name that’s already in the dataset’s resources directory. Use this when you’re replacing a source file you added before. Without it, the copy fails because the file already exists.

The following options configure a database source and apply only with --type mysql or --type postgresql.

--host <host>

Required

Database host name.

--port <port>

Required

Database port number.

--user <user>

Required

Database user name.

--password <password>

Required

Database password.

--database <database>

Required

Database name.

--table <table>

Database table name.

Passing --user or --password on the command line stores the value as plain text in the dataset file (for a local dataset) or sends it in the request body (for a cloud dataset), and exposes it in your shell history and process list. Because these credentials aren’t protected, use a database account limited to read-only access to only the data this source needs, rather than a privileged account.

Examples

$ postman dataset source add -d ./postman/datasets/customers.dataset.yaml \
>   --name customers \
>   --file customers.csv
$ 
$ postman dataset source add -d 14e30f6c-1234-1234-1234-cafef00dc0de \
>   --name customers \
>   --file customers.csv \
>   --upload
$ 
$ postman dataset source add -d ./postman/datasets/customers.dataset.yaml \
>   --name production-db \
>   --type postgresql \
>   --host db.example.com \
>   --port 5432 \
>   --user readonly_user \
>   --password '••••' \
>   --database customers

`postman dataset source update`

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

Usage

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

<data-source>

The data source name or unique identifier.

Options

-d, --dataset <dataset-path-or-id>

Required

Path to a local dataset file or a cloud dataset ID.

To update the source configuration, this command supports the same options as postman dataset source add. You can update connection details for a database source, or change the file for a file-based source.

Examples

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

`postman dataset source remove`

Removes a data source from a dataset.

Usage

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

<data-source>

The data source name or unique identifier.

Options

-d, --dataset <dataset-path-or-id>

Required

Path to a local dataset file or a cloud dataset ID.

Examples

$ postman dataset source remove customers \
>   -d ./postman/datasets/customers.dataset.yaml
$ 
$ postman dataset source remove customers \
>   -d 14e30f6c-1234-1234-1234-cafef00dc0de

`postman dataset view`

Dataset view commands enable you to create, manage, and run saved SQL queries. A dataset can contain multiple views. You specify the dataset with the -d, --dataset option, and commands that act on a specific view also take the view’s name or ID as an argument. To learn more, see Example dataset views in Postman.

To use these commands with a cloud dataset, sign in to Postman with the postman login command, or pass the --api-key <key> option to use a specific API key.

`postman dataset view list`

Lists saved views in a dataset.

Usage

$ postman dataset view list [options]

Options

-d, --dataset <dataset-path-or-id>

Required

Path to a local dataset file or a cloud dataset ID.

--json

Displays results in JSON format.

Examples

$ postman dataset view list -d ./postman/datasets/customers.dataset.yaml
$ 
$ postman dataset view list -d 14e30f6c-1234-1234-1234-cafef00dc0de

`postman dataset view create`

Saves a view to a dataset.

Usage

$ postman dataset view create [options]

Options

-d, --dataset <dataset-path-or-id>

Required

Path to a local dataset file or a cloud dataset ID.

-n, --name <name>

Required

The view name.

-q, --query <query>

Required

The SQL query.

--view-id <uuid>

Defaults to Random v4 UUID

(Local only) Unique identifier for the view. If not provided, a random v4 UUID is generated. A cloud dataset assigns its own view ID.

Examples

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

`postman dataset view update`

Updates a saved view. Only the options you provide are updated.

Usage

$ postman dataset view update <view> [options]

<view>

The view name or unique identifier.

Options

-d, --dataset <dataset-path-or-id>

Required

Path to a local dataset file or a cloud dataset ID.

-n, --name <name>

A new name for the view.

-q, --query <query>

A new SQL query for the view.

Examples

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

`postman dataset view delete`

Deletes a saved view from a dataset.

Usage

$ postman dataset view delete <view> [options]

<view>

The view name or unique identifier.

Options

-d, --dataset <dataset-path-or-id>

Required

Path to a local dataset file or a cloud dataset ID.

Examples

$ postman dataset view delete active-customers \
>   -d ./postman/datasets/customers.dataset.yaml
$ 
$ postman dataset view delete active-customers \
>   -d 14e30f6c-1234-1234-1234-cafef00dc0de

`postman dataset view run`

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

Usage

$ postman dataset view run <view> [options]

<view>

The view name or unique identifier.

Options

-d, --dataset <dataset-path-or-id>

Required

Path to a local dataset file or a cloud dataset ID.

-p, --param <parameter>

Provides a value for a positional placeholder in the view’s query. The first -p value fills $1, the second fills $2, and so on. Repeat the option to pass multiple values, for example -p value1 -p value2.

--json

Displays query results in JSON format.

Examples

$ postman dataset view run active-customers \
>   -d ./postman/datasets/customers.dataset.yaml
$ 
$ postman dataset view run active-customers \
>   -d 14e30f6c-1234-1234-1234-cafef00dc0de

`postman dataset delete`

Deletes a dataset.

To use this command with a cloud dataset, sign in to Postman with the postman login command, or pass the --api-key <key> option to use a specific API key.

Usage

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

<dataset-path-or-id>

Path to a local dataset file or a cloud dataset ID.

Options

-y, --yes

Skips the confirmation prompt.

--keep-resources

(Local only) Deletes the dataset file but preserves the associated resources directory, which holds your copied source files. Use this when you want to remove the dataset definition but keep its data, or when another dataset in the same directory shares those files.

Examples

$ postman dataset delete ./postman/datasets/customers.dataset.yaml
$ 
$ postman dataset delete ./postman/datasets/customers.dataset.yaml \
>   -y \
>   --keep-resources
$ 
$ postman dataset delete 14e30f6c-1234-1234-1234-cafef00dc0de -y