Introduction

TFRecord is TensorFlow’s binary record format for storing sequences of serialized examples efficiently. When your source data starts as NumPy arrays, the main question is not whether TFRecord can store them, but how to serialize the array contents and enough metadata to reconstruct the original shape and dtype correctly.

A Practical Pattern: Store Tensor Bytes Plus Metadata

One reliable approach is:

• Convert the NumPy array to a TensorFlow tensor
• Serialize it with tf.io.serialize_tensor
• Store the resulting bytes in a tf.train.Example
• Save shape or label metadata alongside it if needed

This avoids manually flattening and rebuilding arrays unless you specifically want that control.

Write a NumPy Array to TFRecord

Here is a complete example that writes arrays and labels.

1import numpy as np
2import tensorflow as tf
3
4
5def bytes_feature(value):
6    return tf.train.Feature(bytes_list=tf.train.BytesList(value=[value]))
7
8
9def int64_feature(value):
10    return tf.train.Feature(int64_list=tf.train.Int64List(value=[value]))
11
12
13def serialize_example(array, label):
14    tensor_bytes = tf.io.serialize_tensor(tf.convert_to_tensor(array)).numpy()
15    feature = {
16        "array": bytes_feature(tensor_bytes),
17        "label": int64_feature(label),
18    }
19    example = tf.train.Example(features=tf.train.Features(feature=feature))
20    return example.SerializeToString()
21
22arrays = [
23    np.array([[1.0, 2.0], [3.0, 4.0]], dtype=np.float32),
24    np.array([[5.0, 6.0], [7.0, 8.0]], dtype=np.float32),
25]
26labels = [0, 1]
27
28with tf.io.TFRecordWriter("data.tfrecord") as writer:
29    for array, label in zip(arrays, labels):
30        writer.write(serialize_example(array, label))

This stores each array as one record.

Read the TFRecord Back into Tensors

To read the file, define the schema and parse the serialized tensor back.

1import tensorflow as tf
2
3feature_spec = {
4    "array": tf.io.FixedLenFeature([], tf.string),
5    "label": tf.io.FixedLenFeature([], tf.int64),
6}
7
8
9def parse_example(serialized_example):
10    parsed = tf.io.parse_single_example(serialized_example, feature_spec)
11    array = tf.io.parse_tensor(parsed["array"], out_type=tf.float32)
12    label = parsed["label"]
13    return array, label
14
15dataset = tf.data.TFRecordDataset(["data.tfrecord"])
16dataset = dataset.map(parse_example)
17
18for array, label in dataset:
19    print(array.numpy())
20    print(label.numpy())

Because the tensor bytes include shape information, parse_tensor reconstructs the original dimensions.

When to Store Extra Metadata

Sometimes you still want explicit metadata, such as:

• Original shape for validation
• Dtype name for heterogeneous datasets
• Sample ID or filename
• Class labels or timestamps

That is especially helpful when your pipeline spans multiple languages or tools and you want the record format to stay self-describing.

Why TFRecord Helps at Scale

You could save NumPy arrays directly with .npy or .npz, and that is often fine for smaller workflows. TFRecord becomes attractive when you want:

• Sequential streaming reads
• Easy sharding into many files
• Integration with tf.data
• Consistent training input pipelines

It is less about replacing NumPy entirely and more about packaging examples for TensorFlow ingestion efficiently.

Common Pitfalls

A common mistake is flattening the NumPy array into raw bytes without storing enough information to rebuild shape and dtype later. The data is technically saved, but not meaningfully recoverable.

Another mistake is mixing dtypes during writing and then hard-coding the wrong out_type in tf.io.parse_tensor. That leads to parse errors or incorrect values.

A third mistake is writing one giant TFRecord file for a large dataset. In practice, sharding into multiple files usually works better for throughput and operational handling.

Summary

• NumPy arrays can be stored in TFRecord by serializing them as tensor bytes.
• 'tf.io.serialize_tensor and tf.io.parse_tensor are a clean pair for this workflow.'
• Add metadata such as labels or shape when the dataset needs to be self-describing.
• TFRecord is especially useful when the next step is a tf.data pipeline.
• Be careful to keep dtype and reconstruction logic consistent between writing and reading.