Package com.oracle.database.selectai

Interface Conversation

public interface Conversation

Contract for Select AI conversation lifecycle and metadata management.

A conversation stores chat context so a later prompt can refer to earlier turns. The Conversation object manages the database conversation and its metadata, such as title, description, retention period, and context length.

A Conversation object can be configured for creation or database-backed. A configured conversation has attributes in memory, but it does not have a database conversation ID until create() succeeds. A database-backed conversation 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 conversation, such as drop, metadata update, prompt listing, and prompt deletion, require a database-backed conversation. The SDK rejects those operations with IllegalStateException when the object is not bound to a conversation ID or is configured for creation but has not been created yet.

See Also:

• DBMS_CLOUD_AI conversation reference

Method Summary

Modifier and Type	Method	Description
String	create()	Creates the configured conversation in the database and returns its generated conversation identifier.
boolean	deletePrompt(String conversationPromptId)	Deletes a conversation prompt.
boolean	deletePrompt(String conversationPromptId, boolean force)	Deletes a conversation prompt.
boolean	drop(boolean force)	Drops this conversation from the database.
ConversationAttributes	getConversationAttributes()	Returns conversation metadata.
String	getConversationId()	Returns the database identifier for this conversation.
List<ConversationPrompt>	listPrompts()	Lists prompts recorded for this conversation.
boolean	setAttributes(ConversationAttributes conversationAttributes)	Updates conversation metadata such as title, description, retention, or context length.

Method Details

getConversationId

String getConversationId()

Returns the database identifier for this conversation.

For a complete runnable sample source, see GetConversationIdSample source.

Returns:

conversation ID

drop

boolean drop(boolean force)
      throws SelectAIException

Drops this conversation from the database.

For a complete runnable sample source, see DropConversationSample source.

Parameters:

force - when true, performs force drop if supported

Returns:

true when drop succeeds

Throws:

IllegalStateException - when this Conversation instance is not bound to a conversation ID or is configured for creation but has not been created yet

SelectAIException - when the database conversation cannot be dropped

create

String create()
       throws SelectAIException

Creates the configured conversation in the database and returns its generated conversation identifier.

Call this after obtaining a conversation object from SelectAI.conversation(ConversationAttributes). For a complete runnable sample source, see CreateConversationSample source.

Returns:

conversation ID returned by DBMS_CLOUD_AI.CREATE_CONVERSATION

Throws:

SelectAIException - when the conversation cannot be created

getConversationAttributes

ConversationAttributes getConversationAttributes()
                                          throws SelectAIException

Returns conversation metadata.

For a configured conversation that has not been created yet, returns the attributes supplied by the caller. For a conversation bound to a conversation ID, refreshes metadata from the database before returning attributes. For a complete runnable sample source, see GetConversationAttributesSample source.

Returns:

conversation attributes

Throws:

SelectAIException - when bound conversation metadata cannot be fetched

setAttributes

boolean setAttributes(ConversationAttributes conversationAttributes)
               throws SelectAIException

Updates conversation metadata such as title, description, retention, or context length.

For a complete runnable sample source, see SetConversationAttributesSample source.

Parameters:

conversationAttributes - attributes to set

Returns:

true when update succeeds

Throws:

IllegalStateException - when this Conversation instance is not bound to a conversation ID or is configured for creation but has not been created yet

SelectAIException - when update fails

listPrompts

List<ConversationPrompt> listPrompts()
                              throws SelectAIException

Lists prompts recorded for this conversation.

For a complete runnable sample source, see ListConversationPromptsSample source.

Returns:

prompt rows for this conversation ordered by creation time

Throws:

IllegalStateException - when this Conversation instance is not bound to a conversation ID or is configured for creation but has not been created yet

SelectAIException - when the prompt metadata cannot be fetched

deletePrompt

boolean deletePrompt(String conversationPromptId)
              throws SelectAIException

Deletes a conversation prompt.

For a complete runnable sample source, see DeleteConversationPromptSample source.

Parameters:

conversationPromptId - conversation prompt identifier

Returns:

true when delete succeeds

Throws:

IllegalStateException - when this Conversation instance is not bound to a conversation ID or is configured for creation but has not been created yet

SelectAIException - when the prompt cannot be deleted

deletePrompt

boolean deletePrompt(String conversationPromptId,
 boolean force)
              throws SelectAIException

Deletes a conversation prompt.

For a complete runnable sample source, see DeleteConversationPromptSample source.

Parameters:

conversationPromptId - conversation prompt identifier

force - when true, performs force delete if supported

Returns:

true when delete succeeds

Throws:

IllegalStateException - when this Conversation instance is not bound to a conversation ID or is configured for creation but has not been created yet

SelectAIException - when the prompt cannot be deleted