Introduction

tf.train.SequenceExample is useful when each training example contains a sequence of items and each item may itself contain structured numeric data. The tricky part with multidimensional arrays is that SequenceExample stores scalar lists, so you typically flatten each time-step array, store its shape separately, and reshape it again when parsing.

How SequenceExample Is Structured

A SequenceExample has two parts:

• 'context for features that describe the whole example,'
• 'feature_lists for sequence data where each step can have its own feature values.'

That maps well to data such as:

• a sequence of image embeddings,
• a sequence of sensor matrices,
• a variable-length list of frames or feature vectors.

For multidimensional data, the usual design is:

• keep per-example metadata such as shape in context,
• store each sequence step as a flattened float or int list in feature_lists.

Writing a Sequence of 2D Arrays

Suppose each time step is a 2 x 3 matrix. We can flatten each matrix before storing it.

1import tensorflow as tf
2
3
4def _int64_feature(value):
5    return tf.train.Feature(int64_list=tf.train.Int64List(value=value))
6
7
8def _float_feature(value):
9    return tf.train.Feature(float_list=tf.train.FloatList(value=value))
10
11
12sequence = [
13    [[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]],
14    [[7.0, 8.0, 9.0], [10.0, 11.0, 12.0]],
15]
16
17feature_list = []
18for matrix in sequence:
19    flat = [item for row in matrix for item in row]
20    feature_list.append(_float_feature(flat))
21
22example = tf.train.SequenceExample(
23    context=tf.train.Features(feature={
24        "rows": _int64_feature([2]),
25        "cols": _int64_feature([3]),
26    }),
27    feature_lists=tf.train.FeatureLists(feature_list={
28        "frames": tf.train.FeatureList(feature=feature_list)
29    })
30)
31
32serialized = example.SerializeToString()
33print(len(serialized))

The multidimensional structure is not lost, but it is represented indirectly: flat values plus shape metadata.

Parsing and Reshaping

When reading the serialized record back, parse the flat sequence and then reshape each step to its original dimensions.

1import tensorflow as tf
2
3context_features = {
4    "rows": tf.io.FixedLenFeature([], tf.int64),
5    "cols": tf.io.FixedLenFeature([], tf.int64),
6}
7
8sequence_features = {
9    "frames": tf.io.FixedLenSequenceFeature([6], tf.float32),
10}
11
12context, sequence = tf.io.parse_single_sequence_example(
13    serialized,
14    context_features=context_features,
15    sequence_features=sequence_features,
16)
17
18rows = context["rows"]
19cols = context["cols"]
20frames = sequence["frames"]
21frames = tf.reshape(frames, [-1, rows, cols])
22
23print(frames.shape)
24print(frames)

The FixedLenSequenceFeature([6], tf.float32) part works because each flattened matrix has exactly six values.

Why Flattening Is Usually the Easiest Option

You could store shape information in many different ways, but flattening each step keeps the record format simple. TensorFlow input pipelines generally work best when every step in the sequence has a predictable per-step feature length.

That means SequenceExample is often a good fit for:

• frame embeddings,
• fixed-size per-step sensor windows,
• and any sequence where length varies but inner shape stays stable.

If the inner shape changes too often, the serialization logic and parsing code become much more awkward, which is usually a sign that padding or a different record design may be cleaner.

Common Pitfalls

• Trying to store a multidimensional tensor directly without flattening it into feature values.
• Forgetting to store enough shape metadata to reconstruct the original structure.
• Using FixedLenSequenceFeature even though the flattened size varies between steps.
• Assuming SequenceExample is always the best format when the data is highly irregular.
• Mixing per-example metadata and per-step sequence data without a clear separation between context and feature_lists.

Summary

• 'tf.train.SequenceExample is a good fit for sequence data with per-example metadata and per-step values.'
• For multidimensional arrays, flatten each step before writing and store shape information separately.
• Parse the flat values back with parse_single_sequence_example and reshape them afterward.
• The format works best when each time step has a consistent inner shape.
• If the inner shapes vary too much, padding or a different serialization strategy may be a better choice.