Introduction

tf.train.Example and tf.train.SequenceExample are both TensorFlow protocol buffer messages used to serialize training data, often inside TFRecord files. The difference is not about file format quality; it is about the shape of the data you need to store.

Use Example for Fixed-Shape Records

Example is the simpler structure. It stores one map of feature names to values, where each value is one of TensorFlow's basic list types:

• 'BytesList'
• 'FloatList'
• 'Int64List'

This works well when each record has the same logical fields, such as:

• one image and one label
• one row of tabular features
• one text field plus one class id

Here is a minimal runnable example:

1import tensorflow as tf
2
3example = tf.train.Example(
4    features=tf.train.Features(
5        feature={
6            "age": tf.train.Feature(int64_list=tf.train.Int64List(value=[34])),
7            "income": tf.train.Feature(float_list=tf.train.FloatList(value=[72000.0])),
8            "city": tf.train.Feature(bytes_list=tf.train.BytesList(value=[b"Toronto"])),
9        }
10    )
11)
12
13serialized = example.SerializeToString()
14print(len(serialized))

Everything belongs to one flat record. If a feature is multi-valued, you still store it as a list, but conceptually it remains part of a single example.

Use SequenceExample for Ordered Variable-Length Data

SequenceExample adds structure for sequences. It separates data into:

• 'context, for features that describe the whole record'
• 'feature_lists, for ordered features that change over time or by step'

This is useful for:

• sentences represented as token sequences
• clickstream events
• frame-level video features
• time series with per-step measurements

Example:

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

The steps feature is ordered. That is the key difference: SequenceExample understands that some features are sequences rather than plain per-record attributes.

How To Choose Between Them

Ask two questions:

1. Does each record have one fixed set of fields?
2. Or does each record contain an ordered series of per-step values?

If the answer to the first question is yes, use Example. If the answer to the second question is yes, use SequenceExample.

There is some overlap. You can sometimes force sequence data into Example by storing padded arrays or serialized tensors. But that usually makes parsing less explicit and harder to maintain.

SequenceExample becomes particularly useful when lengths vary across records. For example, one sentence may have 5 tokens and another may have 30. Representing both naturally is much cleaner with feature_lists.

Parsing Differences

The parsing APIs reflect the structural difference. Example is parsed with fixed or variable-length feature specs. SequenceExample uses separate specs for context features and sequence features.

1import tensorflow as tf
2
3context_spec = {
4    "user_id": tf.io.FixedLenFeature([], tf.int64),
5    "label": tf.io.FixedLenFeature([], tf.int64),
6}
7
8sequence_spec = {
9    "steps": tf.io.FixedLenSequenceFeature([], tf.int64),
10}
11
12# serialized must be a scalar string tensor
13# context, sequence = tf.io.parse_single_sequence_example(
14#     serialized,
15#     context_features=context_spec,
16#     sequence_features=sequence_spec,
17# )

That separation is valuable because it keeps metadata and sequential features distinct.

Storage and Pipeline Considerations

Both messages can be written to TFRecord files and consumed with tf.data.TFRecordDataset. So the operational pipeline is similar:

• serialize records
• write them to TFRecord
• read them with a dataset
• parse each record into tensors

The difference is in how much structure you preserve. If your model depends on order, sequence length, or per-step alignment, SequenceExample usually maps more directly to the training task.

Common Pitfalls

One common mistake is using Example for variable-length sequential data and then manually inventing padding and masking rules too early. That works, but it hides the fact that the data is sequential.

Another pitfall is misunderstanding FeatureList. It is not just "a list field"; it is an ordered list of feature entries, typically one entry per timestep.

It is also easy to mix record-level metadata into the sequence itself. Values like labels, ids, or global attributes usually belong in context, not in feature_lists.

Finally, remember that both formats store only primitive feature containers. If you need complex nested objects, you still need a clear serialization strategy on top of these message types.

Summary

• 'Example is best for flat, fixed-shape records with one logical set of features.'
• 'SequenceExample is best for ordered, variable-length sequence data with shared metadata.'
• 'context stores record-level attributes, while feature_lists stores per-step values.'
• Both can live in TFRecord files and work with the same input pipeline style.
• Choose the format that matches the natural structure of the data instead of forcing one shape into another.