Introduction

In tf.data, batch, shuffle, and repeat are not interchangeable because each transformation changes the unit of data seen by the next one. Changing their order changes what gets shuffled, what gets repeated, and where epoch boundaries appear, so different output sequences are expected rather than surprising.

Why Order Matters

The key idea is that each operation changes the structure of the dataset stream.

• 'batch turns individual elements into groups'
• 'shuffle randomizes whatever units it sees'
• 'repeat duplicates the dataset pipeline in its current form'

So:

• 'shuffle().batch() shuffles individual examples, then groups them'
• 'batch().shuffle() shuffles whole batches, not individual examples inside them'

That is already enough to explain many output differences.

A Tiny Example

Start with a simple dataset:

import tensorflow as tf

base = tf.data.Dataset.from_tensor_slices([0, 1, 2, 3, 4, 5])

Shuffle then batch

pipeline = base.shuffle(6, reshuffle_each_iteration=False).batch(2)
for x in pipeline:
    print(x.numpy())

This produces batches built from already shuffled elements.

Batch then shuffle

pipeline = base.batch(2).shuffle(3, reshuffle_each_iteration=False)
for x in pipeline:
    print(x.numpy())

Now the units being shuffled are the batches themselves. Elements inside each batch remain in their original local order.

That is a fundamentally different pipeline.

repeat() Changes Epoch Semantics

repeat() is another major source of confusion because it changes whether the dataset has a clean end.

pipeline = base.repeat(2)
for x in pipeline:
    print(x.numpy(), end=" ")

This outputs two passes over the dataset back to back.

If you shuffle before repeat:

pipeline = base.shuffle(6, reshuffle_each_iteration=False).repeat(2)

you repeat the same shuffled order twice.

If you repeat before shuffle:

pipeline = base.repeat(2).shuffle(6, reshuffle_each_iteration=False)

the shuffle sees a longer stream where repeated copies can mix together. The result no longer has clean epoch boundaries in the same way.

That difference is often the reason training input looks different even though the same three operations appear in both pipelines.

A More Practical Training Pattern

For many training datasets, a common and sensible order is:

1pipeline = (
2    base
3    .shuffle(buffer_size=1000)
4    .repeat()
5    .batch(32)
6)

Why this order is common:

• individual examples are shuffled before batching
• the dataset can feed multiple epochs continuously
• the model sees mixed examples instead of rigid batch blocks

That does not mean it is the only valid choice, but it matches the goal of stochastic training better than shuffling already-formed batches.

Buffer Size Also Affects the Result

shuffle(buffer_size) does not mean perfect global shuffle unless the buffer is large enough to represent the whole relevant stream.

pipeline = base.shuffle(buffer_size=2, reshuffle_each_iteration=False)
for x in pipeline:
    print(x.numpy(), end=" ")

A small buffer gives only local mixing. So if you compare two pipelines with different operation order and a small shuffle buffer, the differences can become even more pronounced.

That is why understanding the unit of shuffling and the size of the shuffle window matters together.

Batching Before Repeat Can Also Change Partial Batches

If the dataset size is not divisible by the batch size, ordering around batch and repeat changes how partial batches appear.

1base = tf.data.Dataset.from_tensor_slices([0, 1, 2, 3, 4])
2
3pipeline = base.batch(2)
4for x in pipeline:
5    print(x.numpy())

This yields a smaller final batch.

But once repeat is introduced at different points, those boundaries can interact differently with batching and reshuffling behavior.

A Good Mental Model

Think in terms of what the next transformation sees:

• after batch, the next stage sees arrays, not single examples
• after repeat, the next stage may see a longer continuous stream
• after shuffle, downstream stages receive already-randomized units

This mental model is more useful than memorizing one "correct" order.

Common Pitfalls

A common mistake is assuming batch().shuffle() is equivalent to shuffle().batch(). It is not. The shuffled units are different.

Another issue is forgetting that repeat() can blur epoch boundaries when placed before shuffle().

Developers also often expect a full random permutation from a tiny shuffle buffer, which tf.data does not guarantee.

Finally, do not debug these pipelines only by intuition. Print a tiny toy dataset through the exact chain you are using and inspect the output directly.

Summary

• 'batch, shuffle, and repeat are order-sensitive transformations.'
• 'shuffle().batch() shuffles examples, while batch().shuffle() shuffles batches.'
• 'repeat() changes the stream shape and can blur epoch boundaries.'
• Shuffle buffer size affects how random the output really is.
• The right order depends on what unit of data you want each stage to operate on.