View source on GitHub 
Represents a sparse tensor.
tf.sparse.SparseTensor(
indices, values, dense_shape
)
Used in the notebooks
Used in the guide  Used in the tutorials 

TensorFlow represents a sparse tensor as three separate dense tensors:
indices
, values
, and dense_shape
. In Python, the three tensors are
collected into a SparseTensor
class for ease of use. If you have separate
indices
, values
, and dense_shape
tensors, wrap them in a SparseTensor
object before passing to the ops below.
Concretely, the sparse tensor SparseTensor(indices, values, dense_shape)
comprises the following components, where N
and ndims
are the number
of values and number of dimensions in the SparseTensor
, respectively:
indices
: A 2D int64 tensor of shape[N, ndims]
, which specifies the indices of the elements in the sparse tensor that contain nonzero values (elements are zeroindexed). For example,indices=[[1,3], [2,4]]
specifies that the elements with indexes of [1,3] and [2,4] have nonzero values.values
: A 1D tensor of any type and shape[N]
, which supplies the values for each element inindices
. For example, givenindices=[[1,3], [2,4]]
, the parametervalues=[18, 3.6]
specifies that element [1,3] of the sparse tensor has a value of 18, and element [2,4] of the tensor has a value of 3.6.dense_shape
: A 1D int64 tensor of shape[ndims]
, which specifies the dense_shape of the sparse tensor. Takes a list indicating the number of elements in each dimension. For example,dense_shape=[3,6]
specifies a twodimensional 3x6 tensor,dense_shape=[2,3,4]
specifies a threedimensional 2x3x4 tensor, anddense_shape=[9]
specifies a onedimensional tensor with 9 elements.
The corresponding dense tensor satisfies:
dense.shape = dense_shape
dense[tuple(indices[i])] = values[i]
By convention, indices
should be sorted in rowmajor order (or equivalently
lexicographic order on the tuples indices[i]
). This is not enforced when
SparseTensor
objects are constructed, but most ops assume correct ordering.
If the ordering of sparse tensor st
is wrong, a fixed version can be
obtained by calling tf.sparse.reorder(st)
.
Example: The sparse tensor
SparseTensor(indices=[[0, 0], [1, 2]], values=[1, 2], dense_shape=[3, 4])
represents the dense tensor
[[1, 0, 0, 0]
[0, 0, 2, 0]
[0, 0, 0, 0]]
Args  

indices

A 2D int64 tensor of shape [N, ndims] .

values

A 1D tensor of any type and shape [N] .

dense_shape

A 1D int64 tensor of shape [ndims] .

Raises  

ValueError

When building an eager SparseTensor if dense_shape is
unknown or contains unknown elements (None or 1).

Methods
consumers
consumers()
eval
eval(
feed_dict=None, session=None
)
Evaluates this sparse tensor in a Session
.
Calling this method will execute all preceding operations that produce the inputs needed for the operation that produces this tensor.
Args  

feed_dict

A dictionary that maps Tensor objects to feed values. See
tf.Session.run for a description of the valid feed values.

session

(Optional.) The Session to be used to evaluate this sparse
tensor. If none, the default session will be used.

Returns  

A SparseTensorValue object.

from_value
@classmethod
from_value( sparse_tensor_value )
get_shape
get_shape()
Get the TensorShape
representing the shape of the dense tensor.
Returns  

A TensorShape object.

set_shape
set_shape(
shape
)
Updates the TensorShape
representing the shape of the dense tensor.
With eager execution this operates as a shape assertion. Here the shapes match:
st = tf.SparseTensor(
indices=[[0, 0], [1, 2]], values=[1, 2], dense_shape=[3, 4])
st.set_shape([3, 4])
Passing a None
in the new shape allows any value for that axis:
st.set_shape([3, None])
An error is raised if an incompatible shape is passed.
st.set_shape([1, 4])
Traceback (most recent call last):
ValueError: Tensor's shape (3, 4) is not compatible with supplied
shape [1, 4]
When executing in a tf.function
, or building a model using
tf.keras.Input
, SparseTensor.set_shape
will merge the given shape
with the current shape of this tensor, and set the tensor's shape to the
merged value (see tf.TensorShape.merge_with
for details):
st = tf.keras.Input(shape=[None, None, 3], sparse=True)
print(st.shape)
(None, None, None, 3)
Dimensions set to None
are not updated:
st.set_shape([None, 224, 224, None])
print(st.shape)
(None, 224, 224, 3)
The main use case for this is to provide additional shape information that cannot be inferred from the graph alone.
Args  

shape

A TensorShape representing the shape of this tensor, a
TensorShapeProto , a list, a tuple, or None.

Raises  

ValueError

If shape is not compatible with the current shape of
this tensor.

with_values
with_values(
new_values
)
Returns a copy of self
with values
replaced by new_values
.
This method produces a new SparseTensor
that has the same nonzero
indices
and same dense_shape
, but updated values.
Args  

new_values

The values of the new SparseTensor . Needs to have the same
shape as the current .values Tensor . May have a different type than
the current values .

Returns  

A SparseTensor with identical indices and shape but updated values.

Example usage:
st = tf.sparse.from_dense([[1, 0, 2, 0], [3, 0, 0, 4]])
tf.sparse.to_dense(st.with_values([10, 20, 30, 40])) # 4 nonzero values
<tf.Tensor: shape=(2, 4), dtype=int32, numpy=
array([[10, 0, 20, 0],
[30, 0, 0, 40]], dtype=int32)>
__div__
__div__(
y
)
Componentwise divides a SparseTensor by a dense Tensor.
Limitation: this Op only broadcasts the dense side to the sparse side, but not the other direction.
Args  

sp_indices

A Tensor of type int64 .
2D. N x R matrix with the indices of nonempty values in a
SparseTensor, possibly not in canonical ordering.

sp_values

A Tensor . Must be one of the following types: float32 , float64 , int32 , uint8 , int16 , int8 , complex64 , int64 , qint8 , quint8 , qint32 , bfloat16 , uint16 , complex128 , half , uint32 , uint64 .
1D. N nonempty values corresponding to sp_indices .

sp_shape

A Tensor of type int64 .
1D. Shape of the input SparseTensor.

dense

A Tensor . Must have the same type as sp_values .
R D. The dense Tensor operand.

name

A name for the operation (optional). 
Returns  

A Tensor . Has the same type as sp_values .

__mul__
__mul__(
y
)
Componentwise multiplies a SparseTensor by a dense Tensor.
The output locations corresponding to the implicitly zero elements in the sparse tensor will be zero (i.e., will not take up storage space), regardless of the contents of the dense tensor (even if it's +/INF and that INF*0 == NaN).
Limitation: this Op only broadcasts the dense side to the sparse side, but not the other direction.
Args  

sp_indices

A Tensor of type int64 .
2D. N x R matrix with the indices of nonempty values in a
SparseTensor, possibly not in canonical ordering.

sp_values

A Tensor . Must be one of the following types: float32 , float64 , int32 , uint8 , int16 , int8 , complex64 , int64 , qint8 , quint8 , qint32 , bfloat16 , uint16 , complex128 , half , uint32 , uint64 .
1D. N nonempty values corresponding to sp_indices .

sp_shape

A Tensor of type int64 .
1D. Shape of the input SparseTensor.

dense

A Tensor . Must have the same type as sp_values .
R D. The dense Tensor operand.

name

A name for the operation (optional). 
Returns  

A Tensor . Has the same type as sp_values .

__truediv__
__truediv__(
y
)
Internal helper function for 'sp_t / dense_t'.