Package oracle.sql

## Interface VECTOR.SparseArray

All Known Subinterfaces:
  `VECTOR.SparseByteArray`, `VECTOR.SparseDoubleArray`, `VECTOR.SparseFloatArray`

Enclosing class:
  VECTOR

    public static interface VECTOR.SparseArray

A representation of SPARSE VECTOR data in Oracle Database. This interface, and its subinterfaces, are designed for use in Java/SQL conversions of SPARSE VECTOR data with the Oracle JDBC Driver. These interfaces are not designed for general usage outside of this context.

SparseArray subinterfaces are defined for double, float, and byte valued data:

- `VECTOR.SparseDoubleArray`
- `VECTOR.SparseFloatArray`
- `VECTOR.SparseByteArray`

### Creating a SPARSE VECTOR Bind Value

Instances of the SparseArray subinterfaces may be passed to `setObject` methods of `PreparedStatement` and `CallableStatement`:

        void example(PreparedStatement preparedStatement) throws SQLException {
          int length = 9999;
          int[] indices = {0, 100, 2000};
          float[] values = {0.5f, -0.25f, 0.125f};

          SparseFloatArray sparseFloatArray =
            SparseFloatArray.of(length, indices, values);
          preparedStatement.setObject(1, sparseFloatArray);
        }

The example above creates a SPARSE VECTOR bind value with FLOAT32 dimensions. The bind value has a length of 9,999 dimensions in total, but only 3 have a non-zero value. The non-zero values of 0.5, -0.25, and 0.125 appear at the indices of 0, 100, and 2000. The value at all other indices is zero.

The code above uses the `VECTOR.SparseFloatArray.of(int,int[],float[])` factory method. Other factory methods can create double-valued and byte-valued SparseArray objects. The objects returned by these factory methods are just wrappers around the input arguments. The factory methods do not perform extensive validations nor create copies of the input arrays.

Usages of SparseArray should be limited to a small scope in which an instance is created and then immediately passed to `setObject`. This usage pattern is illustrated in the following code, where data is sourced from a SparseVector object of the Tribuo library:

         static void setSparseVector(
             PreparedStatement preparedStatement,
             int columnIndex,
             org.tribuo.math.la.SparseVector sparseVector)
           throws SQLException  {

           int length = sparseVector.size();
           int[] indices = new int[sparseVector.numActiveElements()];
           double[] values = new double[indices.length];

           int sparseIndex = 0;
           for (VectorTuple tuple : sparseVector) {
             indices[sparseIndex] = tuple.index;
             values[sparseIndex] = tuple.value;
             sparseIndex++;
           }

           SparseDoubleArray sparseDoubleArray =
             SparseDoubleArray.of(length, indices, values);
           preparedStatement.setObject(columnIndex, sparseDoubleArray);
         }

### Consuming SPARSE VECTOR Columns and Parameters

Instances of the SparseArray subinterfaces may be returned by `getObject` methods of `ResultSet` and `CallableStatement`:

        void example(ResultSet resultSet) throws SQLException {
          SparseFloatArray sparseFloatArray =
            resultSet.getObject(1, SparseFloatArray.class);

          int length = sparseFloatArray.length();
          int[] indices = sparseFloatArray.indices();
          float[] values = sparseFloatArray.values();

          consumeSparseVector(length, indices, values);
        }

In the example above, passing `SparseFloatArray.class` to `getObject` has a VECTOR column converted into a float-valued SparseArray. Passing in `SparseDoubleArray.class` or `SparseByteArray.class` would respectively convert the column into a double-valued or byte-valued SparseArray.

A SparseArray returned by `getObject` is sourced from data that has been validated by Oracle Database. This provides some guarantees about the validity of the SparseArray, but there is no guarantee of it remaining in that state. The `indices()` and `values()` methods will return the same arrays that back the SparseArray, and modifications to these arrays can create an invalid state.

Similar to a SparseArray created by a factory methods, a SparseArray returned by `getObject` should be immediately consumed, typically by translating the data into a more durable representation. This usage pattern is again illustrated with the SparseVector class of the Tribuo library:

         static org.tribuo.math.la.SparseVector getSparseVector(
             ResultSet resultSet, int columnIndex)
           throws SQLException {

           SparseDoubleArray sparseDoubleArray =
             resultSet.getObject(columnIndex, SparseDoubleArray.class);

           int length = sparseDoubleArray.length();
           int[] indices = sparseDoubleArray.indices();
           double[] values = sparseDoubleArray.values();

           SparseVector sparseVector =
             SparseVector.createSparseVector(length, indices, values);
           return sparseVector;
         }

Since:
  23.7

### Method Summary

All Methods Instance Methods Abstract Methods
`int[]` `indices()` Returns the indices of non-zero values in the VECTOR data represented by this SparseArray.
`int` `length()` Returns the the total number of values, including zero-valued dimensions, in the VECTOR data represented by this SparseArray.
`java.lang.String` `toString()` Returns a VARCHAR literal expression of the SPARSE VECTOR data represented by this SparseArray.

### Method Detail

#### length

    int length()

Returns the the total number of values, including zero-valued dimensions, in the VECTOR data represented by this SparseArray.

If this SparseArray was returned by a `getObject` method, then the length is guaranteed to be a positive integer in the range of 0 (inclusive) and the maximum length of SPARSE VECTOR in Oracle Database. In version 23.7, Oracle Database supports a maximum length of 65,535.

Returns:
  The total dimension count, including zero-valued dimensions.

#### indices

    int[] indices()

Returns the indices of non-zero values in the VECTOR data represented by this SparseArray. The indices are zero-based (the lowest possible index is zero).

The array returned by this method may be one that backs this SparseArray. Modifying the array's values can modify the set of non-zero indices retained by this SparseArray.

If this SparseArray was returned by a `getObject` method, and the array has never been modified, then the following guarantees are made:

- The indices are ordered from least to greatest.
- The indices range from 0 (inclusive) to `length()`(exclusive).
- The length of indices is equal to the length of the array returned by the `values()` method of `VECTOR.SparseDoubleArray`, `VECTOR.SparseFloatArray`, or `VECTOR.SparseByteArray`.

None of these guarantees are made if this SparseArray was created via a method such as `VECTOR.SparseFloatArray.of(int, int[], float[])`. These factory methods defer validations until the SparseArray is converted into SPARSE VECTOR data and sent to Oracle Database.

Returns:
  The indices of non-zero values. Not null.

#### toString

    java.lang.String toString()

Returns a VARCHAR literal expression of the SPARSE VECTOR data represented by this SparseArray. The expression has the following format:

          [length,[indices],[non-zero-values]]

Overrides:
  `toString` in class `java.lang.Object`