TensorFlow · Module

Dataset.map

Applies a function to every element of a TensorFlow dataset and returns a new dataset of transformed elements. It can also change element structure and optionally process elements in parallel.

How it works

Dataset.map applies a function to each input element and returns another dataset containing the function's results. The function receives the tensors representing one element and may change both element values and structure; optional parallel calls control asynchronous processing.

Syntax

map(map_func, num_parallel_calls=None, deterministic=None, name=None)

Parameters

Name	Type	Description
`map_func`	`function`	Function mapping one dataset element to another dataset element.
`num_parallel_calls`	`tf.int64 scalar Tensor`	Optional scalar tf.int64 tensor specifying the number of elements processed asynchronously in parallel.
`deterministic`	`bool or None`	Optional setting controlling deterministic ordering of parallel results.
`name`	`string or None`	Optional name for the operation.

Returns

A new Dataset containing the transformed elements, in the same order as the input when deterministic ordering is used.

Key points

The transformation invokes map_func separately for every input dataset element.
The original dataset is not modified; map produces a new dataset of results.
The callback may alter element contents and their supported nested structure.
num_parallel_calls controls the asynchronous parallelism level for element processing.
Disabling deterministic ordering can improve throughput when result order is unimportant.
Dataset.map is a tf.data transformation used in input-pipeline preprocessing.

Common mistakes

Leaving num_parallel_calls unset processes elements sequentially, which can reduce throughput for expensive transformations.
Parallel processing can relax output ordering when deterministic=False, so use that only when input order does not matter.
Python-side eager functions require tf.py_function inside the mapping transformation.

Example: Increment dataset elements

import tensorflow as tf

dataset = tf.data.Dataset.range(1, 6)
dataset = dataset.map(lambda x: x + 1)
print(list(dataset.as_numpy_iterator()))

Creates a range dataset, increments every element, and prints the transformed values.

When to use it

Per-element preprocessing

Normalize, decode, resize, or otherwise preprocess each training example before batching.

Project or reshape dataset elements

Convert tuples into selected components or construct new nested element structures.

Parallel input processing

Run independent preprocessing work concurrently to increase input-pipeline throughput.

Interview questions

QWhat does Dataset.map do?

map_func is applied to each element of the input dataset, and map returns a new dataset containing the transformed elements. The function receives the tensors for one element and returns tensors for one element in the result dataset.

Follow-up: How can mapping change a dataset's shape? It can return a different supported element structure, such as selecting only one component from a tuple or producing multiple components.

QHow do you improve map performance?

num_parallel_calls specifies how many elements may be processed asynchronously in parallel. If omitted, processing is sequential; using parallel calls can improve performance for costly per-element work.

Follow-up: When can ordering be relaxed? Set deterministic=False when the application does not require deterministic output order, allowing potentially better throughput.

QCan map change the structure of dataset elements?

map_func can accept and return any type of dataset element supported by TensorFlow's dataset structure rules. This permits changing both values and the structure of elements.

Follow-up: What is a common pipeline optimization after mapping? Cache after map when the mapped result fits the available memory, avoiding repeated preprocessing across epochs.

tf.data.Dataset.batch
tf.data.Dataset.cache
tf.data.Dataset.flat_map
tf.data.Dataset.interleave
tf.data.Dataset.prefetch
tf.py_function

Source: tf.data.Dataset.map. Checked 2026-10-15.