A summary is a short and concise extract with key features of a document that best represents what the document is about as a whole. A summary can be free-form paragraphs or bullet points based on the format that you specify.

Purpose

Syntax

DBMS_VECTOR_CHAIN.UTL_TO_SUMMARY (
    DATA          IN CLOB,
    PARAMS        IN JSON default NULL
) return CLOB;

DATA

This function accepts the input data type in plain text as CLOB.

It returns a summary of the input document also as CLOB.

PARAMS

Specify summary parameters in JSON format, depending on the service provider that you want to use for document summarization.

{
  "provider"     : "database",
  "glevel"       : "<summary format>",
  "numParagraphs": <number in the range 1-16>,
  "maxPercent"   : <number in the range 1-100>,
  "num_themes"   : <number in the range 1-50>,
  "language"     : "<name of the language>"
}

{
  "provider"          : "database",
  "glevel"            : "sentence",
  "numParagraphs"     : 1
}

If using a third-party provider:

{
  "provider"          : "<AI service provider>", 
  "credential_name"   : "<credential name>",
  "url"               : "<REST endpoint URL for summarization service>", 
  "model"             : "<REST provider summarization model name>",
  "transfer_timeout"  : <maximum wait time for the request to complete>,
  "max_count": "<maximum calls to the AI service provider>",
  "<additional REST provider parameter>": "<REST provider parameter value>"
}

Additional third-party provider parameters:

Optionally, specify additional provider-specific parameters.

Let us look at some example configurations for all third-party providers:

{
  "provider"          : "cohere",
  "credential_name"   : "COHERE_CRED",
  "url"               : "https://api.cohere.example.com/summarize",
  "model"             : "command",
  "length"            : "medium",
  "format"            : "paragraph",
  "temperature"       : 1.0
}

{
 "provider"           : "ocigenai",
 "credential_name"    : "OCI_CRED",
 "url"                : "https://generativeai.oci.example.com/summarizeText",
 "model"              : "cohere.command-r-16k",
 "length"             : "MEDIUM",
 "format"             : "PARAGRAPH"
}

{
  "provider"          : "googleai",
  "credential_name"   : "GOOGLEAI_CRED",
  "url"               : "https://googleapis.example.com/models/",
  "model"             : "gemini-pro:generateContent",
  "generation_config" : {
    "temperature"     : 0.9,
    "topP"            : 1,
    "candidateCount"  : 1,
    "maxOutputTokens" : 256
  }
}

{
  "provider"          : "huggingface",
  "credential_name"   : "HF_CRED",
  "url"               : "https://api.huggingface.example.co/models/",
  "model"             : "facebook/bart-large-cnn"
}

{
  "provider"          : "ollama", 
  "host"              : "local", 
  "url"               : "http://localhost:11434/api/generate", 
  "model"             : "phi3:mini"
}

{
  "provider"          : "openai",
  "credential_name"   : "OPENAI_CRED",
  "url"               : "https://api.openai.example.com",
  "model"             : "gpt-4o-mini",
  "max_tokens"        : 256,
  "temperature"       : 1.0
}

{
  "provider"          : "vertexai",
  "credential_name"   : "VERTEXAI_CRED",
  "url"               : "https://googleapis.example.com/models/",
  "model"             : "gemini-1.0-pro:generateContent",
  "generation_config" : {
    "temperature"     : 0.9,
    "topP"            : 1,
    "candidateCount"  : 1,
    "maxOutputTokens" : 256
  }
}

Examples

• Generate summary using Oracle Database:

  This statement specifies database as the provider. Here, the Oracle Text PL/SQL procedure CTX_DOC.GIST is internally called to generate a summary of an extract on "Transactions".

  -- select example
  
  set serveroutput on
  
  var params clob;
  begin
    :params := '
  {
    "provider": "database",
    "glevel": "sentence",
    "numParagraphs": 1
  }';
  end;
  /
  
  select dbms_vector_chain.utl_to_summary(
   'A transaction is a logical, atomic unit of work that contains one or more SQL statements.  An RDBMS must be able to group SQL statements so that they are either all committed, which means they are applied to the database, or all rolled back, which means they are undone.  An illustration of the need for transactions is a funds transfer from a savings account to a checking account. The transfer consists of the following separate operations:
      1. Decrease the savings account.
      2. Increase the checking account.
      3. Record the transaction in the transaction journal.
      Oracle Database guarantees that all three operations succeed or fail as a unit. For example, if a hardware failure prevents a statement in the transaction from executing, then the other statements must be rolled back.
      Transactions set Oracle Database apart from a file system. If you perform an atomic operation that updates several files, and if the system fails halfway through, then the files will not be consistent. In contrast, a transaction moves an Oracle database from one consistent state to another. The basic principle of a transaction is "all or nothing": an atomic operation succeeds or fails as a whole.',
   json(:params)) from dual;
  
  -- PL/SQL example
  
  declare
    input clob;
    params clob;
    output clob;
  begin
    input := 'A transaction is a logical, atomic unit of work that contains one or more SQL statements.  An RDBMS must be able to group SQL statements so that they are either all committed, which means they are applied to the database, or all rolled back, which means they are undone.  An illustration of the need for transactions is a funds transfer from a savings account to a checking account. The transfer consists of the following separate operations:
      1. Decrease the savings account.
      2. Increase the checking account.
      3. Record the transaction in the transaction journal.
      Oracle Database guarantees that all three operations succeed or fail as a unit. For example, if a hardware failure prevents a statement in the transaction from executing, then the other statements must be rolled back.
      Transactions set Oracle Database apart from a file system. If you perform an atomic operation that updates several files, and if the system fails halfway through, then the files will not be consistent. In contrast, a transaction moves an Oracle database from one consistent state to another. The basic principle of a transaction is "all or nothing": an atomic operation succeeds or fails as a whole.';
  
    params := '
    {
     "provider": "database",
     "glevel": "sentence",
     "numParagraphs": 1
    }';
  
    output := dbms_vector_chain.utl_to_summary(input, json(params));
    dbms_output.put_line(output);
    if output is not null then
      dbms_lob.freetemporary(output);
    end if;
  exception
    when OTHERS THEN
      DBMS_OUTPUT.PUT_LINE (SQLERRM);
      DBMS_OUTPUT.PUT_LINE (SQLCODE);
  end;
  /

• Generate summary using Generative AI:

  These statements generate a summary of an extract on "Transactions" by accessing Generative AI as the provider.

  Here, the cohere.command-r-16k model is used for the summarization operation. You can replace the model value with any other supported model that you want to use with Generative AI, as listed in Supported Third-Party Provider Operations and Endpoints.

  -- select example
  
  var params clob;
  begin
    :params := '
  {  
   "provider": "ocigenai", 
   "credential_name": "OCI_CRED", 
   "url": "https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/chat", 
   "model": "cohere.command-r-16k",
   "temperature": "0.0",
   "extractiveness": "LOW"
  }';
  end;
  /
  
  select dbms_vector_chain.utl_to_summary(
   'A transaction is a logical, atomic unit of work that contains one or more SQL statements.  An RDBMS must be able to group SQL statements so that they are either all committed, which means they are applied to the database, or all rolled back, which means they are undone.  An illustration of the need for transactions is a funds transfer from a savings account to a checking account. The transfer consists of the following separate operations:
      1. Decrease the savings account.
      2. Increase the checking account.
      3. Record the transaction in the transaction journal.
      Oracle Database guarantees that all three operations succeed or fail as a unit. For example, if a hardware failure prevents a statement in the transaction from executing, then the other statements must be rolled back.
      Transactions set Oracle Database apart from a file system. If you perform an atomic operation that updates several files, and if the system fails halfway through, then the files will not be consistent. In contrast, a transaction moves an Oracle database from one consistent state to another. The basic principle of a transaction is "all or nothing": an atomic operation succeeds or fails as a whole.',
   json(:params)) from dual;
  
  -- PL/SQL example
  
  declare
    input clob;
    params clob;
    output clob;
  begin
    input := 'A transaction is a logical, atomic unit of work that contains one or more SQL statements.  An RDBMS must be able to group SQL statements so that they are either all committed, which means they are applied to the database, or all rolled back, which means they are undone.  An illustration of the need for transactions is a funds transfer from a savings account to a checking account. The transfer consists of the following separate operations:
      1. Decrease the savings account.
      2. Increase the checking account.
      3. Record the transaction in the transaction journal.
      Oracle Database guarantees that all three operations succeed or fail as a unit. For example, if a hardware failure prevents a statement in the transaction from executing, then the other statements must be rolled back.
      Transactions set Oracle Database apart from a file system. If you perform an atomic operation that updates several files, and if the system fails halfway through, then the files will not be consistent. In contrast, a transaction moves an Oracle database from one consistent state to another. The basic principle of a transaction is "all or nothing": an atomic operation succeeds or fails as a whole.';
  
    params := '
    {
     "provider": "ocigenai",
     "credential_name": "OCI_CRED",
     "url": "https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/chat",
     "model": "cohere.command-r-16k",
     "length": "MEDIUM",
     "format": "PARAGRAPH",
     "temperature": 1.0
    }';
  
    output := dbms_vector_chain.utl_to_summary(input, json(params));
    dbms_output.put_line(output);
    if output is not null then
      dbms_lob.freetemporary(output);
    end if;
  exception
    when OTHERS THEN
      DBMS_OUTPUT.PUT_LINE (SQLERRM);
      DBMS_OUTPUT.PUT_LINE (SQLCODE);
  end;
  /

• End-to-end examples:

  To run end-to-end example scenarios using this function, see Generate Summary.