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

Modifier and Type	Method and Description
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