Select AI for Java

Select AI for Java is a Java SDK that provides a Java-native API for configuring and using Select AI with Oracle Autonomous AI Database. The SDK provides Select AI capabilities including AI profiles, credentials, conversations, vector indexes, natural-language SQL, summarization, translation, feedback, and synthetic-data generation through Java classes, interfaces, and methods.

The SDK uses JDBC to communicate with the database and uses the underlying database APIs required for Select AI operations. It supports both SDK-managed JDBC connections and application-managed DataSource connections.

This documentation provides task-oriented guidance for installing, configuring, and using the SDK. For complete class, method, parameter, and exception details, see the Select AI for Java API Reference.

For constructors, methods, request and response classes, supported attributes, parameters, examples, and exceptions, see Select AI for Java API Reference (Javadoc).

Supported Environments

Select AI for Java has been validated with:

Note: DBMS_CLOUD_AI_AGENT is outside the scope of Select AI for Java version 1.0.0.

The SDK uses the Oracle JDBC Thin Driver for database connectivity. You can use the SDK with supported Oracle database deployments that provide the required Select AI database packages and privileges. Confirm the supported database and JDBC driver versions AI provider configuration, and required privileges before you deploy an application. See Oracle AI Database Select AI capability Matrix for the supported capabilities along with their database versions.

Download the SDK

Select AI for Java version 1.0.0 is published to Maven Central.

For Maven and Gradle applications, declare the SDK as a dependency. Maven or Gradle resolves the SDK and its runtime dependencies from Maven Central.

Use the Maven Central artifact page to download: Select AI for Java 1.0.0 on Maven Central

For API descriptions, classes, methods, parameters, and usage information, see the Select AI for Java API Reference (Javadoc).

Add Select AI for Java to Your Application

Select AI for Java is packaged as a standard Java JAR. The SDK JAR does not include its third-party runtime dependencies. Maven or Gradle resolves those dependencies from the published POM.

Select AI for Java version 1.0.0 requires JDK 17 or later.

Use the published Maven dependency for normal application development. See Download the SDK for details.

Add the SDK to a Maven Application

Add the following dependency to your application’s pom.xml:

<dependency>
    <groupId>com.oracle.database.selectai</groupId>
    <artifactId>select-ai</artifactId>
    <version>1.0.0</version>
</dependency>

Maven resolves the SDK and its transitive runtime dependencies from the published POM.

Add the SDK to a Gradle Application

For Gradle applications that use the Groovy DSL, add the following configuration to the build.gradle file: For example:

repositories {
    mavenLocal()
}

dependencies {
    implementation 'com.oracle.database.selectai:select-ai:1.0.0'
}

Note: The Gradle configuration uses the Maven Central artifact. It does not indicate a separate Gradle distribution.

Runtime Dependencies

The SDK JAR does not bundle third-party dependencies. When you use the SDK as a Maven or Gradle dependency, the dependency-management tool resolves the required direct and transitive dependencies from the published POM.

The SDK uses these primary runtime dependencies:

Dependency Version Purpose
com.oracle.database.jdbc:ojdbc11 23.26.1.0.0 Oracle JDBC Thin Driver
com.oracle.database.security:oraclepki 23.26.1.0.0 Oracle wallet and security support
org.slf4j:slf4j-api 2.0.17 Logging API used by the SDK
com.fasterxml.jackson.core:jackson-databind 2.22.0 JSON serialization and deserialization
Dependencies resolved transitively by Maven or Gradle Not applicable Additional libraries required by the direct dependencies, including Jackson core and annotations and Oracle security support dependencies

The SDK depends on the SLF4J API but does not include an SLF4J logging provider. Configure an SLF4J 2.x logging provider appropriate for your application. The standalone SDK samples use slf4j-simple.

If you use the SDK JAR directly instead of a dependency-management system, you must also make its runtime dependencies available on the application classpath. Use the dependencies resolved from the SDK pom.xml to ensure that you include the required direct and transitive dependencies.

To copy runtime dependencies for direct JAR usage, run:

mvn clean install
mvn -DincludeScope=runtime \
    -DoutputDirectory=target/dependency \
    dependency:copy-dependencies

Use the SDK JAR and the copied dependencies on the application classpath:

java -cp "target/select-ai-1.0.0.jar:target/dependency/*" \
    com.example.Application

On Windows PowerShell, use a semicolon (;) instead of a colon (:) in the classpath:

java -cp "target/select-ai-1.0.0.jar;target/dependency/*" `
    com.example.Application

Connect to Autonomous AI Database

Select AI for Java uses JDBC connections to communicate with Autonomous AI Database. You can provide connection information directly or supply a JDBC DataSource.

Manage JDBC connections

Choose a connection-management approach before creating Select AI objects. Use one consistent approach throughout an application or clearly document ownership when multiple components share the same database resources.

The SDK supports these connection modes:

DbConnection is a separate standalone connection-owner API.

When the application supplies a connection, be sure that the connection is open and configured for the intended database user. When the SDK obtains connections from a configuration or DataSource, follow the lifecycle rules documented in Select AI for Java API Reference (Javadoc).

Choose the mode that matches the connection-management model your application uses. Applications that already use a connection pool can provide its DataSource. Applications that manage connection properties directly can use the SDK connection configuration.

DbConnectionConfig

Use DbConnectionConfig to define database connection properties and connection-related options. In DbConnectionConfig mode, the SDK creates and owns a single JDBC connection for the SelectAI client. The SDK reuses this connection for operations performed by that client. The SDK closes the JDBC connection when you call SelectAI.close(). Because the client uses one retained JDBC connection, treat a DbConnectionConfig-based SelectAI client as single-threaded unless your application synchronizes access externally.

Use DbConnectionConfig for simple applications, command-line programs, samples, and applications that use one database connection for a SelectAI client. The configuration can include the database URL, authentication information, wallet or security settings, and optional runtime settings.

Keep connection information and secrets outside application source code. Use the credential and secret-management facilities recommended for your deployment.

For the complete list of supported properties, constructors, validation rules, and authentication options, see Select AI for Java API Reference (Javadoc).

DataSource

Use a DataSource when the application or application server owns connection creation and pooling. In DataSource mode, the application owns the DataSource. The SDK borrows a JDBC connection from the DataSource for each operation and closes the borrowed connection after the operation completes. When the DataSource uses a connection pool, closing the borrowed connection normally returns it to the pool. Calling SelectAI.close() does not close the application-owned DataSource.

Use DataSource mode for application servers, Spring or Jakarta applications, multi-threaded services, and applications that manage JDBC connection pools. A DataSource can integrate Select AI for Java with existing JDBC infrastructure and enterprise connection pools.

The application remains responsible for configuring the DataSource, pool capacity, validation, and security. The SDK uses the application-supplied DataSource for database operations.

Connection lifecycle

Close connections and other JDBC resources according to the ownership model used by the application. Release resources when an operation completes and do not retain short-lived connections longer than necessary.

When an application uses a connection pool, return connections to the pool instead of closing the pool-managed resource directly.

The SDK manages JDBC connection lifecycle according to the selected connection mode:

Connection mode Connection ownership Connection lifecycle
DbConnectionConfig SDK The SDK creates one connection, reuses it for client operations, and closes it when SelectAI.close() is called.
DataSource Application The SDK borrows a connection for each operation and closes it after the operation completes. The application continues to own the DataSource.

Resource objects such as Profile, Conversation, and VectorIndex use the connection lifecycle of their associated SelectAI client. They do not create or own a separate JDBC connection.

Threading Behavior

Select AI for Java supports different threading behavior based on the connection mode and how applications use SDK resource objects. The SDK does not make a global thread-safety guarantee for all public objects.

For DataSource mode, you can share a SelectAI client across threads for independent operations because each operation obtains its own JDBC connection.

For DbConnectionConfig mode, treat the SelectAI client as single-threaded unless your application synchronizes access to the retained JDBC connection.

Caution: Multiple threads can use separate resource instances for independent operations. If multiple threads use the same resource instance, do not modify that resource concurrently unless your application synchronizes access. For example, do not use multiple threads at the same time to modify the same resources such as Profile, Credential, Conversation, or VectorIndex instance. Do not concurrently create, update, enable, disable, or drop the same resource. If your application requires concurrent access to the same resource instance, synchronize access in the application.

Transaction Behavior

Select AI for Java uses JDBC transaction behavior. Transaction behavior depends on the connection configuration and the Oracle AI Database APIs used by the SDK. Configure auto-commit and transaction boundaries according to the requirements of the application and the database operation. Select AI for Java does not explicitly commit or roll back transactions and does not change the JDBC connection’s autoCommit setting.

In DbConnectionConfig mode, the SDK reuses its SDK-owned JDBC connection across operations. If autoCommit is disabled, SDK operations and custom JDBC statements that use the same connection participate in the connection’s transaction according to JDBC and Oracle AI Database transaction semantics.

In DataSource mode, the SDK borrows a JDBC connection for each operation and closes the connection after the operation completes. The SDK does not explicitly change the connection’s autoCommit setting or commit or roll back the transaction before returning the connection. The DataSource or connection pool controls how connection state and outstanding transactions are handled when a borrowed connection is returned to the pool.

Note: In DataSource mode, each SDK operation borrows a connection from the DataSource. Therefore, do not rely on uncommitted changes from one SDK operation being available to another operation.

SDK operations that create or modify profile, credential, conversation, and vector-index operations use the transaction behavior of the JDBC connection and the underlying Oracle AI Database API. Some underlying database APIs can perform an implicit commit or rollback. The SDK does not change or override that database behavior.

Note: In DbConnectionConfig mode, SelectAI.getConnection() returns the SDK-owned JDBC connection that the SDK uses for its operations. You can use this connection for custom JDBC work in the same database session. Whether SDK operations and custom JDBC statements can form a single atomic transaction depends on the transaction behavior of the underlying Oracle AI Database APIs.

Query Timeout

The query-timeout option configures the JDBC statement timeout. Use SelectAIOptions.queryTimeoutSeconds() to configure the JDBC statement query timeout for SDK operations. By default, the SDK does not configure a JDBC query timeout. An unset or null value means that the SDK does not call Statement.setQueryTimeout(). A value of 0 uses JDBC no-timeout behavior. The SDK rejects negative values.

The configured timeout applies to JDBC statements created for SDK operations. It controls the JDBC or database statement timeout; it does not configure:

If a database operation has already sent a request to an AI provider, a JDBC statement timeout does not guarantee cancellation of the provider request. Whether and when the JDBC driver interrupts the database call depends on Oracle JDBC and database behavior.

For details about SelectAIOptions,connection management, and resource operations, see Select AI for Java API Reference (Javadoc).

Before You Begin

Before using Select AI for Java:

  1. Confirm that the database release is supported.
  2. Obtain the database connection information and authentication required by the application.
  3. Configure the required AI provider and database credentials.
  4. Create or identify an AI profile for the intended workflow.
  5. Confirm that the database user has the privileges and network access required for the selected features.
  6. Review Perform Prerequisites for Select AI for setup requirements.

See Also:

Manage Database Privileges and Network Access

Select AI for Java provides the DatabaseAdmin interface for privileged database setup operations. Use the SelectAI interface for normal application operations.

Use DatabaseAdmin only in a separately controlled provisioning or administration workflow. Do not expose DatabaseAdmin to normal application users or include it in the application’s general runtime path.

DatabaseAdmin interface provides administrative methods to:

These operations require an appropriately privileged administrative database user. The database user that runs the application does not need DatabaseAdmin privileges unless that user also performs administrative setup.

Package Privileges

Use the DatabaseAdmin package-privilege methods to grant or revoke the database package privileges that Select AI users require.

To use Select AI, a database administrator grants EXECUTE on DBMS_CLOUD_AI to the database user. Select AI capabilities can require additional package privileges. For example, Retrieval-Augmented Generation (RAG) requires access to DBMS_CLOUD_PIPELINE.

Credential operations use DBMS_CLOUD and require the database user that manages credentials to have access to the corresponding DBMS_CLOUD APIs.

Package grants change privileges for the database users specified in the administrative request. Perform these grants during database or application provisioning rather than during normal application startup.

Note: DBMS_CLOUD_AI_AGENT is outside the scope of Select AI for Java version 1.0.0.

For the required privileges see Perform Prerequisites for Select AI.

Network Access

Use the DatabaseAdmin network-access methods only when a database administrator needs to configure outbound access for Select AI users.

The API provides:

Network ACL configuration is not required for every Select AI provider or database deployment. Configure network access only when the selected provider and deployment require it. For example, Select AI does not require a network ACL for OCI Generative AI.

Network ACL changes modify database network ACL configuration. The ACL configuration resides in the database rather than in the Java application or the target user’s schema. An access control entry identifies the database user or role that receives access, therefore configuring an ACL does not automatically grant network access to every database user.

Specify only the hosts that the application requires. A host can identify a host name, IP address, domain, or supported wildcard. When applicable, use the lower and upper port parameters to restrict access to the required TCP port range. If you do not specify a port range, the underlying network ACL rules determine access without a port restriction.

Network ACL changes remain part of the database configuration until an administrator changes or removes them. They are not temporary settings associated with the Java SDK process or JDBC session.

Caution: Network ACL changes affect database security configuration. Configure network access as part of a controlled provisioning or administration workflow. Do not grant DatabaseAdmin network-management privileges to the normal application runtime.

For provider endpoints and network requirements, see Perform Prerequisites for Select AI.

Select AI Data Access

Use DatabaseAdmin.enableDataAccess() and DatabaseAdmin.disableDataAccess() to control whether applicable Select AI features can send database data or vector-search document content to a large language model.

This setting applies to Select AI capabilities that require data access, including the narrate action, Retrieval-Augmented Generation (RAG), and synthetic data generation.

Only an administrator can change the Select AI data-access setting. The underlying DBMS_CLOUD_AI.ENABLE_DATA_ACCESS and DBMS_CLOUD_AI.DISABLE_DATA_ACCESS procedures do not accept a database user or schema parameter.

Treat changes to Select AI data access as administrative database configuration. Configure the required setting during provisioning or through an explicitly authorized administrative change, rather than during normal application startup.

Caution: Disabling Select AI data access can limit Select AI features that need to send database data or retrieved document content to the AI provider. Review the affected Select AI capabilities before changing this setting.

Administrative and Runtime Operations

Oracle recommends keeping administrative setup separate from normal application processing.

Operation Recommended Use
Grant or revoke Select AI package privileges One-time provisioning or an authorized administrative change
Grant or revoke HTTP access One-time provisioning or an authorized network configuration change
Grant or revoke general network access One-time provisioning or an authorized network configuration change
Enable or disable Select AI data access Controlled administrative configuration
Create and use profiles, conversations, and vector indexes Normal application workflow, after required privileges and configuration are in place
Process prompts and other Select AI requests Normal application runtime

Use a least-privilege database user for the normal application runtime. Do not grant administrative privileges to an application user solely so that the application can configure its own prerequisites at startup.

For the required Select AI privileges, credentials, provider configuration, and network requirements, see Perform Prerequisites for Select AI.

For the DatabaseAdmin methods, parameters, and exceptions, see Select AI for Java API Reference (Javadoc)

What You Can Do

The Select AI for Java SDK provides a Java API for working with Select AI resources.

The following table summarizes the primary Select AI for Java capabilities:

Capability Description
Natural-language-to-SQL Generate SQL from natural-language prompts using the GenerateAction.
Run generated SQL Generate SQL from a natural-language prompt and run the generated SQL by using Profile.runsql().
Show generated SQL Return the SQL generated from a natural-language prompt without running the SQL by using Profile.showsql().
Explain generated SQL Generate SQL and return a natural-language explanation of the SQL by using Profile.explainsql().
Narrate query results Generate and run SQL, and return a natural-language narration of the query results by using Profile.narrate().
Chat Send a general natural-language prompt to the AI provider configured in the AI profile by using Profile.chat().
Show augmented prompt Return the augmented prompt that Select AI prepares for the AI provider by using Profile.showprompt().
AI profiles Create and manage AI profiles that define AI providers, credentials, model settings, database objects, and vector indexes.
Credentials Create and drop database credentials used for AI provider or object storage access.
Conversations Create and manage conversations that maintain context across related prompts.
Retrieval-Augmented Generation Create and manage vector indexes that Select AI can use to retrieve relevant content for RAG. Configure an AI profile to use a vector index, and use the RAG-enabled profile to retrieve relevant content from the vector store and augment the prompt sent to the AI provider. For more information, see Select AI with Retrieval Augmented Generation (RAG).
Synthetic data Generate synthetic data for one database object or a group of related objects. For more information, see Synthetic Data Generation.
Summarization Summarize inline text or content identified by an external location by using Profile.summarize(). For more information, see Generate a Summary with Select AI.
Translation Translate text in the supported languages by using the provider configured in an AI profile by using Profile.translate(). Select AI Translate supports OCI, Google, AWS, and Azure. Each provider has its own authentication, authorization, and service requirements. The languages available for translation depend on the selected provider and its translation service. For provider-specific requirements and supported translation functionality, see Translate.
Feedback Provide positive or negative feedback for NL2SQL generation by using Profile.feedback(). Positive feedback confirms generated SQL for future reference. With negative feedback, you can identify problems with the generated SQL and provide the expected SQL or additional guidance. Select AI associates feedback with the AI profile and the specified SQL ID or SQL text and stores the feedback in a profile-specific feedback vector index. Select AI can use stored feedback as hints for similar prompts during subsequent SQL generation. For more information, see Feedback.
Network configuration Manage package privileges, data access, HTTP access, and network ACL access through the DatabaseAdmin through methods in the DatabaseAdmin interface.
JDBC connection management Use an SDK-owned JDBC connection or an application-managed DataSource.

For Java API details, see Select AI for Java API Reference (Javadoc).

Supported Classes

Select AI for Java provides public interfaces and model classes for application operations, administrative configuration, connection management, and Select AI resource configuration.

Application code should use the public interfaces in com.oracle.database.selectai and the related model types in com.oracle.database.selectai.model. Classes in com.oracle.database.selectai.impl are internal implementation classes and are not intended for direct application use.

Primary Application Classes

Use these classes for common Select AI application workflows.

Class or interface Purpose
SelectAI Provides the main application entry point for Select AI. Use it to work with profiles, credentials, conversations, and vector indexes and to perform collection-level operations.
Profile Creates and manages AI profiles and provides prompt, summarization, translation, feedback, and synthetic data operations.
Credential Creates and drops database credentials.
Conversation Creates and manages Select AI conversations and their prompt metadata.
VectorIndex Creates and manages vector indexes used by Retrieval-Augmented Generation (RAG).

Administrative Classes

Use the DatabaseAdmin interface separately from normal application processing.

Class or interface Purpose
DatabaseAdmin Manages Select AI package privileges, data access, HTTP access, and network ACL configuration.

Use DatabaseAdmin only in a separately controlled provisioning or administration workflow. For more information, see Manage Database Privileges and Network Access.

Configuration and Request Models

Use the following model classes to configure SDK resources and operations.

Class Purpose
DbConnectionConfig Defines JDBC connection configuration for an SDK-owned connection.
SelectAIOptions Defines optional SDK settings, including the JDBC statement query timeout.
ProfileAttributes Defines AI profile attributes.
CredentialConfig Defines database credential configuration.
ConversationAttributes Defines conversation metadata.
VectorIndexConfig Defines vector-index creation configuration.
VectorIndexAttributes Defines vector-index attributes.
Feedback Defines feedback for NL2SQL generation.
SummaryParams Defines optional summarization parameters.
SyntheticDataSingleRequest Defines a synthetic-data request for one database object.
SyntheticDataBatchRequest Defines a synthetic-data request for multiple database objects.
SelectAIException Reports JDBC, database, DBMS_CLOUD, and DBMS_CLOUD_AI errors through the SDK.

Connection APIs and Extension Points

The SDK provides public connection interfaces and extension points for applications that require direct JDBC connection access or custom connection handling.

Class or interface Purpose
DbConnection Provides a standalone SDK-owned JDBC connection. The application closes the DbConnection when it no longer needs the connection.
ConnectionProvider Defines the public abstraction that supplies JDBC connections for SDK operations.
ConnectionCallback<T> Defines work that uses a JDBC connection supplied through a ConnectionProvider.

For most applications, use DbConnectionConfig or an application-managed DataSource with SelectAI. Use the connection extension points only when your application requires custom JDBC connection handling.

For connection ownership, lifecycle, transaction, and threading behavior, see Connect to Autonomous AI Database.

Provider Classes

Select AI for Java represents AI providers through the Provider enumeration and provider-specific configuration classes for supported AI providers. Use the appropriate provider configuration when you configure an AI profile.

Select AI for Java includes the following provider configuration classes:

Use the provider configuration appropriate for the provider that you configure in ProfileAttributes. For provider prerequisites and configuration requirements, see Perform Prerequisites for Select AI.

Internal Implementation Classes

Classes in the com.oracle.database.selectai.impl package implement the public SDK interfaces and manage internal JDBC and database interactions.

Note: Classes in the com.oracle.database.selectai.impl package provide the internal implementations of the public SDK interfaces. These classes are not supported as application-facing APIs and can change independently of the public API. Use the public interfaces and factory methods in com.oracle.database.selectai instead.

For complete information about public classes, interfaces, model types, methods, and extension points, see Select AI for Java API Reference (Javadoc).

Work with Credentials

A database credential stores authentication information that Autonomous AI Database uses to access an AI provider or an external service such as Object Storage.

Create the required credential before creating an AI profile or vector index that references it. The database user that creates the credential owns it, and the credential name identifies it within that user’s schema.

Create and Manage Credentials

Use SelectAI.credential(CredentialConfig) to create a Credential object from the credential configuration. This method creates a Java Credential object only; it does not create the credential in the database. Call Credential.create() on the returned Credential object to create the database credential.

Use the following Credential methods:

The CredentialConfig class defines the credential creation details, including the credential name and supported authentication information.

Credential Ownership

The database user that creates the credential owns the credential. The credential name identifies the credential in that user’s schema.

The SDK does not provide a method to retrieve the stored secret values of a credential. Protect passwords, private keys, fingerprints, OCIDs, and complete credential configurations. Do not include secrets in source code, logs, error reports, or prompts.

AI Provider Credentials

AI provider credentials store the authentication information required to access the configured AI provider.

Configure an AI provider credential when the AI profile requires a database credential for provider authentication. The profile references the credential by name through its profile configuration.

For OCI authentication, CredentialConfig supports credential configuration that includes the credential name, user OCID, tenancy OCID, private key, and fingerprint.

Object Storage Credentials

Use a database credential to authenticate access to Object Storage when a vector index uses content stored there.

The Select AI for Java SDK does not define a separate Java type for an Object Storage credential. Create the database credential by using methods in the Credential interface. Specify the credential for Object Storage access in the vector-index configuration.

VectorIndexAttributes defines the Object Storage credential attribute, along with other vector-index attributes such as the source location.

The same database credential can be referenced by multiple Select AI resources when they require the same authentication information.

Drop a Credential

Use Credential.drop() or Credential.drop(boolean force) to remove a credential.

Dropping a credential does not automatically update AI profiles or vector indexes that reference it. If a resource still references the dropped credential, an operation that requires the credential can fail.

Caution: Before dropping a credential, identify the AI profiles, vector indexes, and other resources that reference it. Update or remove those dependencies as required.

OCI Resource Principals and Instance Principals

Some OCI authentication configurations can use resource principals or instance principals instead of stored user credentials. When the selected provider and database environment support these authentication methods, you can use the supported OCI authentication configuration without storing user signing information in a database credential.

For provider-specific authentication requirements, see Perform Prerequisites for Select AI.

For credential configuration, supported authentication properties, lifecycle operations, and exceptions, see Select AI for Java API Reference (Javadoc).

Work with AI Profiles

An AI profile defines how Select AI communicates with an AI provider and which database objects and vector indexes Select AI can use. A profile can include provider, model, credential, object-list, conversation, translation, and vector-index settings.

Use the Profile interface to create and manage AI profiles and perform Select AI operations. All methods in the Profile interface are synchronous. The calling thread waits for each operation to complete or return an error.

Configure an AI Profile

Use the ProfileAttributes class to configure an AI profile. The profile configuration depends on the provider and the Select AI capability that you use.

Specify the provider and other attributes required by that provider. Provider-specific attributes can include the model, credential, endpoint, region, compartment, and other provider settings.

Configure a database credential where the selected provider and authentication method require one. Some supported authentication methods do not require a stored database credential.

Use the provider-specific configuration classes in ProviderProfile to define provider settings. For the required and optional attributes for each provider, see Perform Prerequisites for Select AI.

Create an AI Profile

Use SelectAI.profile(String profileName, ProfileAttributes profileAttributes, String description, ProfileStatus status) to create a Java Profile object initialized with the profile configuration.

This method does not create the AI profile in the database. Call Profile.create() on the returned object to create the database profile.

For example:

ProfileAttributes attributes =
    ProfileAttributes.builder()
        .provider(Provider.OCI)
        // Add provider-specific attributes.
        .build();

Profile profile =
    selectAI.profile(
        "MY_PROFILE",
        attributes,
        "Select AI profile",
        ProfileStatus.ENABLED);

profile.create();

The required ProfileAttributes values depend on the selected provider, authentication method, and profile functionality. Configure any required credential before you create a profile that references it.

For a complete profile-creation example for your provider, see Select AI for Java API Reference (Javadoc).

Use an Existing AI Profile

Use SelectAI.profile(String profileName) to open an existing AI profile in the current schema. The method returns a Profile object that you can use for profile operations.

For example:

Profile profile = selectAI.profile("MY_PROFILE");

String sql = profile.showsql("Show the total sales by region");

Use the Profile interface to:

Configure Database Objects for NL2SQL

Use the profile object-list configuration to control which database objects Select AI considers when generating SQL.

The ProfileAttributes class supports object-list configuration and the ObjectListMode values AUTOMATED and ALL. The profile’s object-list settings determine the database metadata that Select AI makes available for natural-language SQL generation.

The object list does not grant database privileges. The database user must have the required privileges on the objects that the profile uses.

For object-list configuration and object-selection behavior, see Manage AI Profiles.

Configure Vector Indexes for RAG

Associate vector indexes with an AI profile to use Retrieval-Augmented Generation (RAG). The ProfileAttributes class provides the vector-index settings that the profile uses.

When you use a RAG-enabled profile, Select AI retrieves relevant content from the configured vector index and adds that content to the augmented prompt sent to the AI provider.

Create and configure the required vector index before using it with the profile. For more information, see Select AI with Retrieval Augmented Generation (RAG).

Use Profiles Across Select AI Interfaces

The Profile.create() method creates the AI profile as a database resource. The Java Profile object provides a Java representation of that database profile.

Because the profile resides in the database rather than in the Java process, other Select AI interfaces that can access the same database profile can use it according to their database privileges and supported profile functionality. This includes SQL and PL/SQL interfaces and other supported Select AI SDKs or APIs.

Summarize and Translate Content

Use the Profile.summarize() method to summarize inline content or content at an external location. For each summarization request, specify either inline content or a location URI, but not both.

Use the Profile.translate() method to translate text with a supported translation provider configured in the profile. Provider-specific authentication, language support, and service requirements apply.

For more information, see Generate a Summary with Select AI and Translate.

Provide SQL Feedback

Use the Profile.feedback() method to submit positive or negative feedback for NL2SQL generation.

Positive feedback confirms generated SQL for future reference. Negative feedback can identify problems with generated SQL and provide expected SQL or additional guidance. Select AI can use relevant stored feedback as hints for similar prompts during subsequent SQL generation.

For more information, see Feedback.

For complete information about the Profile interface, ProfileAttributes class, provider-specific configuration, profile lifecycle methods, generation methods, and examples, see Select AI for Java API Reference (Javadoc).

Work with Conversations

A Conversation object represents a Select AI conversation stored in the database. Use a conversation to retain context and prompt history across related Select AI interactions.

A conversation is a database resource identified by a conversation ID. It is not permanently associated with one AI profile. Applications can use the conversation identifier with Select AI operations that support conversational context, subject to the profile configuration and database privileges of the application.

Create a Conversation

Use SelectAI.conversation(ConversationAttributes) to create a Java Conversation object initialized with conversation attributes.

This method does not create the conversation in the database. Call Conversation.create() on the returned object to create the database conversation. The create() method returns the generated conversation identifier.

Conversation Attributes

Use ConversationAttributes to configure conversation metadata, including:

The retentionDays attribute specifies how long Select AI retains the conversation. The conversationLength attribute specifies the amount of conversation context that Select AI retains for related interactions.

Use Conversation.getConversationAttributes() to retrieve the current attributes of an existing conversation. Use Conversation.setAttributes() to update supported conversation attributes.

Select AI stores conversation prompt history in the database. Use Conversation.listPrompts() to retrieve prompts recorded for the conversation, ordered by creation time. Use Conversation.deletePrompt() to remove an individual prompt. Removing an individual prompt with deletePrompt() does not remove the conversation. Use Conversation.drop() to remove the conversation from the database.

Preserve the conversation identifier when subsequent application operations need to access the same conversation.

Use an Existing Conversation

Use SelectAI.conversation(String conversationId) to open an existing conversation by its conversation identifier.

After you open or create a conversation, use the Conversation interface to:

Conversation Lifecycle

A Java Conversation object does not automatically remove the corresponding database conversation when the Java object goes out of scope or when the SelectAI client closes.

Manage the database conversation lifecycle explicitly. Call Conversation.drop() when the application no longer requires the conversation.

Note: The current Select AI for Java SDK does not define a separate public session lifecycle that automatically deletes a conversation when the session closes. Manage conversations through the Conversation interface and the conversation identifier.

Threading Behavior for Conversations

The SDK does not provide a global thread-safety guarantee for Conversation objects.

Multiple threads can use separate Conversation instances for independent operations. Do not use multiple threads at the same time to update, delete prompts from, or drop the same Conversation instance unless your application synchronizes access.

For general SDK threading behavior and connection-mode considerations, see Threading Behavior.

Guidelines for Conversations

Treat conversation identifiers and conversation content as application data. A conversation can contain prompts and metadata derived from database interactions or sensitive business information.

Do not include conversation identifiers, prompts, or conversation content in logs, error reports, or other output unless your application’s security and logging policies allow it. Restrict database access to conversations according to the application’s access-control requirements.

For complete information about the Conversation interface, ConversationAttributes class, conversation lifecycle methods, prompt metadata, and examples, see Select AI for Java API Reference (Javadoc).

Work with Vector Indexes

Vector indexes support Retrieval-Augmented Generation (RAG) workflows. A vector index stores searchable representations of source content so that Select AI can retrieve relevant information for an AI response.

Use the VectorIndex interface to create, retrieve, update, enable, disable, and remove vector indexes. Configure the vector index with the source location, credential, embedding settings, and other attributes required by the intended RAG workflow.

Use Vector Indexes with RAG

After you create a vector index, configure an AI profile to use the index for RAG.

The vector index provides the retrieved source content. The RAG-enabled profile provides the AI provider and model configuration used to process the user’s prompt and the retrieved content.

You can use the same vector index with multiple profiles when those profiles support the required RAG configuration.

Create a Vector Index

Use SelectAI.vectorIndex(VectorIndexConfig) to create a Java VectorIndex object from a vector-index configuration. This method creates the Java object; it does not create the vector index in the database.

Call VectorIndex.create() to create the vector index in the database.

When the SDK creates a vector index, the database:

  1. Reads the content from the configured source location.
  2. Uses the profile and provider configured for the vector index to generate embeddings.
  3. Stores the generated vectors for retrieval during RAG operations.

The VectorIndexConfig class provides the create-time configuration, including the vector index name, profile name, status, description, wait-for-completion setting, and vector-index attributes.

Embedding and RAG Profiles

The profile specified in the vector-index configuration provides the provider and embedding configuration that the database uses to create embeddings for the source content.

The profile used to create embeddings does not automatically determine which profile an application uses for RAG requests. Configure a profile for RAG separately by specifying the vector index in its ProfileAttributes configuration.

The RAG workflow uses AI profiles in different roles. The following table maps each resource in the workflow to the corresponding Select AI for Java resource or configuration.

Resource Java resource or configuration Purpose
Embedding profile Profile and ProfileAttributes Provides the provider and embedding configuration used to create embeddings for the source content. Specify the profile name in VectorIndexConfig when you configure the vector index.
Vector index VectorIndex, VectorIndexConfig, and VectorIndexAttributes Configures and manages the vector index that stores generated vectors and provides content for retrieval.
RAG profile Profile and ProfileAttributes References the vector index in the profile configuration and provides the provider and model configuration used to process RAG requests.

When the RAG-enabled profile processes a request, Select AI retrieves relevant content from the vector index and adds that content to the augmented prompt sent to the AI provider.

For more information, see Select AI with Retrieval Augmented Generation (RAG).

Monitor Vector Index Creation

Vector-index creation can run synchronously or asynchronously based on the waitForCompletion setting in VectorIndexConfig.

waitForCompletion Behavior
true VectorIndex.create() waits for vector-index creation to complete before it returns.
false VectorIndex.create() returns without waiting for vector-index creation to finish.

Use VectorIndex.getStatus() to retrieve the current status of a database-backed vector index. Use VectorIndex.getVectorIndexAttributes() to retrieve its current attributes.

If vector-index creation fails, VectorIndex.create() reports the database or JDBC failure through SelectAIException.

The SDK does not provide a separate progress interface or asynchronous job object for vector-index creation.

Refresh Vector Indexes

A vector index can use a configured refresh rate to control how the index processes source content changes.

When the source documents change, the database updates the vector index according to the configured refresh behavior. Configure the refresh rate in VectorIndexAttributes.

The application does not need to recreate the vector index solely because the source content changes when the configured refresh behavior supports the required updates.

The required source location and credential must remain available while the vector index processes or refreshes its content.

For supported refresh attributes and configuration, see Select AI for Java API Reference (Javadoc).

Update a Vector Index

Use VectorIndex.update(VectorIndexAttributes) or the single-attribute update() methods to update supported vector-index attributes.

Some attributes apply only when you create the vector index and cannot be changed later. The database determines whether an attribute can be updated.

Build the update request with only the attributes that the database supports for modification. For example, chunk_size is a create-time attribute and cannot be updated after the vector index is created.

Use VectorIndex.getVectorIndexAttributes() to retrieve the current attributes of an existing vector index before making changes.

Enable or Disable a Vector Index

Use the following methods to control whether Select AI can use a vector index for RAG retrieval.

Method Effect
VectorIndex.enable() Enables the vector index for RAG retrieval.
VectorIndex.disable() Disables the vector index. Select AI does not use the vector index for retrieval until you enable it again.

Enabling or disabling a vector index does not remove the vector data.

Drop a Vector Index

Use VectorIndex.drop(boolean force) to remove the vector index.

This form removes both the vector-index metadata and the backing vector data.

Use VectorIndex.drop(boolean includeData, boolean force) when you need to control whether the backing vector data is removed.

includeData Behavior
true Removes the backing vector data together with the vector-index metadata.
false Retains the backing vector data when the underlying database operation supports this option.

Caution: Before dropping a vector index, identify any RAG-enabled profiles or applications that use it. Verify whether the underlying vector data must be retained before selecting the drop option.

For complete runnable sample sources, see vectorindex.

For database configuration and RAG concepts, see Perform Prerequisites for Select AI and Select AI with Retrieval Augmented Generation (RAG).

For information about supported attributes, creation options, status values, update methods, and drop methods, see Select AI for Java API Reference (Javadoc).

Generate Synthetic Data

Select AI for Java can generate synthetic data for a single database object or for multiple related database objects. Use synthetic data for testing, development, prototyping, and analysis. Synthetic data generation uses the AI provider configured in the associated Profile object.

Use Profile.generateSyntheticData(SyntheticDataSingleRequest) to generate synthetic data for one database object. Use Profile.generateSyntheticData(SyntheticDataBatchRequest) to generate synthetic data for multiple objects.

A request can specify:

The generated data targets the database objects specified in the request. The Java methods return a Boolean result that indicates whether the database operation succeeded; they do not return the generated rows to the caller.

Prerequisites for Generating Synthetic Data

Before you generate synthetic data:

For the required Select AI privileges and database setup, see Perform Prerequisites for Select AI.

Generate Data for Related Objects

Use SyntheticDataBatchRequest when you need to generate data for multiple related database objects.

The batch request can include multiple objects and their generation settings. Use this form when the generated data must reflect relationships between the specified objects.

The request supports a specified number of rows for synthetic data generation. The effective limit can depend on the underlying database functionality, provider, and database resources.

If a single-object or batch generation operation fails, the SDK reports the database or JDBC failure through SelectAIException.

Caution:

Synthetic data generation uses a large language model to produce the requested data. Review generated data before using it in downstream systems, particularly when the target objects have:

Do not use synthetic data generation to reproduce real personal information or sensitive production data.

Transaction Behavior for Synthetic Data Generation

Synthetic data generation follows the transaction behavior of the JDBC connection that the Profile object uses.

The SDK does not explicitly commit or roll back the transaction. In DbConnectionConfig mode, the operation uses the SDK-owned JDBC connection. In DataSource mode, the operation uses a connection borrowed from the application-managed DataSource.

For more information about transaction behavior, see Connect to Autonomous AI Database.

For information about supported parameters and exceptions, see Select AI for Java API Reference (Javadoc).

Retrieve and Update Existing Objects

Select AI for Java represents profiles, conversations, credentials, and vector indexes as database-backed Java objects.

Use the supported retrieval methods to obtain current information about existing objects. Depending on the object, returned information can include the name, identifier, description, status, attributes, and metadata.

Update only attributes supported by the underlying Select AI database APIs. An update does not necessarily replace the complete object. Retrieve the object when the application needs current database state, and confirm that the object exists before performing an object-specific operation.

Collection retrieval returns objects accessible to the connected database user.

For supported retrieval methods, update operations, request objects, and return values, see Select AI for Java API Reference (Javadoc).

Delete Objects

Remove profiles, credentials, conversations, and vector indexes that the application no longer requires.

Before deleting an object:

Some resource methods provide a force-removal option that treats an already absent object as a successful result. Use that option only when the application can safely accept an absent object as the final state.

For object-specific removal methods, dependency behavior, and exceptions, see Select AI for Java API Reference (Javadoc).

Use Synchronous APIs

Select AI for Java 1.0.0 provides only synchronous Java APIs. The SDK does not provide asynchronous APIs or streaming profile operations. Use the synchronous APIs when the application can wait for each database operation to finish before continuing.

A synchronous method waits for the database operation to complete or return an error before control returns to the calling application. Operations that communicate with an AI provider or perform long-running database processing can therefore block the calling thread for an extended period.

For multi-threaded applications, use DataSource mode and size the connection pool for the expected concurrency and workload. For information about JDBC query timeouts, see Transaction Behavior.

Note: A JDBC query timeout does not configure AI provider request timeouts or guarantee cancellation of a provider request that is already in progress.

For the synchronous methods available in this release, see Select AI for Java API Reference (Javadoc).

Handle Errors

Select AI for Java reports locally detected validation errors through standard Java exceptions and reports database, JDBC, DBMS_CLOUD, DBMS_CLOUD_AI, and provider failures through SelectAIException.

The SDK validates request information that it can check before JDBC processing. The database and JDBC driver validate database privileges, resource state, package requirements, provider configuration, network access, and other database-side requirements.

Handle SDK Exceptions

The SDK uses the following exceptions for common error conditions:

Exception When it occurs
IllegalArgumentException The application supplies an invalid argument or configuration value. Examples include null or blank required values, invalid port ranges, negative timeout values, and invalid credential combinations.
IllegalStateException The application uses an SDK resource in an invalid lifecycle state. For example, an operation requires a resource that has already been created or opened.
SelectAIException JDBC, DBMS_CLOUD, DBMS_CLOUD_AI, or the configured AI provider reports a failure through the SDK.

SelectAIException inherits from Exception, making it a checked exception that callers must explicitly handle or declare. Public database-backed methods declare SelectAIException, including profile generation and lifecycle methods, conversation operations, vector-index operations, credential operations, DatabaseAdmin operations, and SDK-owned connection creation and cleanup.

For the exception declaration for an individual method, see Select AI for Java API Reference (Javadoc).

Client-Side and Database-Side Validation

The SDK validates supported inputs before JDBC processing when it can determine the validity from the Java request.

The SDK detects conditions such as:

These conditions normally result in IllegalArgumentException or IllegalStateException before JDBC processing.

The database validates conditions that depend on database configuration, resources, or remote services. These conditions include:

The SDK reports these database-side failures through SelectAIException.

Handle SelectAIException

Catch SelectAIException to handle failures from database-backed Select AI operations.

For example:

try (SelectAI selectAI = SelectAI.create(dataSource)) {
    Profile profile = selectAI.profile("MY_PROFILE");
    String response = profile.chat("Show the top five products");
} catch (SelectAIException exception) {
    System.err.println(exception.getMessage());
    System.err.println(exception.getErrorCode());
    System.err.println(exception.getSqlState());
}

Record enough diagnostic information to troubleshoot the failure, but do not record passwords, private keys, tokens, or complete credential configurations.

For the exception hierarchy, error details, and operation-specific behavior, see Select AI for Java API Reference (Javadoc).

Inspect Error Details

Use the following SelectAIException methods to inspect available error information:

Method Description
getErrorCode() Returns the JDBC or Oracle error code when available.
getSqlState() Returns the SQLState when available.
getCause() Returns the underlying exception, including the underlying JDBC exception when available.

Provider failures do not use a separate Java provider-exception type. DBMS_CLOUD or DBMS_CLOUD_AI normally receives a provider failure, reports it through the database and JDBC layers, and the SDK wraps the failure in SelectAIException.

For example, an HTTP error returned by an AI provider can appear as an Oracle error such as ORA-20400. Inspect the SelectAIException error details and underlying cause for the diagnostic information available for the operation.

For the complete SelectAIException methods and return values, see Select AI for Java API Reference (Javadoc).

Retry Failed Operations

Select AI for Java does not automatically retry failed operations.

You can consider retrying a read-only metadata operation after confirming that a connection failure was transient.

Do not automatically retry creation, update, deletion, administrative, generation, or chat operations. The database or AI provider might have started processing the request before the application received the failure.

Before retrying an operation that can change database state or send a request to an AI provider, verify the current operation or resource state and confirm that repeating the request is safe.

Timeout and Server-Side Work

The queryTimeoutSeconds setting configures the JDBC statement timeout. It does not necessarily configure:

A JDBC timeout can stop the application from waiting for the JDBC statement while database-side or provider-side processing continues.

Caution: Do not assume that a timed-out operation stopped processing. Before retrying the operation, verify the state of the affected database resource or operation and consider whether the AI provider might still be processing the original request.

For more information, see Transaction Behavior.

Troubleshoot Errors

When an operation fails:

  1. Review the SelectAIException message, Oracle error code, SQLState, and underlying cause when available.
  2. Confirm that the database user has the required privileges.
  3. Confirm that the referenced profile, credential, conversation, or vector index exists and has the required state.
  4. Verify the provider configuration and credential where required.
  5. Verify network access and ACL configuration when the provider or data source requires it.
  6. For provider failures, review the Oracle error and underlying diagnostic information returned through DBMS_CLOUD or DBMS_CLOUD_AI.
  7. For a timeout or connection failure, verify the operation or resource state before retrying the request.

For complete information about SelectAIException, method-specific exceptions, validation behavior, and error handling, see Select AI for Java API Reference (Javadoc).

Select AI for Java Examples

Explore the Select AI for Java examples for sample Java code that demonstrates how to configure and use Select AI for Java features. Use these examples with the Select AI for Java API Reference (Javadoc) to understand the classes, methods, and configuration used in each workflow.