<br />

|---|
| [![](https://www.tensorflow.org/images/GitHub-Mark-32px.png) View source on GitHub](https://github.com/tensorflow/tensorflow/blob/v2.15.1/tensorflow/python/framework/sparse_tensor.py#L47-L368) |

Represents a sparse tensor.

#### View aliases


**Main aliases**

[`tf.SparseTensor`](https://www.tensorflow.org/api_docs/python/tf/sparse/SparseTensor.md.txt)
**Compat aliases for migration**

See
[Migration guide](https://www.tensorflow.org/guide/migrate) for
more details.

[`tf.compat.v1.SparseTensor`](https://www.tensorflow.org/api_docs/python/tf/sparse/SparseTensor.md.txt), [`tf.compat.v1.sparse.SparseTensor`](https://www.tensorflow.org/api_docs/python/tf/sparse/SparseTensor.md.txt)

<br />

```python
tf.sparse.SparseTensor(
    indices, values, dense_shape
)
```

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 2-D int64 tensor of shape `[N, ndims]`, which specifies the
  indices of the elements in the sparse tensor that contain nonzero values
  (elements are zero-indexed). For example, `indices=[[1,3], [2,4]]` specifies
  that the elements with indexes of \[1,3\] and \[2,4\] have nonzero values.

- `values`: A 1-D tensor of any type and shape `[N]`, which supplies the
  values for each element in `indices`. For example, given `indices=[[1,3],
  [2,4]]`, the parameter `values=[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 1-D 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
  two-dimensional 3x6 tensor, `dense_shape=[2,3,4]` specifies a
  three-dimensional 2x3x4 tensor, and `dense_shape=[9]` specifies a
  one-dimensional tensor with 9 elements.

The corresponding dense tensor satisfies:

```python
dense.shape = dense_shape
dense[tuple(indices[i])] = values[i]
```

By convention, `indices` should be sorted in row-major 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)`](https://www.tensorflow.org/versions/r2.15/api_docs/python/tf/sparse/reorder.md.txt).

Example: The sparse tensor

```python
SparseTensor(indices=[[0, 0], [1, 2]], values=[1, 2], dense_shape=[3, 4])
```

represents the dense tensor

```python
[[1, 0, 0, 0]
 [0, 0, 2, 0]
 [0, 0, 0, 0]]
```

<br />

<br />

<br />

| ## Args ||
|---|---|
| `indices` | A 2-D int64 tensor of shape `[N, ndims]`. |
| `values` | A 1-D tensor of any type and shape `[N]`. |
| `dense_shape` | A 1-D int64 tensor of shape `[ndims]`. |

<br />

<br />

<br />

<br />

| ## Raises ||
|---|---|
| `ValueError` | When building an eager SparseTensor if `dense_shape` is unknown or contains unknown elements (None or -1). |

<br />

<br />

<br />

<br />

| ## Attributes ||
|---|---|
| `dense_shape` | A 1-D Tensor of int64 representing the shape of the dense tensor. |
| `dtype` | The `DType` of elements in this tensor. |
| `graph` | The `Graph` that contains the index, value, and dense_shape tensors. |
| `indices` | The indices of non-zero values in the represented dense tensor. |
| `op` | The `Operation` that produces `values` as an output. |
| `shape` | Get the `TensorShape` representing the shape of the dense tensor. |
| `values` | The non-zero values in the represented dense tensor. |

<br />

## Methods

### `consumers`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.15.1/tensorflow/python/framework/sparse_tensor.py#L343-L344)

```python
consumers()
```

### `eval`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.15.1/tensorflow/python/framework/sparse_tensor.py#L297-L320)

```python
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.

> [!NOTE]
> **Note:** Before invoking [`SparseTensor.eval()`](https://www.tensorflow.org/versions/r2.15/api_docs/python/tf/sparse/SparseTensor.md.txt#eval), its graph must have been launched in a session, and either a default session must be available, or `session` must be specified explicitly.

<br />

<br />

<br />

| 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. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| A `SparseTensorValue` object. ||

<br />

### `from_value`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.15.1/tensorflow/python/framework/sparse_tensor.py#L107-L115)

```python
@classmethod
from_value(
    sparse_tensor_value
)
```

### `get_shape`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.15.1/tensorflow/python/framework/sparse_tensor.py#L155-L161)

```python
get_shape() -> `tf.TensorShape`
```

Get the `TensorShape` representing the shape of the dense tensor.

<br />

<br />

<br />

| Returns ||
|---|---|
| A `TensorShape` object. ||

<br />

### `set_shape`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.15.1/tensorflow/python/framework/sparse_tensor.py#L231-L286)

```python
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:

```python
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:

```python
st.set_shape([3, None])
```

An error is raised if an incompatible shape is passed.

```python
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`](https://www.tensorflow.org/versions/r2.15/api_docs/python/tf/function.md.txt), or building a model using
[`tf.keras.Input`](https://www.tensorflow.org/versions/r2.15/api_docs/python/tf/keras/Input.md.txt), [`SparseTensor.set_shape`](https://www.tensorflow.org/versions/r2.15/api_docs/python/tf/sparse/SparseTensor.md.txt#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`](https://www.tensorflow.org/versions/r2.15/api_docs/python/tf/TensorShape.md.txt#merge_with) for details):

```python
st = tf.keras.Input(shape=[None, None, 3], sparse=True)
print(st.shape)
(None, None, None, 3)
```

Dimensions set to `None` are not updated:

```python
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.

> [!CAUTION]
> **Caution:** `set_shape` ensures that the applied shape is compatible with the existing shape, but it does not check at runtime. Setting incorrect shapes can result in inconsistencies between the statically-known graph and the runtime value of tensors.

<br />

<br />

<br />

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

<br />

<br />

<br />

<br />

| Raises ||
|---|---|
| `ValueError` | If `shape` is not compatible with the current shape of this tensor. |

<br />

### `with_values`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.15.1/tensorflow/python/framework/sparse_tensor.py#L182-L205)

```python
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.

<br />

<br />

<br />

| 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`. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| A `SparseTensor` with identical indices and shape but updated values. ||

<br />

#### Example usage:

```python
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__`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.15.1/tensorflow/python/ops/math_ops.py#L1498-L1505)

```python
__div__(
    y
)
```

Component-wise divides a SparseTensor by a dense Tensor.

*Limitation*: this Op only broadcasts the dense side to the sparse side, but not
the other direction.

<br />

<br />

<br />

| Args ||
|---|---|
| `sp_indices` | A `Tensor` of type `int64`. 2-D. `N x R` matrix with the indices of non-empty 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`, `qint16`, `quint16`, `uint16`, `complex128`, `half`, `uint32`, `uint64`. 1-D. `N` non-empty values corresponding to `sp_indices`. |
| `sp_shape` | A `Tensor` of type `int64`. 1-D. 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). |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| A `Tensor`. Has the same type as `sp_values`. ||

<br />

### `__mul__`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.15.1/tensorflow/python/ops/math_ops.py#L1498-L1505)

```python
__mul__(
    y
)
```

Component-wise 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.

<br />

<br />

<br />

| Args ||
|---|---|
| `sp_indices` | A `Tensor` of type `int64`. 2-D. `N x R` matrix with the indices of non-empty 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`, `qint16`, `quint16`, `uint16`, `complex128`, `half`, `uint32`, `uint64`. 1-D. `N` non-empty values corresponding to `sp_indices`. |
| `sp_shape` | A `Tensor` of type `int64`. 1-D. 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). |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| A `Tensor`. Has the same type as `sp_values`. ||

<br />

### `__truediv__`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.15.1/tensorflow/python/ops/math_ops.py#L1498-L1505)

```python
__truediv__(
    y
)
```

Internal helper function for 'sp_t / dense_t'.