Introduction

Both tf.train.Example and tf.train.SequenceExample can serialize TensorFlow training data, but they model structure differently. For variable-length sequential features, SequenceExample usually provides cleaner schema and easier parsing. The main benefit is explicit separation between sample-level context and per-step feature lists.

Structural Difference

Example is one flat feature map. It works well for fixed-size tabular features.

SequenceExample contains two parts:

• 'context for fields that apply to the whole sample.'
• 'feature_lists for ordered per-step values.'

This maps naturally to time series, token sequences, click streams, and audio frames.

Why SequenceExample Is Better For Variable Length

Main advantages for sequence tasks:

• You do not need custom conventions to encode step boundaries.
• Parsing functions already understand sequence semantics.
• Data contracts are clearer for teams.
• Padding and batching workflows become simpler.

With flat Example, teams often pack sequences into ad hoc list fields, then write extra parsing code that is easy to break.

Write A SequenceExample

1import tensorflow as tf
2
3seq = tf.train.SequenceExample()
4seq.context.feature["label"].int64_list.value.append(1)
5seq.context.feature["session_id"].bytes_list.value.append(b"s-100")
6
7for token in [12, 51, 9, 3]:
8    f = seq.feature_lists.feature_list["token_ids"].feature.add()
9    f.int64_list.value.append(token)
10
11for score in [0.9, 0.8, 0.6, 0.95]:
12    f = seq.feature_lists.feature_list["confidence"].feature.add()
13    f.float_list.value.append(score)
14
15serialized = seq.SerializeToString()
16print(len(serialized))

This keeps global label fields separate from variable-length token stream fields.

Parse It Cleanly

1import tensorflow as tf
2
3context_spec = {
4    "label": tf.io.FixedLenFeature([], tf.int64),
5    "session_id": tf.io.FixedLenFeature([], tf.string),
6}
7
8sequence_spec = {
9    "token_ids": tf.io.FixedLenSequenceFeature([], tf.int64),
10    "confidence": tf.io.FixedLenSequenceFeature([], tf.float32),
11}
12
13ctx, seq = tf.io.parse_single_sequence_example(
14    serialized,
15    context_features=context_spec,
16    sequence_features=sequence_spec,
17)
18
19print(ctx["label"], ctx["session_id"])
20print(seq["token_ids"], seq["confidence"])

Parser output now reflects sequence-aware design directly.

tf.data Pipeline Integration

SequenceExample works naturally with TFRecord and dataset mapping.

1import tensorflow as tf
2
3
4def parse_fn(record_bytes):
5    ctx, seq = tf.io.parse_single_sequence_example(
6        record_bytes,
7        context_features={"label": tf.io.FixedLenFeature([], tf.int64)},
8        sequence_features={"token_ids": tf.io.FixedLenSequenceFeature([], tf.int64)},
9    )
10    return seq["token_ids"], ctx["label"]
11
12# ds = tf.data.TFRecordDataset(["train.tfrecord"]).map(parse_fn)

This makes input pipelines consistent with sequence model inputs.

When Flat Example Is Still Fine

Use plain Example when data is not sequence-oriented.

• fixed-length embeddings,
• tabular scalar and categorical features,
• no timestep alignment requirements.

Choosing SequenceExample without real sequential semantics can add unnecessary complexity.

Schema Evolution Benefits

SequenceExample also helps long-term schema evolution because context and per-step features evolve independently. For example, you can add a new context feature such as locale without touching sequence feature parsing logic.

Documenting this separation makes migrations safer in multi-team data pipelines.

Practical Guidance

• Keep sample metadata in context.
• Keep aligned time-step values in matching feature_lists.
• Validate that aligned sequence feature lists have same length when expected.
• Version schemas explicitly for backward compatibility.
• Test parser changes with old and new records.

Migration Tip From Flat Records

If your current data uses flat Example records with packed list features, migrate gradually. Start by writing dual readers in input pipeline, then switch new data generation to SequenceExample. During overlap period, compare parsed tensors from both formats in validation jobs to prove semantic equivalence before full cutover.

Common Pitfalls

• Putting sequence data into context fields and losing order semantics.
• Mixing per-step and global fields in a flat Example schema.
• Forgetting to validate sequence length alignment across feature lists.
• Treating parser code as stable while changing serialization format silently.
• Using fixed-length specs for genuinely variable-length sequence fields.

Summary

• 'SequenceExample is usually the better choice for variable-length ordered features.'
• It cleanly separates context metadata from per-step values.
• Parsing is clearer with sequence-aware TensorFlow IO APIs.
• It simplifies batching and sequence model input preparation.
• Use plain Example only when your data is fundamentally non-sequential.