Package com.oracle.database.selectai

Interface SelectAI

All Superinterfaces:
AutoCloseable
public interface SelectAI extends AutoCloseable
Top-level API contract for Oracle Select AI operations.

Select AI lets applications use natural-language prompts for SQL generation, SQL execution, SQL explanation, chat, summarization, synthetic data generation, and retrieval augmented generation (RAG) with vector indexes. This interface is the SDK entry point for creating or opening SDK objects for the database resources that support those features: credentials, profiles, conversations, and vector indexes.

SelectAI extends AutoCloseable. A SelectAI client may own SDK-managed JDBC resources depending on how it is created.

For clients created with create(DbConnectionConfig), the SDK creates and owns a single JDBC connection. Call close() when the client is no longer needed to release that connection and its database session.

For clients created with create(DataSource), the application owns the DataSource. The SDK obtains a connection from the DataSource for each operation and closes that operation connection after use. Calling close() does not close the caller-owned DataSource.

See Also:

  • Method Details

    • create

      static SelectAI create(DbConnectionConfig dbConnectionConfig) throws SelectAIException
      Creates a SelectAI client from database connection configuration.

      This is the recommended public entry point for applications that want the SDK to create and use a single JDBC connection from DbConnectionConfig. For a complete runnable sample source, see ListProfilesSample source.

      Parameters:
      dbConnectionConfig - database connection configuration
      Returns:
      SelectAI client
      Throws:
      IllegalArgumentException - when dbConnectionConfig is null
      SelectAIException - when the database connection cannot be initialized

    • create

      static SelectAI create(DbConnectionConfig dbConnectionConfig, SelectAIOptions options) throws SelectAIException
      Creates a SelectAI client from database connection configuration and SDK execution options.

      For a complete runnable sample source, see CreateSelectAIWithOptionsSample source.

      Parameters:
      dbConnectionConfig - database connection configuration
      options - SDK execution options; null uses SelectAIOptions.defaults()
      Returns:
      SelectAI client
      Throws:
      IllegalArgumentException - when dbConnectionConfig is null
      SelectAIException - when the database connection cannot be initialized

    • create

      static SelectAI create(DataSource dataSource)
      Creates a SelectAI client backed by a DataSource.

      This is the recommended public entry point for applications that manage JDBC connections through a DataSource or connection pool. Each SDK operation obtains a connection from the DataSource and closes it when the operation completes. For a complete runnable sample source, see ListProfilesWithDataSourceSample source.

      Parameters:
      dataSource - DataSource used to obtain JDBC connections
      Returns:
      SelectAI client
      Throws:
      IllegalArgumentException - when dataSource is null

    • create

      static SelectAI create(DataSource dataSource, SelectAIOptions options)
      Creates a SelectAI client backed by a DataSource and SDK execution options.

      For a complete runnable sample source, see CreateSelectAIDataSourceWithOptionsSample source.

      Parameters:
      dataSource - DataSource used to obtain JDBC connections
      options - SDK execution options; null uses SelectAIOptions.defaults()
      Returns:
      SelectAI client
      Throws:
      IllegalArgumentException - when dataSource is null

    • close

      void close() throws SelectAIException
      Releases resources owned by this SelectAI client.

      For clients created with create(DbConnectionConfig), this closes the SDK-owned JDBC connection. For clients created with create(DataSource), this does not close the caller-owned DataSource; individual operation connections are already closed after each operation. For a complete runnable sample source, see CloseSelectAISample source.

      Specified by:
      close in interface AutoCloseable
      Throws:
      SelectAIException - when an owned JDBC connection cannot be closed

    • getConnection

      Connection getConnection()
      Returns the JDBC connection retained by this SelectAI client.

      This method is available only for clients created with create(DbConnectionConfig), where the SDK owns and reuses one JDBC connection. Use it when application code needs to execute custom SQL or PL/SQL in the same database session used by SDK operations.

      For clients created with create(DataSource), there is no single retained connection. In that mode, this method throws IllegalStateException; callers should obtain custom JDBC connections from their own DataSource directly.

      The returned connection is owned by this SelectAI client. Close the SelectAI client when finished; closing the returned connection directly also closes the SDK connection and can make later SDK operations fail. Do not use this method to share one SDK-owned JDBC connection across multiple application threads. For a complete runnable sample source, see GetConnectionSample source.

      Returns:
      retained JDBC connection for DbConnectionConfig mode
      Throws:
      IllegalStateException - when this client is DataSource-backed

    • credential

      Credential credential(CredentialConfig credentialConfig)
      Creates a Credential instance from database credential details.

      A credential is a database object that stores the secret material needed by Autonomous Database to call an AI provider or object storage service. The returned object can create or drop that credential in the current schema. For a complete runnable sample source, see CreateCredentialObjectSample source.

      Parameters:
      credentialConfig - credential definition used for create/drop operations
      Returns:
      credential object initialized with the supplied credential details
      See Also:

    • profile

      Profile profile(String profileName) throws SelectAIException
      Opens a Profile object for an existing AI profile in the current schema.

      An AI profile stores the provider and AI model configuration and database object metadata that Select AI uses for natural-language SQL, chat, and RAG. "Existing" is not limited to profiles created by this Java SDK; profiles created through PL/SQL, Python, SQL tools, or another application are available when they exist in the same schema and privileges allow access. The returned object can run prompts, inspect metadata, update attributes, enable/disable the profile, or drop it. For a complete runnable sample source, see OpenProfileSample source.

      Parameters:
      profileName - profile name
      Returns:
      profile object bound to the specified database profile
      Throws:
      SelectAIException - when the profile cannot be loaded
      See Also:

    • profile

      Profile profile(String profileName, ProfileAttributes profileAttributes, String description, ProfileStatus status) throws SelectAIException
      Creates a Profile object initialized with profile creation details.

      This call does not create the profile in the database. Invoke Profile.create() on the returned object to persist the profile. Passing null for status keeps the database default behavior during creation. For a complete runnable sample source, see CreateProfileWithSelectAISample source.

      Parameters:
      profileName - profile name
      profileAttributes - profile attributes payload
      description - profile description
      status - optional initial profile status
      Returns:
      profile object initialized with the supplied create details
      Throws:
      SelectAIException - when the profile object cannot be initialized
      See Also:

    • listProfiles

      List<Profile> listProfiles() throws SelectAIException
      Lists AI profiles visible in the current schema.

      Listing profiles is a collection-level operation, so it is exposed on the SelectAI client instead of requiring an unbound Profile object. Each returned object can inspect profile metadata, run prompts, update attributes, enable/disable the profile, or drop the profile. For a complete runnable sample source, see ListProfilesSample source.

      Returns:
      list of profile objects hydrated from database metadata
      Throws:
      SelectAIException - when listing profiles fails

    • listProfiles

      List<Profile> listProfiles(String profileNamePattern) throws SelectAIException
      Lists AI profiles visible in the current schema whose names match the supplied database regular-expression pattern.

      Listing profiles is a collection-level operation, so it is exposed on the SelectAI client. The pattern is evaluated by the database metadata query. Use profile(String) when opening one literal profile name. For a complete runnable sample source, see ListProfilesByPatternSample source.

      Parameters:
      profileNamePattern - regular-expression pattern matched against profile names
      Returns:
      list of matching profile objects hydrated from database metadata
      Throws:
      IllegalArgumentException - when profileNamePattern is null or blank
      SelectAIException - when listing profiles fails

    • vectorIndex

      VectorIndex vectorIndex(String indexName) throws SelectAIException
      Opens a VectorIndex object for an existing vector index in the current schema.

      A vector index stores embeddings for content that Select AI can retrieve for RAG. The index may have been created by Java, PL/SQL, Python, or another tool; this method only binds a Java object to the database object so it can be inspected, enabled, disabled, updated, or dropped. For a complete runnable sample source, see OpenVectorIndexSample source.

      Parameters:
      indexName - vector index name
      Returns:
      vector index object bound to the specified database index
      Throws:
      SelectAIException - when loading the index fails
      See Also:

    • vectorIndex

      VectorIndex vectorIndex(VectorIndexConfig vectorIndexConfig) throws SelectAIException
      Creates a VectorIndex object initialized from configuration.

      This call does not create/persist the vector index in the database. Invoke VectorIndex.create() on the returned object to create it. The configuration describes where source content is located, which credential can read it, and which profile/embedding settings Select AI should use to populate the vector store. For a complete runnable sample source, see ConfigureVectorIndexSample source.

      Parameters:
      vectorIndexConfig - vector index configuration
      Returns:
      vector index object initialized with the given configuration
      Throws:
      SelectAIException - when vector index object initialization fails
      See Also:

    • listVectorIndexes

      List<VectorIndex> listVectorIndexes() throws SelectAIException
      Lists vector indexes visible in the current schema.

      Listing vector indexes is a collection-level operation, so it is exposed on the SelectAI client. This method is equivalent to listVectorIndexes(String) with .*. For a complete runnable sample source, see ListVectorIndexesSample source.

      Returns:
      list of vector index objects hydrated from database metadata
      Throws:
      SelectAIException - when listing vector indexes fails

    • listVectorIndexes

      List<VectorIndex> listVectorIndexes(String indexNamePattern) throws SelectAIException
      Lists vector indexes visible in the current schema whose names match the supplied database regular-expression pattern.

      The pattern is evaluated by the database metadata query. Use vectorIndex(String) when opening one literal vector-index name. For a complete runnable sample source, see ListVectorIndexesSample source.

      Parameters:
      indexNamePattern - regular-expression pattern matched against vector-index names
      Returns:
      list of matching vector index objects hydrated from database metadata
      Throws:
      SelectAIException - when listing vector indexes fails

    • listConversations

      List<Conversation> listConversations() throws SelectAIException
      Lists conversations visible in the current schema.

      Listing conversations is a collection-level operation, so it is exposed on the SelectAI client instead of requiring an unbound Conversation object. For a complete runnable sample source, see ListConversationsSample source.

      Returns:
      list of conversation objects hydrated from database metadata
      Throws:
      SelectAIException - when listing conversations fails

    • conversation

      Conversation conversation(ConversationAttributes conversationAttributes) throws SelectAIException
      Creates a Conversation object initialized with supplied attributes.

      This call does not persist/create the conversation in the database. Invoke Conversation.create() on the returned object to create it. Conversations keep chat-style context so later prompts can refer to prior turns. For a complete runnable sample source, see ConfigureConversationSample source.

      Parameters:
      conversationAttributes - conversation attributes
      Returns:
      conversation object initialized with the given attributes
      Throws:
      SelectAIException - when conversation object initialization fails

    • conversation

      Conversation conversation(String conversationId) throws SelectAIException
      Opens a Conversation object for an existing conversation by ID.

      The returned object can inspect attributes, update retention/title metadata, or drop the conversation. For a complete runnable sample source, see OpenConversationSample source.

      Parameters:
      conversationId - conversation identifier
      Returns:
      conversation object bound to the given ID
      Throws:
      SelectAIException - when the conversation metadata cannot be loaded