Package oracle.kv.table

# Interface Index

public interface Index
Index represents an index on a table in Oracle NoSQL Database. It is an immutable object created from system metadata. Index is used to examine index metadata and used as a factory for `IndexKey` objects used for IndexKey operations in `TableAPI`.

Indexes are created and managed using the administrative command line interface.

Since:
  3.0

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Interface
  Description
  `static enum`
  `Index.IndexType`
  The type of an index.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `FieldRange`
  `createFieldRange(String fieldPath)`
  Creates a `FieldRange` object used to specify a value range for use in a index iteration operation in `TableAPI`.
  `IndexKey`
  `createIndexKey()`
  Creates an `IndexKey` for this index.
  `IndexKey`
  `createIndexKey(RecordValue value)`
  Deprecated.
  as of 4.5
  `IndexKey`
  `createIndexKeyFromJson(InputStream jsonInput, boolean exact)`
  Creates an `IndexKey` based on JSON input.
  `IndexKey`
  `createIndexKeyFromJson(String jsonInput, boolean exact)`
  Creates an `IndexKey` based on JSON input.
  `String`
  `getAnnotationForField(String fieldName)`
  Return an annotation for the given field.
  `String`
  `getDescription()`
  Gets the index's description if present, otherwise null.
  `List<String>`
  `getFields()`
  Returns an unmodifiable list of the field names that define the index.
  `String`
  `getName()`
  Returns the name of the index.
  `Table`
  `getTable()`
  Returns the Table on which the index is defined.
  `Index.IndexType`
  `getType()`
  Returns the index's IndexType.
  `boolean`
  `indexesNulls()`
  Returns wherther the index indexes SQL NULL and EMPTY values.

- ## Method Details

  - ### getTable

    Table getTable()
    Returns the Table on which the index is defined.
    Returns:
      the table

  - ### getName

    String getName()
    Returns the name of the index.
    Returns:
      the index name

  - ### getFields

    List<String> getFields()
    Returns an unmodifiable list of the field names that define the index. These are in order of declaration which is significant. This method returns the same list as `IndexKey.getFields()` for IndexKey instances created by this Index.
    Returns:
      the field names

  - ### indexesNulls

    boolean indexesNulls()
    Returns wherther the index indexes SQL NULL and EMPTY values. This is specified in the index creation DDL. The default is true. If false, a row that contains a NULL value on an indexed field or is missing an indexed field will be skipped during indexing. As a result, the index may not contain at least one entry per row, which further implies that there are certain queries that cannot use this index. The query compiler makes sure that the index will not be used in those cases (e.g. queries containing IS NULL or NOT EXISTS predicates on the indexed field(s)).

  - ### getDescription

    String getDescription()
    Gets the index's description if present, otherwise null. This is a description of the index that is optionally supplied during definition of the index.
    Returns:
      the description or null

  - ### getType

    Index.IndexType getType()
    Returns the index's IndexType.
    Since:
      3.5

  - ### getAnnotationForField

    String getAnnotationForField(String fieldName)
    Return an annotation for the given field. Annotations are used only for Full Text Indexes. Returns null if there is no annotation.
    Since:
      3.5

  - ### createIndexKey

    IndexKey createIndexKey()
    Creates an `IndexKey` for this index. The returned key can only hold fields that are part of this. Other fields are rejected if an attempt is made to set them on the returned object.
    Returns:
      an empty index key based on the index

  - ### createIndexKey

    @Deprecated IndexKey createIndexKey(RecordValue value)
    Deprecated.
    as of 4.5
    Creates an `IndexKey` for the index populated relevant fields from the `RecordValue` parameter. Fields that are not part of the index key are silently ignored.

    This method is not able to construct index keys for multi-key indexes. These are indexes that include elements of a map or array and can result in multiple index entries, or distinct `IndexKey` values for a single row.

    Parameters:
      `value` - a `RecordValue` instance
    Returns:
      an `IndexKey` containing relevant fields from the value
    Throws:
      `IllegalArgumentException` - if the value does not match the table or index, or if the index contains an array or map

  - ### createIndexKeyFromJson

    IndexKey createIndexKeyFromJson(String jsonInput, boolean exact)
    Creates an `IndexKey` based on JSON input. If the `exact` parameter is true the input string must contain an exact match to the index key. It must not have additional data. If false, only matching fields will be added and the input may have additional, unrelated data.
    Parameters:
      `jsonInput` - a JSON string
      `exact` - set to true for an exact match. See above
    Throws:
      `IllegalArgumentException` - if exact is true and a field is missing or extra. It will also be thrown if a field type or value is not correct
      `IllegalArgumentException` - if the input is malformed

  - ### createIndexKeyFromJson

    IndexKey createIndexKeyFromJson(InputStream jsonInput, boolean exact)
    Creates an `IndexKey` based on JSON input. If the `exact` parameter is true the input string must contain an exact match to the index key. It must not have additional data. If false, only matching fields will be added and the input may have additional, unrelated data.
    Parameters:
      `jsonInput` - a JSON string
      `exact` - set to true for an exact match. See above
    Throws:
      `IllegalArgumentException` - if exact is true and a field is missing or extra. It will also be thrown if a field type or value is not correct
      `IllegalArgumentException` - if the input is malformed

  - ### createFieldRange

    FieldRange createFieldRange(String fieldPath)
    Creates a `FieldRange` object used to specify a value range for use in a index iteration operation in `TableAPI`.
    Parameters:
      `fieldPath` - the path to the field from the index to use for the range. This string must match one of the valid index field strings returned by `getFields()`.
    Returns:
      an empty `FieldRange` based on the index
    Throws:
      `IllegalArgumentException` - if the field is not defined in the index