Indexed slice selection
Selecting rows or columns from a tensor using an index tensor.
TensorFlow · Function
tf.gather
Selects slices from a tensor along a chosen axis using integer indices. It supports arbitrary tensor ranks, negative axes, and batch-specific lookups.
How it works
tf.gather selects slices from a tensor along a chosen axis using integer indices. The output preserves the non-gathered dimensions while inserting the shape of indices at the gathered position; batch_dims enables separate lookups for each batch element.
Syntax
tf.gather(params, indices, validate_indices=None, axis=None, batch_dims=0, name=None)Parameters
| Name | Type | Description |
|---|---|---|
params | Tensor | Tensor from which to gather values; it must have rank at least axis + 1. |
indices | Tensor | Integer index tensor with int32 or int64 dtype; values must be valid for the selected axis. |
validate_indices | None | Deprecated argument with no effect. |
axis | Tensor | Tensor specifying the axis in params; it must be at least batch_dims and supports negative indexes. |
batch_dims | integer | Number of batch dimensions; it must not exceed rank(indices). |
name | string | Optional name for the operation. |
Returns
A Tensor containing the gathered slices, with the same dtype as params.
Key points
- The function selects complete slices rather than only scalar values, using indices along the specified axis.
- Indices may have any rank, although one-dimensional index tensors are common.
- Input tensors are not limited to vectors or matrices; gathering works with arbitrary parameter shapes.
- Set axis to choose the dimension being indexed; if omitted, gathering uses axis 0.
- batch_dims supports per-batch lookups instead of applying one shared index set to every batch element.
- Supported index dtypes are int32 and int64.
Common mistakes
- Indices outside the valid range can fail; on CPU an out-of-bounds index raises an error.
- Do not rely on validate_indices to change checking behavior; the argument is deprecated and ignored.
- When batching, axis cannot precede the number of batch dimensions.
Example: Gather selected rows
import tensorflow as tf
params = tf.constant([[10, 20], [30, 40], [50, 60]])
indices = tf.constant([2, 0], dtype=tf.int32)
result = tf.gather(params, indices, axis=0)
print(result.numpy())
Selects rows 2 and 0 from the first axis, producing [[50, 60], [10, 20]].
When to use it
Batch-specific lookup
Looking up different positions for each item in a batched tensor.
Tensor reordering
Reordering or filtering tensor slices according to computed integer positions.
Interview questions
QWhat does tf.gather do?
tf.gather selects slices from params along axis using integer indices. By default, axis is the first non-batch dimension, and the selected index shape contributes to the result shape.
Follow-up: How would you gather independently within each batch? Use batch_dims to specify the number of leading dimensions whose entries are matched between params and indices.
QWhat restrictions apply to indices?
indices must be an int32 or int64 tensor and its values must fall within the valid range for the selected axis. The gathered slices retain the values and dtype of params.
Follow-up: What happens with an invalid index? On CPU, TensorFlow raises an error; indices are always validated on CPU and never validated on GPU.
QHow do axis and batch_dims affect gathering?
axis identifies the dimension from which slices are selected and supports negative indexes. batch_dims specifies leading batch dimensions, and it must not exceed the rank of indices.
Follow-up: What constraint connects axis and batch_dims? axis must be greater than or equal to batch_dims.
Related
tf.gather_ndtf.nn.embedding_lookuptf.argsort