Java: What is the difference between Stream.flatMap() and Stream.map()?

map() — one-to-one transformation: each element produces exactly one result. flatMap() — one-to-many transformation: each element produces a stream of results, and all streams are flattened into one. Think of map() as a vending machine (one coin → one snack), while flatMap() is a bulk dispenser (one coin → a bag of snacks).

map():

• Each element → one result.
• Returns Stream<R>.
• No flattening — output structure mirrors input structure.

1// Each word → one length
2List<Integer> lengths = words.stream()
3    .map(String::length)
4    .toList();
5// Input: ["hello", "world"] → Output: [5, 5]

flatMap():

• Each element → Stream of results.
• Flattens all sub-streams into one.
• Returns Stream<R>.

1// Each sentence → multiple words
2Stream<String> words = sentences.stream()
3    .flatMap(s -> Arrays.stream(s.split(" ")));
4
5// Flatten nested lists
6List<Integer> flat = nested.stream()
7    .flatMap(Collection::stream)
8    .toList();

When to use flatMap:

• Flattening nested collections (List<List<T>> → List<T>).
• Splitting strings into characters or words.
• Exploding a single record into multiple records (e.g., User with multiple Roles).
• Optional.flatMap() for chaining nullable computations.
• Processing database relationships (one-to-many).

1// Real-world: flatten order items
2List<OrderItem> allItems = orders.stream()
3    .flatMap(order -> order.getItems().stream())
4    .collect(Collectors.toList());
5
6// Real-world: get all unique tags
7Set<String> allTags = articles.stream()
8    .flatMap(a -> a.getTags().stream())
9    .collect(Collectors.toSet());

Performance considerations:

• flatMap has slightly more overhead than map due to sub-stream creation.
• For deeply nested structures, flatten incrementally rather than all at once.
• flatMap preserves encounter order — first sub-stream's elements come before second.

Key difference:

• map() — transform, one-to-one.
• flatMap() — transform + flatten, one-to-many.