DBMS_CLOUD_AI Package

profile_name

A name for the AI profile. The profile name must follow the naming rules of Oracle SQL identifier. Maximum length of profile name is 125 characters.

This is a mandatory parameter.

attributes

Profile attributes in JSON format. See AI Profile Attributes for more details.

The default value is NULL.

Status of the profile.

The default value is enabled.

description

Description for the AI profile.

The default value is NULL.

annotations

Provides additional metadata about your database tables and columns using the 26ai annotations feature.

The valid values are TRUE or FALSE. The default value is FALSE. The values are not case sensitive.

TRUE: Augments the user prompt with table-level and column-level annotations in addition to other metadata to the LLM.

FALSE: Does not include annotations as part of the augmented prompt metadata.

azure_deployment_name

Name of the Azure OpenAI Service deployed model. The name can only include alphanumeric characters, underscore character (_) and a hyphen (-) character. The name cannot end with an underscore (_) or a hyphen (-). To know how to get the azure_deployment_name, see Create and deploy an Azure OpenAI Service resource.

azure_embedding_deployment_name

Name of the Azure OpenAI deployed embedding model.

The name can only include alphanumeric characters, underscore, and hyphen. The name can't start or end with a hyphen or underscore.

azure_resource_name

Name of the Azure OpenAI Service resource. The resource name can only include alphanumeric characters and hyphens, and can't start or end with a hyphen. To know how to get the azure_resource_name, see Create and deploy an Azure OpenAI Service resource.

case_sensitive_values

Specifies whether Select AI should instruct the LLM to generate case-insensitive SQL for columns containing string or text values.

The supported values are:

The default value is false.

comments

Includes table and column comments in the metadata used for translating natural language prompts using AI. BOOLEAN data type is supported. The valid values are TRUE or FALSE for a string with VARCHAR2 data type. The values are not case sensitive.

constraints

Manages whether to include referential integrity constraints such as primary and foreign keys in the metadata sent to the LLM.

The valid values are TRUE or FALSE. The default value is FALSE. The values are not case sensitive.

TRUE: Includes referential constraints in the augmented prompt metadata that is sent to the LLM.

FALSE: Does not include referential integrity constraints.

conversation

A VARCHAR2 attribute that indicates if conversation history is enabled for a profile. Valid values are true or false. The default value is false. The values are not case sensitive.

credential_name

The name of the credential to access the AI provider APIs.

Credential using bearer tokens can be created by using the provider name as the user name and bearer token as the password.

Vault Secret credentials are also supported.

Principal authentication, for example, Azure service principal, is also supported. For more information on how to configure it, see Use Azure Service Principal to Access Azure Resources.

This is a mandatory attribute. See CREATE_CREDENTIAL Procedure.

embedding_model

The embedding model defined in the AI profile. The following are the supported AI providers for the embedding models with their default values:

enforce_object_list

Specifies whether to restrict the LLM to generate SQL that uses only tables covered by the object list.

The supported values are:

• true: Enforces the use of only the tables specified in the object list.

• false: Allows the LLM to use tables accessible to the user.

The values are not case sensitive. The default value is false.

max_tokens

Denotes the number of tokens to predict per generation. Default is 1024. See Tokens and Tokenizers for more details.

model

The name of the AI model being used to generate responses.

See Select your AI Provider and LLMs and specify the model name.

object_list

Array of JSON objects specifying the owner and object names that are eligible for natural language translation to SQL. To include all objects of a given user, omit the "name" and only specify the "owner" key in the JSON object.

The following types of objects can be used:

• tables
• views
• materialized views
• global temporary tables
• external tables
• synonyms on the above object types

For translation natural language to SQL, the object name, object owner, object columns and comments are sent to the AI provider using HTTPS requests. Avoid specifying objects with sensitive object name, column names or comments in the object list.

AI providers may have limit on the size of metadata allowed in translation requests. Consider limiting the list of objects suitable for the natural language prompts by your application users.

[
  {"owner": "SH", "name": "SALES",
  {"owner": "TEST_USER"}
]

External tables created using sync of OCI Data Catalog or AWS Glue can also be used the object list. This helps in managing metadata in central Data Catalogs and use the metadata directly for translating natural language prompts using AI.

object_list_mode

Specifies whether to send metadata for the most relevant tables or all tables to the LLM.

Supported values are:

• automated: Sends metadata only for the specific tables identified as most relevant to the query.

• all: Sends metadata for all tables accessible to the user.

When object_list_mode is set to automated, Select AI automatically creates a vector index, named <profile_name>_OBJECT_LIST_VECINDEX with default attributes. See

oci_apiformat

Specifies the format in which the API expects data to be sent and received. Use this attribute to generate text responses. This attribute applies to OCI Generative AI Chat Models in a dedicated AI cluster. Specify this attribute when you specify a model OCID in the model attribute or provide an endpoint in the oci_endpoint_id attribute.

oci_compartment_id

Specifies the OCID of the compartment you are permitted to access when calling the OCI Generative AI service. The compartment ID can contain alphanumeric characters, hyphens and dots.

The default is the compartment ID of the PDB.

oci_endpoint_id

This attributes indicates the endpoint OCID of the Oracle dedicated AI hosting cluster. The endpoint ID can contain alphanumeric characters, hyphens and dots. To find the endpoint OCID, see Getting an Endpoint's Details in Generative AI.

When you want to use the Oracle dedicated AI cluster, you must provide the endpoint OCID of the hosting cluster.

By default, the endpoint ID is empty and the model is on-demand on a shared infrastructure.

oci_runtimetype

This attribute indicates the runtime type of the provided model. This attribute is applicable to OCI Generate Text models in a dedicated AI cluster. Specify this attribute when you specify a model OCID in the model attribute or provide an endpoint in the oci_endpoint_id attribute.

All permitted values can be found in OCI Generative AI runtimeType. See LlmInferenceRequest Reference.

provider

AI provider for the AI profile.

Supported providers:

• openai
• cohere
• azure
• database
• oci
• google
• anthropic
• huggingface
• aws

This is a mandatory attribute.

provider_endpoint

Specifies the API endpoint for OpenAI-compatible providers. This attribute is specific only to OpenAI-compatible providers. Specify provider_endpoint as an attribute in the DBMS_CLOUD_AI.CREATE_PROFILE procedure instead of the provider attribute. See Use OpenAI-Compatible Providers to learn how to obtain the parameter.

Example: api.fireworks.ai/inference

region

The default region for AWS is us-east-1.

The default region is us-chicago-1.

stop_tokens

The generated text will be terminated at the beginning of the earliest stop sequence. Sequence will be incorporated into the text. The attribute value must be a valid array of string values in JSON format. stop_tokens takes a JSON array as input. To learn more about stop tokens or stop sequences, see OpenAI or Cohere documentation.

temperature

Sampling from Generate Text models incorporates randomness, so that the same prompt may yield different outputs each time you hit "generate". Temperature is a non-negative float number used to tune the degree of randomness. Lower temperatures mean less random generations. See Temperature for more details. This parameter is applicable to all the supported service providers.

vector_index_name

Name of the vector index. The vector index name must follow the naming rules of Oracle SQL identifier. Maximum length of the vector store name is 125 characters.

source_language

target_language

The language into which the provider translates the text. Accepts either the full language name or the language code (language_code) supported by providers. The values are not case sensitive.

profile_name

Name of the AI profile

force

If TRUE, then the procedure ignores errors if AI profile does not exist.

The default value for this parameter is FALSE.

profile_name

Name for the AI profile to enable

This parameter is mandatory.

profile_name

Name for the AI profile.

This parameter is mandatory.

profile_name

Specifies the AI profile to use. If you do not provide a profile_name, Select AI uses the default profile set in the session.

This is a mandatory parameter.

sql_id

Identifies the SQL query. One sql_id can have only one feedback entry.

This is a mandatory parameter.

sql_text

Contains the full text of the SQL query.

This is a mandatory parameter.

feedback_type

This is a mandatory parameter when operation is add.

response

Represents the correct SQL query result the user expects.

This is a mandatory parameter when operation is add and feedback_type is negative.

feedback_content

Captures the user's natural language feedback. You have the option to use this parameter along with response.

operation

attributes

Includes JSON object attributes as per the FEEDBACK Procedure.

content

Contains the user prompt.

embedding

Contains vector representations (embeddings) of user prompt.

profile_name

Name of the AI profile for which you want to set the attributes.

This parameter is mandatory.

attribute_name

Name of the AI profile attribute

This parameter is mandatory.

attribute_value

Value of the profile attribute. Value can be BOOLEAN, CLOB, NUMBER or VARCHAR2 type.

The default value is NULL.

prompt

Natural language prompt to translate using AI.

The prompt can include SELECT AI <action> as the prefix. The action can also be supplied separately as an "action" parameter. The action supplied in the prompt overrides the action parameter. Default action is showsql.

This parameter is mandatory.

profile_name

Name of the AI profile. This parameter is optional if an AI profile is already set in the session using DBMS_CLOUD_AI.SET_PROFILE.

The default value is NULL.

EXEC DBMS_CLOUD_AI.set_profile('OPENAI');

-----------------------------------------------
SELECT DBMS_CLOUD_AI.GENERATE(prompt       => 'how many customers',
                              profile_name => 'OPENAI',
                              action       => 'runsql')
FROM dual;
-----------------------------------------------

SELECT DBMS_CLOUD_AI.GENERATE(prompt       => 'how many customers',
                              profile_name => 'OPENAI',
                              action       => 'showsql')
FROM dual;
-----------------------------------------------
SELECT DBMS_CLOUD_AI.GENERATE(prompt       => 'how many customers',
                              profile_name => 'OPENAI',
                              action       => 'explainsql')
FROM dual;
------------------------------------------------
SELECT DBMS_CLOUD_AI.GENERATE(prompt       => 'how many customers',
                              profile_name => 'OPENAI',
                              action       => 'narrate')
FROM dual;
-------------------------------------------
SELECT DBMS_CLOUD_AI.GENERATE(prompt       => 'what is oracle autonomous database',
                              profile_name => 'OPENAI',
                              action       => 'chat')
FROM dual;

Descriptions of actions are included in Use AI Keyword to Enter Prompts.

Specify conversation parameters. See CREATE_CONVERSATION Attributes. You can specify only the following parameters:

profile_name

A name for the AI profile in the current session.

This parameter is mandatory.

attributes

Attributes for conversation in JSON format. See CREATE_CONVERSATION Attributes for more details.

The default value is NULL.

attributes

Attributes for conversation in JSON format. See CREATE_CONVERSATION Attributes for more details.

The default value is NULL.

title

New Conversation

The user-assigned name for the conversation. If not provided, Select AI will have the LLM generate one when the conversation is first used with a prompt.

description

NULL

Provides a user-defined description summarizing the purpose or context of the conversation. If it's not provided, the LLM generates one when the conversation is first used with a prompt and update it again on the 5th use to include more accurate and relevant information.

retention_days

7

Specify the number of days to retain the conversation history. This is stored in the database from its creation date. If you omit the value, the systems sets it to default value of 7. If you set it to 0, the system retains the conversation until you manually delete it using the DBMS_CLOUD_AI.DROP_CONVERSATION procedure or DBMS_CLOUD.DELETE_ALL_OPERATIONS('CONVERSATION').

conversation_length

NULL

If none of them specify the conversation_length, then the default value is 10.

conversation_id

Unique number assigned to a conversation.

This is a mandatory parameter.

attributes

Attributes for conversation in JSON format. See CREATE_CONVERSATION Attributes for more details.

conversation_id

Unique number assigned to a conversation in the current session.

This parameter is mandatory.

conversation_prompt_id

Unique number assigned to a prompt in a conversation. You can find the prompt ID by querying DBA/USER_CLOUD_AI_CONVERSATION_PROMPTS view. See DBMS_CLOUD_AI Views.

This is a mandatory parameter.

force

If TRUE, then the procedure ignores errors if the conversation_prompt_id does not exist.

The default value for this parameter is FALSE.

conversation_id

Unique number assigned to a conversation.

This is a mandatory parameter.

force

If TRUE, then the procedure ignores errors if the conversation_id does not exist.

The default value for this parameter is FALSE.

content

Specifies the text you want to summarize. Either content or location_uri must be specified.

This is not a mandatory parameter.

credential_name

location_uri

Provides the URI where the text is stored or the path to a local file. Either content or location_uri must be specified.

For example:

Object storage: https://objectstorage.ca-toronto-1.oraclecloud.com/n/namespace-string/b/bucketname/o/data_folder/summary/test_file.txt

Local file: summary_gobject:test_file.txt

profile_name

Specifies the AI profile to use. If you do not provide a profile_name, Select AI uses the default profile set in the session. If no default profile is set, it returns the error: ORA-20046: AI profile is not enabled in the session.

The default value is NULL.

user_prompt

Supplies a natural language prompt to guide or customize the summary. You can include additional instructions beyond summary parameters.

For example, The summary should start with ''The summary of the article is: '''

This parameter is not mandatory.

Defines summarization parameters. See SUMMARIZE Parameters.

min_words

0

Specifies the approximate minimum number of words the generated summary is expected to contain.

max_words

200

summary_style

chunk_processing_method

extractiveness_level

• High: The summary stays close to the original phrasing, reusing sentences and expressions where possible.
• Medium: A balanced mix of extraction and paraphrasing.
• Low: Allows more freedom to reword, restructure, or simplify the input, focusing on meaning rather than exact phrasing.

profile_name

Specifies the AI profile to use.

This is not a mandatory parameter.

text

Specifies the text you want to translate.

This is a mandatory parameter.

source_language

Language of the input text

target_language

Language into which the text is translated.

profile_name

The AI profile containing necessary LLM service information. This can be created by CREATE_PROFILE Procedure.

object_name

• SELECT and INSERT privilege on the table objects are needed for the user using it.
• The table is either empty or have records in it.

Specify the database user who owns the referenced object. If no specific owner is provided, the procedure defaults to using the schema of the user running it.

The number of records to be synthetically generated.

user_prompt

the release date for the movies should be in 2019

params

Optional attributes provided in JSON object string format to modify the behavior of an API. See Optional Parameters.

object_list

sample_rows

Number

0 <= sample_rows <= 100

Specify the number of rows from the table to use as a sample to guide the LLM in data generation.

A value of 0 means no sample rows will be used. The default value is 0.

table_statistics

Boolean

Enable or disable the use of table statistics information.

The default value is False.

priority

String

Valid values:

Assign a priority value that defines the number of parallel requests sent to the LLM for generating synthetic data. Tasks with a higher priority will consume more database resources and complete faster.

The default value is HIGH

• HIGH: Specifies the number of parallel LLM requests based on the database's ECPU count (or OCPU count if your database uses OCPUs).

• MEDIUM: Sets the number of concurrent processes according to the concurrency limit for Medium service. The default value is 4.

• LOW: Runs the pipeline job in a serial order, without parallel processing.

The maximum number of concurrent parallel processes used for synthetic data generation is limited to 64.

comments

Enable or disable sending comments to the LLM to guide data generation.

The default value is False.

index_name

Name of the vector index. The vector index name must follow the naming rules of Oracle SQL identifier. Maximum length of vector store name is 125 characters.

This is a mandatory parameter.

attributes

Custom attributes for the vector index in JSON. To see a list of configurable parameters, see Vector Index Attributes.

The default value is NULL.

The default value is Disabled.

description

Description for the vector index.

The default value is NULL.

index_name

Name of the vector index. The vector index name must follow the naming rules of Oracle SQL identifier. Maximum length of vector store name is 125 characters.

This is a mandatory parameter.

include_data

Indicates whether to delete both the customer's vector store and vector index along with the vector index object.

Possible values:

• TRUE
• FALSE

The default value is TRUE.

Indicates whether to ignore errors that occur if the vector index does not exist.

Possible values:

• TRUE
• FALSE

If set to TRUE, this parameter bypasses any errors that occur if the vector index does not exist.

The default value is FALSE.

index_name

Name of the vector index. The vector index name must follow the naming rules of Oracle SQL identifier. Maximum length of vector store name is 125 characters.

This is a mandatory parameter.

index_name

Name of the vector index. The vector index name must follow the naming rules of Oracle SQL identifier. Maximum length of vector store name is 125 characters.

This is a mandatory parameter.

index_name

Name of the vector index. The vector index name must follow the naming rules of Oracle SQL identifier. Maximum length of vector store name is 125 characters.

This is a mandatory parameter.

attributes

Specifies vector index attributes in JSON format.

This is a mandatory parameter.

attribute_name

Name of the custom attributes specified as JSON parameters in CREATE_VECTOR_INDEX procedure.

You cannot modify the following attributes:

• location
• vector_table_name
• chunk_size
• chunk_overlap
• vector_distance_metric
• vector_dimension

This is a mandatory parameter.

User specified value for the custom attribute_name. Value can be CLOB, NUMBER or VARCHAR2 type.

The default value is NULL.