Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Java Stream flatMap: Flatten Nested Collections

Understand Java Stream flatMap: its syntax, how it flattens nested collections, and when to choose it over map, with practical examples.

~5 min readJava
#Java Streams#flatMap#Functional Programming#Stream API
Illustration of Java stream flatMap flattening nested collections into a single stream

When you work with Java streams, you often encounter collections nested inside collections. For example, a list of orders, each containing a list of line items. To process every line item across all orders, you need to flatten the structure. The flatMap method on Stream does exactly that: it maps each element to a stream and then concatenates those streams into a single stream. This article explains how Java Stream flatMap works, where it fits, and how to avoid common mistakes.

What flatMap Does in a Java Stream

The flatMap method is defined on the Stream interface. For a stream of type Stream<T>, it accepts a Function<? super T, ? extends Stream<? extends R>> and returns a Stream<R>. For each element in the source stream, the function returns a new stream. These resulting streams are then merged into one output stream. In effect, flatMap flattens the structure one level deeper than map.

Consider a simple example: you have a list of sentences and want to extract all distinct words. Each sentence is a String, and splitting it produces an array of words, which Arrays.stream converts into a Stream<String>. Using flatMap lets you process each word individually:

java
List<String> sentences = Arrays.asList( "the quick brown fox", "jumps over the lazy dog" ); long wordCount = sentences.stream() .flatMap(sentence -> Arrays.stream(sentence.split("\\s+"))) .distinct() .count(); System.out.println(wordCount); // 8

Here, sentence.split("\\s+") returns a String[], which is converted to a Stream<String> via Arrays.stream. The flatMap call concatenates the two word streams into one, allowing distinct() and count() to operate across all words.

flatMap vs map: When the Difference Matters

The map method transforms each element into another object, but it does not flatten. If you use map on the sentence example, you get a Stream<Stream<String>>—a stream of streams, which is rarely what you need. flatMap is the correct choice when the mapping function itself returns a stream, an array, or another collection that you want to merge into the main stream.

A simple rule: if your mapping function returns a stream, array, or collection that you want to process further as one stream, use flatMap. If it returns a single value, use map. For instance, to get the length of each sentence, map is appropriate:

java
List<Integer> lengths = sentences.stream() .map(String::length) .collect(Collectors.toList());

But to get all characters from all sentences, you need flatMap because each sentence produces multiple characters.

Flattening a List of Lists with flatMap

A typical use case is flattening a list of lists into a single list. Suppose you have a list of List<Integer> and want to collect all integers into one list:

java
List<List<Integer>> listOfLists = Arrays.asList( Arrays.asList(1, 2), Arrays.asList(3, 4, 5), Collections.emptyList() ); List<Integer> flattened = listOfLists.stream() .flatMap(List::stream) .collect(Collectors.toList()); System.out.println(flattened); // [1, 2, 3, 4, 5]

Here, List::stream is a method reference that returns a Stream<Integer> for each inner list. The flatMap concatenates all those streams. Empty lists contribute no elements, so they are naturally ignored. This behavior is useful when you have optional collections that might be empty.

Using flatMap with Optional

flatMap is not limited to streams of collections. It also works with Optional in Java 8+. The Optional.flatMap method takes a function that returns an Optional and flattens the result, avoiding nested Optional<Optional<T>>. This is particularly useful when you have a chain of lookups that may return empty.

For example, consider a User object that has an Optional<Address> and an Address that has an Optional<City>. To get the city of a user, you can use flatMap:

java
Optional<City> city = user.flatMap(User::getAddress) .flatMap(Address::getCity);

If any step returns an empty Optional, the result is empty. This is more concise than using map and then orElse or nested conditionals.

Handling Empty Streams and Nulls

An empty stream from the mapping function contributes no elements, so empty input collections are naturally skipped. In the standard Stream.flatMap API, a mapped stream that is null is also treated as empty. However, explicit code is usually clearer. For example, if you want to avoid relying on that behavior, you can map null strings to Stream.empty():

java
List<String> words = Arrays.asList("apple", null, "banana"); List<String> nonNull = words.stream() .flatMap(word -> word == null ? Stream.empty() : Stream.of(word)) .collect(Collectors.toList());

Optional.flatMap is stricter: its mapper must return an Optional, and returning null from that mapper causes a NullPointerException.

Performance Considerations of flatMap

The main performance cost of flatMap comes from creating and merging streams. Each element in the source stream causes the mapping function to create a new stream, and the intermediate streams are lazily consumed. This is generally efficient for small to medium datasets, but for large streams, consider the overhead of stream creation and the potential for many small streams.

One subtle point: flatMap is lazy, meaning the mapping function is not invoked until the terminal operation starts. This allows short-circuiting operations like findFirst() to stop early. However, if the mapping function performs expensive I/O or computation, the laziness can cause unexpected delays at the terminal point. Also, in a sequential stream, encounter order is preserved, which is important if you rely on the original order.

For very large collections, parallel streams may improve throughput, but only if the mapping function is independent and the stream splitting works well. The overhead of merging streams in parallel can negate gains if the streams are small. Measure performance in your specific context rather than assuming.

Common Mistakes and How to Avoid Them

One frequent mistake is using map when you need flatMap, resulting in a Stream<Stream<T>> that is hard to consume. Another is forgetting that Optional.flatMap does not accept a null result, even though Stream.flatMap treats a null mapped stream as empty. Return an empty stream explicitly when you need to represent no elements.

Another issue is using flatMap on a stream of primitives. For IntStream, LongStream, and DoubleStream, there is no flatMap that returns an object stream directly. You can use boxed() if you need an object stream, or use flatMapToInt, flatMapToLong, and flatMapToDouble to stay on primitive streams. For example, to flatten a list of int[] arrays, you can use flatMapToInt:

java
List<int[]> arrays = Arrays.asList(new int[]{1, 2}, new int[]{3, 4}); int sum = arrays.stream() .flatMapToInt(Arrays::stream) .sum();

This avoids boxing overhead and is more idiomatic for primitive streams.

When to Choose flatMap Over Other Approaches

flatMap is not the only way to flatten collections. You could use nested loops or reduce with addAll, but those are more verbose and less expressive. For example, a nested loop approach:

java
List<Integer> result = new ArrayList<>(); for (List<Integer> list : listOfLists) { result.addAll(list); }

This works, but it is imperative and does not compose well with other stream operations. If you need to filter, transform, or aggregate after flattening, flatMap integrates cleanly with the stream pipeline.

However, if you are only flattening a fixed structure and do not need further stream processing, a simple loop may be more readable. The choice depends on whether you value declarative style and composability over imperative brevity. For most data processing tasks, flatMap is the idiomatic Java stream solution.

Try matching browser tools

All tools

Small utilities that fit Java work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Java guides

More in Java

All Java guides

The guides filed next to this one in Java, in library order.