Introduction

When you have categorical strings in TensorFlow, you cannot use a normal Python dictionary directly inside the graph and expect it to work on tensors. The usual TensorFlow solution is a lookup table such as tf.lookup.StaticHashTable, which maps string tensors to numeric or string outputs efficiently.

Use StaticHashTable for Fixed Mappings

If your mapping is known ahead of time, create a static table from key and value tensors.

1import tensorflow as tf
2
3keys = tf.constant(["apple", "banana", "orange"])
4values = tf.constant([1, 2, 3], dtype=tf.int64)
5
6initializer = tf.lookup.KeyValueTensorInitializer(
7    keys=keys,
8    values=values,
9)
10
11table = tf.lookup.StaticHashTable(
12    initializer=initializer,
13    default_value=-1,
14)
15
16fruit = tf.constant(["banana", "orange", "durian"])
17result = table.lookup(fruit)
18
19print(result.numpy())

Output:

[ 2  3 -1]

The table returns -1 for "durian" because that key is not present. This default is one of the most important parts of the design, because real data usually includes unexpected tokens.

Why a Python Dictionary Is Not Enough

A plain Python dictionary works on Python values, not on TensorFlow tensors flowing through a graph or a dataset pipeline.

This works for one scalar in eager mode:

mapping = {"apple": 1, "banana": 2}
print(mapping["apple"])

But it does not scale into tensor-native preprocessing. Once the input is a tf.Tensor, the TensorFlow runtime needs a tensor-aware operation. Lookup tables provide that bridge.

The Output Shape Matches the Input Shape

Lookup happens element by element, preserving the input tensor shape.

1labels = tf.constant([
2    ["cat", "dog"],
3    ["dog", "bird"],
4])
5
6table = tf.lookup.StaticHashTable(
7    tf.lookup.KeyValueTensorInitializer(
8        keys=tf.constant(["cat", "dog", "bird"]),
9        values=tf.constant([0, 1, 2], dtype=tf.int32),
10    ),
11    default_value=-1,
12)
13
14encoded = table.lookup(labels)
15print(encoded.numpy())

Output:

[[0 1]
 [1 2]]

That makes lookup tables convenient inside tf.data pipelines, where batches often arrive as vectors or matrices of strings.

An Alternative for Keras Models

If you are preprocessing string features directly for a Keras model, keras.layers.StringLookup is often an even better fit because it integrates naturally with model building.

1from tensorflow import keras
2
3layer = keras.layers.StringLookup(
4    vocabulary=["apple", "banana", "orange"],
5    output_mode="int",
6)
7
8fruit = tf.constant(["banana", "orange", "durian"])
9print(layer(fruit).numpy())

This is especially useful when the lookup is part of the model or preprocessing pipeline rather than a standalone tensor operation.

Choose the Right Tool

Use tf.lookup.StaticHashTable when:

• you want an explicit table object
• you are working in lower-level TensorFlow code
• you need a fixed mapping in a dataset pipeline

Use StringLookup when:

• you are already building a Keras preprocessing stack
• you want vocabulary management closer to the model

Both solve the same core problem: converting string tensors into model-friendly representations.

Common Pitfalls

• Expecting a Python dictionary to operate directly on TensorFlow tensors inside the graph.
• Forgetting to set a sensible default_value for unknown strings.
• Mixing key and value dtypes incorrectly, such as expecting integer output but creating string values.
• Building one lookup path for training and a different one for serving, which causes inconsistent encodings.
• Ignoring StringLookup when the code is already Keras-centric and the preprocessing belongs with the model.

Summary

• For string tensor lookups in TensorFlow, use tf.lookup.StaticHashTable or keras.layers.StringLookup.
• 'StaticHashTable is a good fit for fixed mappings in tensor and dataset code.'
• Lookup results preserve the input tensor shape.
• Always decide how unknown tokens should be handled through a default value or vocabulary policy.
• A plain Python dictionary is not the right tool once the data is flowing as TensorFlow tensors.