adm_ai_rag_api
This document contains the API documentation for the adm_ai_rag_api package.
r_embedding_config_type
Section titled “r_embedding_config_type”Type for embedding configuration
Definition:
type r_embedding_config_type is record ( dimensions number, provider varchar2(4000 char), model varchar2(4000 char), config json_object_t);Fields:
| Name | Type | Description |
|---|---|---|
dimensions | number | - |
provider | varchar2(4000 char) | - |
model | varchar2(4000 char) | - |
config | json_object_t | - |
r_llm_extraction_config_type
Section titled “r_llm_extraction_config_type”Type for the optional LLM (file-input) text-extraction configuration. is_configured is false when the collection has no llm_text_extraction section (built-in extraction is then used for every file). mime_types is always populated (defaults to application/pdf) and lowercased; annotation_* are null unless the apply_to filter restricts extraction to annotated documents.
Definition:
type r_llm_extraction_config_type is record ( is_configured boolean, provider varchar2(4000 char), model varchar2(4000 char), config json_object_t, prompt clob, mime_types apex_t_varchar2, annotation_key varchar2(255 char), annotation_value varchar2(4000 char));Fields:
| Name | Type | Description |
|---|---|---|
is_configured | boolean | - |
provider | varchar2(4000 char) | - |
model | varchar2(4000 char) | - |
config | json_object_t | - |
prompt | clob | - |
mime_types | apex_t_varchar2 | - |
annotation_key | varchar2(255 char) | - |
annotation_value | varchar2(4000 char) | - |
r_chunk_config_type
Section titled “r_chunk_config_type”Type for chunk configuration
Definition:
type r_chunk_config_type is record ( target_chunk_size number, overlap_size number, min_chunk_size number, max_chunk_size number);Fields:
| Name | Type | Description |
|---|---|---|
target_chunk_size | number | - |
overlap_size | number | - |
min_chunk_size | number | - |
max_chunk_size | number | - |
r_hybrid_config_type
Section titled “r_hybrid_config_type”Type for the optional hybrid-search configuration (vector + Oracle Text + RRF). is_enabled is false when the collection has no hybrid_search section (vector-only).
Definition:
type r_hybrid_config_type is record ( is_enabled boolean, rrf_k number, doc_candidates number, vector_weight number, keyword_weight number);Fields:
| Name | Type | Description |
|---|---|---|
is_enabled | boolean | - |
rrf_k | number | - |
doc_candidates | number | - |
vector_weight | number | - |
keyword_weight | number | - |
r_matched_chunk_type
Section titled “r_matched_chunk_type”Type for matched chunk result
Definition:
type r_matched_chunk_type is record ( rag_chunk_id number, chunk_index number, chunk_text clob, score number, document_id number, document_name varchar2(4000 char), version_id number, version_number number);Fields:
| Name | Type | Description |
|---|---|---|
rag_chunk_id | number | - |
chunk_index | number | - |
chunk_text | clob | - |
score | number | - |
document_id | number | - |
document_name | varchar2(4000 char) | - |
version_id | number | - |
version_number | number | - |
r_source_type
Section titled “r_source_type”Type for prepared source
Definition:
type r_source_type is record ( document_id number, document_name varchar2(4000 char), version_id number, version_number number, source_text clob, chunk_count number, avg_score number);Fields:
| Name | Type | Description |
|---|---|---|
document_id | number | - |
document_name | varchar2(4000 char) | - |
version_id | number | - |
version_number | number | - |
source_text | clob | - |
chunk_count | number | - |
avg_score | number | - |
Functions and Procedures
Section titled “Functions and Procedures”get_embedding_config
Section titled “get_embedding_config”Gets the embedding configuration for a RAG collection
Signature:
function get_embedding_config ( p_rag_collection_id in number) return r_embedding_config_type;Parameters:
| Name | Direction | Type | Description |
|---|---|---|---|
p_rag_collection_id | in | number | ID of the collection |
Returns: r_embedding_config_type - Embedding configuration record
get_chunk_config
Section titled “get_chunk_config”Gets the chunk configuration for a RAG collection
Signature:
function get_chunk_config ( p_rag_collection_id in number) return r_chunk_config_type;Parameters:
| Name | Direction | Type | Description |
|---|---|---|---|
p_rag_collection_id | in | number | ID of the collection |
Returns: r_chunk_config_type - Chunk configuration record
get_vector_store
Section titled “get_vector_store”Gets the configured vector backend for a RAG collection.
Signature:
function get_vector_store ( p_rag_collection_id in number) return varchar2;Parameters:
| Name | Direction | Type | Description |
|---|---|---|---|
p_rag_collection_id | in | number | ID of the collection |
Returns: varchar2 - ‘ORACLE’ (native Oracle vector search) or ‘QDRANT’ (external Qdrant; also the
default for legacy collections that predate the vector_store option)
get_llm_extraction_config
Section titled “get_llm_extraction_config”Gets the optional LLM text-extraction configuration for a RAG collection. Returns is_configured = false (built-in extraction) when the collection has no llm_text_extraction section.
Signature:
function get_llm_extraction_config ( p_rag_collection_id in number) return r_llm_extraction_config_type;Parameters:
| Name | Direction | Type | Description |
|---|---|---|---|
p_rag_collection_id | in | number | ID of the collection |
Returns: r_llm_extraction_config_type - LLM text-extraction configuration record
get_hybrid_config
Section titled “get_hybrid_config”Gets the optional hybrid-search configuration for a RAG collection. Returns is_enabled = false (vector-only) when the collection has no hybrid_search section; numeric fields fall back to defaults (rrf_k 60, doc_candidates 20, weights 1).
Signature:
function get_hybrid_config ( p_rag_collection_id in number) return r_hybrid_config_type;Parameters:
| Name | Direction | Type | Description |
|---|---|---|---|
p_rag_collection_id | in | number | ID of the collection |
Returns: r_hybrid_config_type - Hybrid-search configuration record
create_rag_collection
Section titled “create_rag_collection”Creates a new RAG collection with JSON configuration validation
Signature:
function create_rag_collection ( p_collection_name in varchar2, p_description in varchar2 default null, p_config_json in clob) return number;Parameters:
| Name | Direction | Type | Description |
|---|---|---|---|
p_collection_name | in | varchar2 | Name of the collection (must be lowercase) |
p_description | in | varchar2 default null | Description of the collection |
p_config_json | in | clob | JSON configuration containing required attributes |
Returns: number - The ID of the created RAG collection
update_rag_collection
Section titled “update_rag_collection”Updates an existing RAG collection
Signature:
procedure update_rag_collection ( p_rag_collection_id in number, p_collection_name in varchar2 default null, p_description in varchar2 default null, p_config_json in clob default null);Parameters:
| Name | Direction | Type | Description |
|---|---|---|---|
p_rag_collection_id | in | number | ID of the collection to update |
p_collection_name | in | varchar2 default null | Optional new name for the collection |
p_description | in | varchar2 default null | Optional new description |
p_config_json | in | clob default null | Optional new JSON configuration |
delete_rag_collection
Section titled “delete_rag_collection”Deletes a RAG collection by ID
Signature:
procedure delete_rag_collection ( p_rag_collection_id in number);Parameters:
| Name | Direction | Type | Description |
|---|---|---|---|
p_rag_collection_id | in | number | ID of the collection to delete |
delete_rag_collection
Section titled “delete_rag_collection”Deletes a RAG collection by name
Signature:
procedure delete_rag_collection ( p_collection_name in varchar2);Parameters:
| Name | Direction | Type | Description |
|---|---|---|---|
p_collection_name | in | varchar2 | Name of the collection to delete |
search_chunks
Section titled “search_chunks”Searches for matching chunks in a RAG collection
Signature:
function search_chunks ( p_rag_collection_id in number, p_query in varchar2, p_limit in number default null, p_score_threshold in number default null, p_rewrite_query in boolean default null, p_rewrite_provider in varchar2 default null, p_rewrite_model in varchar2 default null, p_rewrite_config in json_object_t default null, p_document_id in number default null) return t_matched_chunks_type pipelined;Parameters:
| Name | Direction | Type | Description |
|---|---|---|---|
p_rag_collection_id | in | number | ID of the collection to search |
p_query | in | varchar2 | The search query |
p_limit | in | number default null | Maximum number of chunks to return; null uses the collection’s default_limit |
p_score_threshold | in | number default null | Minimum similarity score (0-1); null uses the collection’s default_score_threshold |
p_rewrite_query | in | boolean default null | Whether to rewrite query using LLM |
p_rewrite_provider | in | varchar2 default null | Override provider for query rewriting |
p_rewrite_model | in | varchar2 default null | Override model for query rewriting |
p_rewrite_config | in | json_object_t default null | Override UC AI config (merged over the collection’s |
query_rewriting.config; override keys win) for query rewriting || p_document_id | in | number default null | Restrict the search to this document’s chunks; null (the default)
searches the whole collection. Needs the native Oracle vector store: Qdrant points
carry no payload to filter on, so a QDRANT collection raises
adm_ai_error.e_no_doc_scoped_search rather than quietly searching everything. A
document that is in the collection but has no active file yields no rows. |
Returns: t_matched_chunks_type pipelined - Collection of matched chunks
prepare_sources
Section titled “prepare_sources”Prepares sources from matched chunks, grouping by document. Documents are ranked by their best chunk score, so p_max_sources returns the most relevant documents. Each matched chunk is expanded by p_surrounding_chunks neighboring chunks on each side; overlapping character ranges are merged so the source text contains no duplicated passages, and non-contiguous regions are separated by a ’[…]’ marker.
Signature:
function prepare_sources ( p_rag_collection_id in number, p_query in varchar2, p_limit in number default null, p_score_threshold in number default null, p_max_sources in number default null, p_surrounding_chunks in number default null, p_rewrite_query in boolean default null, p_rewrite_provider in varchar2 default null, p_rewrite_model in varchar2 default null, p_rewrite_config in json_object_t default null, p_document_id in number default null) return t_sources_type pipelined;Parameters:
| Name | Direction | Type | Description |
|---|---|---|---|
p_rag_collection_id | in | number | ID of the collection |
p_query | in | varchar2 | The search query |
p_limit | in | number default null | Maximum number of chunks to retrieve; null uses the collection’s default_limit |
p_score_threshold | in | number default null | Minimum similarity score (0-1); null uses the collection’s default_score_threshold |
p_max_sources | in | number default null | Maximum number of source documents to return; null uses the collection’s default_max_sources |
p_surrounding_chunks | in | number default null | Number of neighboring chunks to include around each matched |
chunk (0 = matched chunks only); null uses the collection's default_surrounding_chunks || p_rewrite_query | in | boolean default null | Whether to rewrite query using LLM |
| p_rewrite_provider | in | varchar2 default null | Override provider for query rewriting |
| p_rewrite_model | in | varchar2 default null | Override model for query rewriting |
| p_rewrite_config | in | json_object_t default null | Override UC AI config (merged over the collection’s
query_rewriting.config; override keys win) for query rewriting |
| p_document_id | in | number default null | Restrict the search to this document’s chunks; null (the default)
searches the whole collection. See search_chunks for the vector-store requirement.
With a document bound, p_max_sources is naturally 1. |
Returns: t_sources_type pipelined - Collection of prepared sources
generate_answer
Section titled “generate_answer”Generates an AI answer based on RAG sources
Signature:
function generate_answer ( p_rag_collection_id in number, p_query in varchar2, p_limit in number default null, p_score_threshold in number default null, p_max_sources in number default null, p_surrounding_chunks in number default null, p_system_prompt in clob default null, p_rewrite_query in boolean default null, p_rewrite_provider in varchar2 default null, p_rewrite_model in varchar2 default null, p_rewrite_config in json_object_t default null, p_answer_provider in varchar2 default null, p_answer_model in varchar2 default null, p_answer_config in json_object_t default null) return clob;Parameters:
| Name | Direction | Type | Description |
|---|---|---|---|
p_rag_collection_id | in | number | ID of the collection |
p_query | in | varchar2 | The user’s question |
p_limit | in | number default null | Maximum number of chunks to retrieve; null uses the collection’s default_limit |
p_score_threshold | in | number default null | Minimum similarity score (0-1); null uses the collection’s default_score_threshold |
p_max_sources | in | number default null | Maximum number of source documents; null uses the collection’s default_max_sources |
p_surrounding_chunks | in | number default null | Number of neighboring chunks to include around each matched |
chunk; null uses the collection's default_surrounding_chunks || p_system_prompt | in | clob default null | Custom system prompt for answer generation; null uses the
collection’s answer_model.system_prompt, falling back to a built-in prompt |
| p_rewrite_query | in | boolean default null | Whether to rewrite query using LLM |
| p_rewrite_provider | in | varchar2 default null | Override provider for query rewriting |
| p_rewrite_model | in | varchar2 default null | Override model for query rewriting |
| p_rewrite_config | in | json_object_t default null | Override UC AI config (merged over the collection’s
query_rewriting.config; override keys win) for query rewriting |
| p_answer_provider | in | varchar2 default null | Override provider for answer generation |
| p_answer_model | in | varchar2 default null | Override model for answer generation |
| p_answer_config | in | json_object_t default null | Override UC AI config (merged over the collection’s
answer_model.config; override keys win) for answer generation |
Returns: clob - Generated answer with sources
generate_answer_debug
Section titled “generate_answer_debug”Generates an AI answer based on RAG sources with debug logging
Signature:
procedure generate_answer_debug ( p_rag_collection_id in number, p_query in varchar2, p_limit in number default null, p_score_threshold in number default null, p_max_sources in number default null, p_surrounding_chunks in number default null, p_system_prompt in clob default null, p_rewrite_query in boolean default null, p_rewrite_provider in varchar2 default null, p_rewrite_model in varchar2 default null, p_rewrite_config in json_object_t default null, p_answer_provider in varchar2 default null, p_answer_model in varchar2 default null, p_answer_config in json_object_t default null, po_answer out nocopy clob, po_debug_log_id out nocopy number);Parameters:
| Name | Direction | Type | Description |
|---|---|---|---|
p_rag_collection_id | in | number | ID of the collection |
p_query | in | varchar2 | The user’s question |
p_limit | in | number default null | Maximum number of chunks to retrieve; null uses the collection’s default_limit |
p_score_threshold | in | number default null | Minimum similarity score (0-1); null uses the collection’s default_score_threshold |
p_max_sources | in | number default null | Maximum number of source documents; null uses the collection’s default_max_sources |
p_surrounding_chunks | in | number default null | Number of neighboring chunks to include around each matched |
chunk; null uses the collection's default_surrounding_chunks || p_system_prompt | in | clob default null | Custom system prompt for answer generation; null uses the
collection’s answer_model.system_prompt, falling back to a built-in prompt |
| p_rewrite_query | in | boolean default null | Whether to rewrite query using LLM |
| p_rewrite_provider | in | varchar2 default null | Override provider for query rewriting |
| p_rewrite_model | in | varchar2 default null | Override model for query rewriting |
| p_rewrite_config | in | json_object_t default null | Override UC AI config (merged over the collection’s
query_rewriting.config; override keys win) for query rewriting |
| p_answer_provider | in | varchar2 default null | Override provider for answer generation |
| p_answer_model | in | varchar2 default null | Override model for answer generation |
| p_answer_config | in | json_object_t default null | Override UC AI config (merged over the collection’s
answer_model.config; override keys win) for answer generation |
| po_answer | out | nocopy clob | OUT: Generated answer with sources |
| po_debug_log_id | out | nocopy number | OUT: ID of the debug log entry |
get_debug_log_markdown
Section titled “get_debug_log_markdown”Formats a debug log entry as Markdown
Signature:
function get_debug_log_markdown ( p_debug_log_id in number) return clob;Parameters:
| Name | Direction | Type | Description |
|---|---|---|---|
p_debug_log_id | in | number | ID of the debug log entry |
Returns: clob - Markdown formatted debug information