Package com.oracle.database.selectai

Interface VectorIndex

public interface VectorIndex
Contract for Select AI vector-index lifecycle and configuration operations.

A vector index stores embeddings for source content so Select AI can retrieve relevant chunks and include them in model prompts for retrieval augmented generation (RAG). A VectorIndex instance can represent a vector index created by Java, PL/SQL, Python, SQL tools, or another application when the index is visible in the current schema.

A VectorIndex object can be configured for creation or database-backed. A configured vector index has an index name, attributes, description, status, and create options in memory, but it is not persisted until create() succeeds. A database-backed vector index is opened from the database, listed from metadata, or successfully created through this SDK.

Metadata getters can return configured values before creation. Operations that execute against an existing database vector index, such as update, enable, disable, and drop, require a database-backed vector index. The SDK rejects those operations with IllegalStateException when the object is not bound to an index name or is configured for creation but has not been created yet.

See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    create()
    Creates the vector index in the database.
    boolean
    disable()
    Disables the vector index so Select AI will not use it for retrieval until it is enabled again.
    boolean
    drop(boolean force)
    Drops the vector index.
    boolean
    drop(boolean includeData, boolean force)
    Drops the vector index and controls whether backing vector data is also removed.
    boolean
    enable()
    Enables the vector index so Select AI can use it during RAG operations.
    String
    getDescription()
    Returns vector index description.
    String
    getIndexName()
    Returns vector index name.
    String
    getStatus()
    Returns vector index status.
    VectorIndexAttributes
    getVectorIndexAttributes()
    Fetches and returns current vector index attributes.
    Boolean
    isWaitForCompletion()
    Indicates whether create operations wait for completion.
    boolean
    update(VectorIndexAttributes vectorIndexAttributes)
    Updates vector index attributes in bulk.
    boolean
    update(String attributeName, String attributeValue)
    Updates a single vector-index attribute using normal string binding.
    boolean
    update(String attributeName, String attributeValue, boolean useClob)
    Updates a single vector-index attribute and optionally sends large values as character data.

  • Method Details

    • getIndexName

      String getIndexName()
      Returns vector index name.

      For a complete runnable sample source, see GetVectorIndexNameSample source.

      Returns:
      vector index name

    • getDescription

      String getDescription()
      Returns vector index description.

      For a complete runnable sample source, see GetVectorIndexDescriptionSample source.

      Returns:
      vector index description

    • getStatus

      String getStatus() throws SelectAIException
      Returns vector index status.

      For a configured index that has not been created yet, returns the caller-supplied create status. For an index opened from or listed from the database, refreshes metadata from the database before returning the status. For a complete runnable sample source, see GetVectorIndexStatusSample source.

      Returns:
      vector index status
      Throws:
      IllegalStateException - when this VectorIndex instance is not bound to an index name
      SelectAIException - when current vector index metadata cannot be fetched

    • getVectorIndexAttributes

      VectorIndexAttributes getVectorIndexAttributes() throws SelectAIException
      Fetches and returns current vector index attributes.

      For indexes opened from or listed from the database, this fetches current attributes from database metadata. For newly configured indexes that have not been created yet, this returns the caller-supplied create payload. For a complete runnable sample source, see GetVectorIndexAttributesSample source.

      Returns:
      vector index attributes, or null when attributes are not available
      Throws:
      SelectAIException - when current vector index attributes cannot be fetched

    • isWaitForCompletion

      Boolean isWaitForCompletion()
      Indicates whether create operations wait for completion.

      This is a create-time execution option, not current database metadata. Loaded/listed indexes return null; configured indexes return the caller-supplied create option. For a complete runnable sample source, see IsVectorIndexWaitForCompletionSample source.

      Returns:
      wait-for-completion flag

    • create

      boolean create() throws SelectAIException
      Creates the vector index in the database.

      Creation reads source content using the configured credential, generates embeddings using the associated profile/provider, and stores the resulting vectors for later RAG prompts. For a complete runnable sample source, see CreateVectorIndexSample source.

      Returns:
      true when create succeeds
      Throws:
      IllegalStateException - when this VectorIndex instance is not configured for creation
      SelectAIException - when create fails

    • drop

      boolean drop(boolean force) throws SelectAIException
      Drops the vector index.

      This shorthand drops both vector-index metadata and backing vector data. For a complete runnable sample source, see DropVectorIndexSample source.

      Parameters:
      force - when true, performs force drop if supported
      Returns:
      true when drop succeeds
      Throws:
      IllegalStateException - when this VectorIndex instance is not bound to an index name or is configured for creation but has not been created yet
      SelectAIException - when drop fails

    • drop

      boolean drop(boolean includeData, boolean force) throws SelectAIException
      Drops the vector index and controls whether backing vector data is also removed.

      For a complete runnable sample source, see DropVectorIndexSample source.

      Parameters:
      includeData - when true, drops backing vector data with the index metadata; when false, drops only vector-index metadata
      force - when true, performs force drop if supported
      Returns:
      true when drop succeeds
      Throws:
      IllegalStateException - when this VectorIndex instance is not bound to an index name or is configured for creation but has not been created yet
      SelectAIException - when drop fails

    • enable

      boolean enable() throws SelectAIException
      Enables the vector index so Select AI can use it during RAG operations.

      For a complete runnable sample source, see EnableVectorIndexSample source.

      Returns:
      true when enable succeeds
      Throws:
      IllegalStateException - when this VectorIndex instance is not bound to an index name or is configured for creation but has not been created yet
      SelectAIException - when enable fails

    • disable

      boolean disable() throws SelectAIException
      Disables the vector index so Select AI will not use it for retrieval until it is enabled again.

      For a complete runnable sample source, see DisableVectorIndexSample source.

      Returns:
      true when disable succeeds
      Throws:
      IllegalStateException - when this VectorIndex instance is not bound to an index name or is configured for creation but has not been created yet
      SelectAIException - when disable fails

    • update

      boolean update(VectorIndexAttributes vectorIndexAttributes) throws SelectAIException
      Updates vector index attributes in bulk.

      Use this with VectorIndexAttributes.updateBuilder() when building an update-only payload. The SDK validates required Java inputs, then delegates attribute mutability rules to DBMS_CLOUD_AI.UPDATE_VECTOR_INDEX so database-version changes are honored without SDK code changes. For a complete runnable sample source, see UpdateVectorIndexAttributesSample source.

      Parameters:
      vectorIndexAttributes - attributes payload
      Returns:
      true when update succeeds
      Throws:
      IllegalStateException - when this VectorIndex instance is not bound to an index name or is configured for creation but has not been created yet
      SelectAIException - when update fails

    • update

      boolean update(String attributeName, String attributeValue) throws SelectAIException
      Updates a single vector-index attribute using normal string binding.

      The SDK validates required Java inputs, then delegates attribute mutability rules to DBMS_CLOUD_AI.UPDATE_VECTOR_INDEX. For a complete runnable sample source, see UpdateVectorIndexAttributeSample source.

      Parameters:
      attributeName - attribute name
      attributeValue - attribute value
      Returns:
      true when update succeeds
      Throws:
      IllegalStateException - when this VectorIndex instance is not bound to an index name or is configured for creation but has not been created yet
      SelectAIException - when update fails

    • update

      boolean update(String attributeName, String attributeValue, boolean useClob) throws SelectAIException
      Updates a single vector-index attribute and optionally sends large values as character data.

      The SDK validates required Java inputs, then delegates attribute mutability rules to DBMS_CLOUD_AI.UPDATE_VECTOR_INDEX. For a complete runnable sample source, see UpdateVectorIndexAttributeWithClobSample source.

      Parameters:
      attributeName - attribute name
      attributeValue - attribute value
      useClob - when true, sends value as CLOB
      Returns:
      true when update succeeds
      Throws:
      IllegalStateException - when this VectorIndex instance is not bound to an index name or is configured for creation but has not been created yet
      SelectAIException - when update fails