Introduction

tf.train.Example and tf.train.SequenceExample are both protobuf formats used with TFRecord, but they solve different data-shape problems. Example is for one record with named features. SequenceExample is for data that has per-sequence context plus ordered feature lists over time or steps.

The most useful mental model is simple: if one training instance is just a flat bag of features, use Example. If one training instance contains a sequence, such as tokens in a sentence or frames in a clip, use SequenceExample.

Use Example for Flat Records

An Example stores one set of named features. Each feature can hold bytes, floats, or integers.

1import tensorflow as tf
2
3example = tf.train.Example(
4    features=tf.train.Features(
5        feature={
6            "height": tf.train.Feature(int64_list=tf.train.Int64List(value=[28])),
7            "width": tf.train.Feature(int64_list=tf.train.Int64List(value=[28])),
8            "label": tf.train.Feature(int64_list=tf.train.Int64List(value=[3])),
9        }
10    )
11)
12
13serialized = example.SerializeToString()
14print(len(serialized))

This is a good fit for independent examples such as tabular rows, images with one label, or any record where the internal order of values is not the primary structure.

Use SequenceExample for Ordered Features

SequenceExample separates data into:

• context features, which apply to the whole record
• feature lists, which hold ordered per-step values

1import tensorflow as tf
2
3sequence = tf.train.SequenceExample(
4    context=tf.train.Features(
5        feature={
6            "user_id": tf.train.Feature(int64_list=tf.train.Int64List(value=[42]))
7        }
8    ),
9    feature_lists=tf.train.FeatureLists(
10        feature_list={
11            "tokens": tf.train.FeatureList(
12                feature=[
13                    tf.train.Feature(bytes_list=tf.train.BytesList(value=[b"hello"])),
14                    tf.train.Feature(bytes_list=tf.train.BytesList(value=[b"world"]))
15                ]
16            )
17        }
18    )
19)
20
21serialized = sequence.SerializeToString()
22print(len(serialized))

This is the right choice when each example includes an ordered list of elements and that order matters to the model.

Choose Based on the Model Input Shape

A practical rule:

• use Example when each record is already one fixed feature set
• use SequenceExample when each record contains a variable-length sequence with shared context

That means:

• image classification datasets often use Example
• language, speech, clickstream, and event-sequence datasets often fit SequenceExample

You can still store sequences inside an Example if you serialize them yourself, but SequenceExample makes the structure explicit and easier to parse with sequence-aware input pipelines.

Parsing Also Looks Different

The storage choice affects your input pipeline. A flat Example is typically parsed with tf.io.parse_single_example, while sequence-oriented data usually goes through tf.io.parse_single_sequence_example.

1context, sequence = tf.io.parse_single_sequence_example(
2    serialized,
3    context_features={
4        "user_id": tf.io.FixedLenFeature([], tf.int64),
5    },
6    sequence_features={
7        "tokens": tf.io.VarLenFeature(tf.string),
8    },
9)

If your parsing code naturally wants fixed per-record fields plus ordered per-step fields, that is a strong hint that SequenceExample is the better format.

Common Pitfalls

The biggest mistake is using SequenceExample just because a feature happens to be a list. A list of values is not automatically a sequence problem. The real question is whether the record has ordered step-wise structure.

Another common issue is misunderstanding the split between context and feature lists. Context belongs to the whole example. Feature lists belong to the time or step dimension.

It is also easy to overcomplicate the format. If a plain Example already matches the data shape, adding SequenceExample only makes parsing harder.

Finally, remember that these formats are storage containers, not model types. The model still decides how to interpret the parsed tensors.

One more practical hint: if batching requires heavy padding or ragged handling because lengths vary by step, you are usually in SequenceExample territory already.

Summary

• 'Example is for flat per-record features.'
• 'SequenceExample is for records with ordered feature sequences plus shared context.'
• Choose based on the actual shape of one training instance.
• Use context for whole-record metadata and feature lists for per-step data.
• Do not pick SequenceExample unless sequence structure is really part of the problem.