Introduction

A variable-length list feature means each example can contain a different number of values, such as a list of viewed products, clicked tags, or token ids. In older TensorFlow input pipelines, feature columns could help represent this kind of data, but you had to choose the right column type and parsing strategy.

The key distinction is whether the feature is sparse categorical data or a real sequence for models such as RNNs. Those use related but different APIs.

Parse Variable-Length Features Correctly

For tf.Example input, variable-length lists are often parsed with VarLenFeature or RaggedFeature depending on the pipeline style.

1import tensorflow as tf
2
3feature_spec = {
4    "tags": tf.io.VarLenFeature(tf.string),
5}
6
7example = tf.train.Example(features=tf.train.Features(feature={
8    "tags": tf.train.Feature(bytes_list=tf.train.BytesList(value=[b"a", b"b", b"c"]))
9})).SerializeToString()
10
11parsed = tf.io.parse_single_example(example, feature_spec)
12print(parsed["tags"])

This produces a sparse tensor, which is a common starting point for variable-length categorical values.

Use a Categorical Column for Multi-Value Sparse Input

If each example contains a bag or set of categorical values rather than a time sequence, an older feature-column pipeline might look like this:

1import tensorflow as tf
2
3categorical = tf.feature_column.categorical_column_with_vocabulary_list(
4    key="tags",
5    vocabulary_list=["a", "b", "c", "d"],
6)
7
8indicator = tf.feature_column.indicator_column(categorical)

This is useful when an example can contain multiple tags and you want a multi-hot style representation.

The parsed VarLenFeature input works well here because sparse categorical columns expect sparse-style data.

Sequence Feature Columns Are for Ordered Sequences

If the feature is truly ordered sequence data, use sequence-oriented APIs instead of treating it like an unordered bag.

1sequence_col = tf.feature_column.sequence_categorical_column_with_vocabulary_list(
2    key="tokens",
3    vocabulary_list=["red", "green", "blue"],
4)

This older API was designed for sequential model inputs where order matters.

That distinction matters:

• use ordinary categorical columns for unordered multi-value membership
• use sequence feature columns when order and timestep structure matter

Modern TensorFlow Note

Feature columns still appear in older TensorFlow codebases, especially Estimator-based pipelines, but newer Keras workflows often use preprocessing layers, ragged tensors, embeddings, and direct tensor operations instead.

For many modern projects, a Keras-native approach is clearer.

1inputs = tf.keras.Input(shape=(None,), dtype=tf.string, ragged=True)
2lookup = tf.keras.layers.StringLookup(vocabulary=["a", "b", "c", "d"])
3encoded = lookup(inputs)
4embedded = tf.keras.layers.Embedding(input_dim=lookup.vocabulary_size(), output_dim=4)(encoded)
5model = tf.keras.Model(inputs, embedded)

This is often easier to reason about than an older feature-column stack.

Choosing the Right Representation

Ask these questions first:

• Is the list ordered or unordered
• Are values numeric or categorical
• Do you need sparse, ragged, or embedded output
• Are you using Estimator-style code or Keras

The answers determine whether a feature column is still the right tool.

Common Pitfalls

The biggest mistake is treating all variable-length lists as sequences. Many are really unordered multi-value categorical features.

Another common issue is parsing the input incorrectly. Sparse categorical columns generally expect sparse-style parsed data, while ragged and Keras-native pipelines may want different input shapes.

People also reach for feature columns in modern TensorFlow code even when preprocessing layers would be simpler.

Finally, do not confuse sequence feature columns with ordinary categorical columns. They encode different modeling assumptions.

Summary

• Variable-length list features usually start with sparse or ragged parsing.
• Use ordinary categorical columns for unordered multi-value features.
• Use sequence feature columns only when order matters.
• Feature columns are common in older Estimator code, but Keras preprocessing layers are often cleaner in modern TensorFlow.
• Parse the input format to match the representation your column or layer expects.
• Choose the API based on modeling semantics, not just on input shape.