10
CTX_THES Package

This chapter provides reference information for using the CTX_THES package to manage and browse thesauri.

Knowing how information is stored in your thesaurus helps in writing queries with thesaurus operators. You can also use a thesaurus to extend the knowledge base, which is used for ABOUT queries in English and for generating document themes.

CTX_THES contains the following stored procedures and functions:

Name	Description
BT	Returns all broader terms of a phrase.
BTG	Returns all broader terms generic of a phrase.
BTI	Returns all broader terms instance of a phrase.
BTP	Returns all broader terms partitive of a phrase.
CREATE_PHRASE	Adds a phrase to the specified thesaurus or creates a relationship between two existing phrases.
CREATE_THESAURUS	Creates the specified thesaurus and returns the ID for the thesaurus.
DROP_THESAURUS	Drops the specified thesaurus from the thesaurus tables.
NT	Returns all narrower terms of a phrase.
NTG	Returns all narrower terms generic of a phrase.
NTI	Returns all narrower terms instance of a phrase.
NTP	Returns all narrower terms partitive of a phrase.
OUTPUT_STYLE	Sets the output style for the expansion functions.
TT	Returns the preferred term of a phrase.
RT	Returns the related terms of a phrase
SYN	Returns the synonym terms of a phrase
TR	Returns the foreign equivalent of a phrase.
TRSYN	Returns the foreign equivalent of a phrase, synonyms of the phrase, and foreign equivalent of the synonyms.
TT	Returns the top term of a phrase.

---

BT

This function returns all broader terms of a phrase as recorded in the specified thesaurus.

Syntax

CTX_THES.BT(phrase IN VARCHAR2, 
            lvl    IN NUMBER DEFAULT 1,
            tname  IN VARCHAR2 DEFAULT 'DEFAULT') 
RETURN VARCHAR2;

phrase

Specify phrase to lookup in thesaurus.

lvl

Specify how many levels of broader terms to return. For example 2 means get the broader terms of the broader terms of the phrase.

tname

Specify thesaurus name. If not specified, system default thesaurus is used.

Returns

This function returns a string of broader terms in the form:

 {bt1}|{bt2}|{bt3} ...

Example

Consider a thesaurus named MY_THES that has an entry for cat as follows:

cat 
   BT1 feline 
     BT2 mammal 
       BT3 vertebrate 
         BT4 animal

To look up the broader terms for cat up to two levels, issue the following statements:

declare 
  terms varchar2(2000); 
begin 
  terms := ctx_thes.bt('CAT', 2, 'MY_THES'); 
  dbms_output.put_line('The broader expansion for CAT is: '||terms); 
end; 

This code produces the following output:

The broader expansion for CAT is: {cat}|{feline}|{mammal}

Related Topics

OUTPUT_STYLE

Broader Term (BT, BTG, BTP, BTI) Operators in Chapter 4

---

BTG

This function returns all broader terms generic of a phrase as recorded in the specified thesaurus.

Syntax

CTX_THES.BTG(phrase IN VARCHAR2, 
             lvl    IN NUMBER DEFAULT 1,
             tname  IN VARCHAR2 DEFAULT 'DEFAULT') 
RETURN VARCHAR2;

phrase

Specify phrase to lookup in thesaurus.

lvl

Specify how many levels of broader terms to return. For example 2 means get the broader terms of the broader terms of the phrase.

tname

Specify thesaurus name. If not specified, system default thesaurus is used.

Returns

This function returns a string of broader terms generic in the form:

 {bt1}|{bt2}|{bt3} ...

Example

To look up the broader terms generic for cat up to two levels, issue the following statements:

declare 
  terms varchar2(2000); 
begin 
  terms := ctx_thes.btg('CAT', 2, 'MY_THES'); 
  dbms_output.put_line('the broader expansion for CAT is: '||terms); 
end; 

Related Topics

OUTPUT_STYLE

Broader Term (BT, BTG, BTP, BTI) Operators in Chapter 4

---

BTI

This function returns all broader terms instance of a phrase as recorded in the specified thesaurus.

Syntax

CTX_THES.BTI(phrase IN VARCHAR2, 
             lvl    IN NUMBER DEFAULT 1,
             tname  IN VARCHAR2 DEFAULT 'DEFAULT') 
RETURN VARCHAR2;

phrase

Specify phrase to lookup in thesaurus.

lvl

Specify how many levels of broader terms to return. For example 2 means get the broader terms of the broader terms of the phrase.

tname

Specify thesaurus name. If not specified, system default thesaurus is used.

Returns

This function returns a string of broader terms instance in the form:

 {bt1}|{bt2}|{bt3} ...

Example

To look up the broader terms instance for cat up to two levels, issue the following statements:

declare 
  terms varchar2(2000); 
begin 
  terms := ctx_thes.bti('CAT', 2, 'MY_THES'); 
  dbms_output.put_line('the broader expansion for CAT is: '||terms); 
end; 

Related Topics

OUTPUT_STYLE

Broader Term (BT, BTG, BTP, BTI) Operators in Chapter 4

---

BTP

This function returns all broader terms partitive of a phrase as recorded in the specified thesaurus.

Syntax

CTX_THES.BTP(phrase IN VARCHAR2, 
             lvl    IN NUMBER DEFAULT 1,
             tname  IN VARCHAR2 DEFAULT 'DEFAULT') 
RETURN VARCHAR2;

phrase

Specify phrase to lookup in thesaurus.

lvl

Specify how many levels of broader terms to return. For example 2 means get the broader terms of the broader terms of the phrase.

tname

Specify thesaurus name. If not specified, the system default thesaurus is used.

Returns

This function returns a string of broader terms in the form:

 {bt1}|{bt2}|{bt3} ...

Example

To look up the 2 broader terms partitive for cat, issue the following statements:

declare 
  terms varchar2(2000); 
begin 
  terms := ctx_thes.btp('CAT', 2, 'MY_THES'); 
  dbms_output.put_line('the broader expansion for CAT is: '||terms); 
end; 

Related Topics

OUTPUT_STYLE

Broader Term (BT, BTG, BTP, BTI) Operators in Chapter 4

---

CREATE_PHRASE

The CREATE_PHRASE procedure adds a new phrase to the specified thesaurus or creates a relationship between two existing phrases.

Syntax

CTX_THES.CREATE_PHRASE(tname   IN VARCHAR2,
                       phrase  IN VARCHAR2,
                       rel     IN VARCHAR2 DEFAULT NULL,
                       relname IN VARCHAR2 DEFAULT NULL);

tname

Specify the name of the thesaurus in which the new phrase is added or the existing phrase is located.

phrase

Specify the phrase to be added to a thesaurus or the phrase for which a new relationship is created.

rel

Specify the new relationship between phrase and relname:

• SYN (i.e. phrase is synonymous term for relname)

• PT | USE | SEE (i.e. phrase is preferred synonymous term for relname)

• BT (i.e. phrase is broader term for relname)

• NT (i.e. phrase is narrower term for relname)

• BTG (broader generic term)

• NTG (narrower generic term)

• BTP (broader partitive term)

• NTP (narrower partitive term)

• BTI (broader instance term)

• NTI (narrower instance term)

• RT (related term)

  See Also: For more information about thesaurus operators, see Chapter 4, "Query Operators".

relname

Specify the existing phrase that is related to phrase.

Returns

The ID for the entry.

Examples

Example 1: Creating Entries for Phrases

In this example, two new phrases (os and operating system) are created in a thesaurus named tech_thes.

begin
   ctx_thes.create_phrase('tech_thes','os');
   ctx_thes.create_phrase('tech_thes','operating system');
end;

Example 2: Creating a Relationship

In this example, the two phrases (os and operating system) in tech_thes are recorded as synonyms (syn).

begin
   ctx_thes.create_phrase('tech_thes','os','syn','operating system');
end;

This example assumes operating system already exists as a phrase in the thesaurus.

Notes

CREATE_PHRASE cannot be used to update the relationship between two existing phrases. It can only be used to create a new relationship between two existing phrases.

---

CREATE_THESAURUS

The CREATE_THESAURUS function creates an empty thesaurus with the specified name in the thesaurus tables.

Syntax

CTX_THES.CREATE_THESAURUS(thes_name      IN VARCHAR2,
                          casesens       IN BOOLEAN DEFAULT FALSE)
RETURN NUMBER;

thes_name

Specify the name of the thesaurus to be created.

casesens

Specify whether the thesaurus to be created is case-sensitive. If casesens is TRUE, Oracle retains the cases of all terms entered in the specified thesaurus. As a result, queries that use the thesaurus are case-sensitive.

Returns

The ID for the thesaurus.

Examples

declare thesid number;
begin
   thesid := ctx_thes.create_phrase('tech_thes');
end;

Notes

The name of the thesaurus must be unique. If a thesaurus with the specified name already exists, CREATE_THESAURUS returns an error and does not create the thesaurus.

To enter phrases in the thesaurus, use CTX_THES.CREATE_PHRASE or use the Thesaurus Maintenance screen in the System Administration tool.

---

DROP_THESAURUS

The DROP_THESAURUS procedure deletes the specified thesaurus and all of its entries from the thesaurus tables.

Syntax

CTX_THES.DROP_THESAURUS(name IN VARCHAR2);

name

Specify the name of the thesaurus to be dropped.

Examples

begin
ctx_thes.drop_thesaurus('tech_thes');
end;

---

NT

This function returns all narrower terms of a phrase as recorded in the specified thesaurus.

Syntax

CTX_THES.NT(phrase IN VARCHAR2, 
             lvl    IN NUMBER DEFAULT 1,
             tname  IN VARCHAR2 DEFAULT 'DEFAULT') 
RETURN VARCHAR2;

phrase

Specify phrase to lookup in thesaurus.

lvl

Specify how many levels of narrower terms to return. For example 2 means get the narrower terms of the narrower terms of the phrase.

tname

Specify thesaurus name. If not specified, system default thesaurus is used.

Returns

This function returns a string of narrower terms in the form:

 {nt1}|{nt2}|{nt3} ...

Example

Consider a thesaurus named MY_THES that has an entry for cat as follows:

cat
 NT domestic cat
 NT wild cat
 BT mammal
mammal
 BT animal
domestic cat
 NT Persian cat
 NT Siamese cat

To look up the narrower terms for cat down to two levels, issue the following statements:

declare 
  terms varchar2(2000); 
begin 
  terms := ctx_thes.nt('CAT', 2, 'MY_THES'); 
  dbms_output.put_line('the narrower expansion for CAT is: '||terms); 
end; 

This code produces the following output:

the narrower expansion for CAT is: {cat}|{domestic cat}|{wild cat}|{Persian 
cat}|{Siamese cat}

Related Topics

OUTPUT_STYLE

Narrower Term (NT, NTG, NTP, NTI) Operators in Chapter 4

---

NTG

This function returns all narrower terms generic of a phrase as recorded in the specified thesaurus.

Syntax

CTX_THES.NTG(phrase IN VARCHAR2, 
             lvl    IN NUMBER DEFAULT 1,
             tname  IN VARCHAR2 DEFAULT 'DEFAULT') 
RETURN VARCHAR2;

phrase

Specify phrase to lookup in thesaurus.

lvl

Specify how many levels of narrower terms to return. For example 2 means get the narrower terms of the narrower terms of the phrase.

tname

Specify thesaurus name. If not specified, system default thesaurus is used.

Returns

This function returns a string of narrower terms generic in the form:

 {nt1}|{nt2}|{nt3} ...

Example

To look up the narrower terms generic for cat down to two levels, issue the following statements:

declare 
  terms varchar2(2000); 
begin 
  terms := ctx_thes.ntg('CAT', 2, 'MY_THES'); 
  dbms_output.put_line('the narrower expansion for CAT is: '||terms); 
end; 

Related Topics

OUTPUT_STYLE

Narrower Term (NT, NTG, NTP, NTI) Operators in Chapter 4

---

NTI

This function returns all narrower terms instance of a phrase as recorded in the specified thesaurus.

Syntax

CTX_THES.NTI(phrase IN VARCHAR2, 
             lvl    IN NUMBER DEFAULT 1,
             tname  IN VARCHAR2 DEFAULT 'DEFAULT') 
RETURN VARCHAR2;

phrase

Specify phrase to lookup in thesaurus.

lvl

Specify how many levels of narrower terms to return. For example 2 means get the narrower terms of the narrower terms of the phrase.

tname

Specify thesaurus name. If not specified, system default thesaurus is used.

Returns

This function returns a string of narrower terms instance in the form:

 {nt1}|{nt2}|{nt3} ...

Example

To look up the narrower terms instance for cat down to two levels, issue the following statements:

declare 
  terms varchar2(2000); 
begin 
  terms := ctx_thes.nti('CAT', 2, 'MY_THES'); 
  dbms_output.put_line('the narrower expansion for CAT is: '||terms); 
end; 

Related Topics

OUTPUT_STYLE

Narrower Term (NT, NTG, NTP, NTI) Operators in Chapter 4

---

NTP

This function returns all narrower terms partitive of a phrase as recorded in the specified thesaurus.

Syntax

CTX_THES.NTP(phrase IN VARCHAR2, 
             lvl    IN NUMBER DEFAULT 1,
             tname  IN VARCHAR2 DEFAULT 'DEFAULT') 
RETURN VARCHAR2;

phrase

Specify phrase to lookup in thesaurus.

lvl

Specify how many levels of narrower terms to return. For example 2 means get the narrower terms of the narrower terms of the phrase.

tname

Specify thesaurus name. If not specified, system default thesaurus is used.

Returns

This function returns a string of narrower terms partitive in the form:

 {nt1}|{nt2}|{nt3} ...

Example

To look up the narrower terms partitive for cat down to two levels, issue the following statements:

declare 
  terms varchar2(2000); 
begin 
  terms := ctx_thes.ntp('CAT', 2, 'MY_THES'); 
  dbms_output.put_line('the narrower expansion for CAT is: '||terms); 
end; 

Related Topics

OUTPUT_STYLE

Narrower Term (NT, NTG, NTP, NTI) Operators in Chapter 4

---

OUTPUT_STYLE

Sets the output style for the return string of the CTX_THES expansion functions.

Syntax

CTX_THES.OUTPUT_STYLE (
      showlevel     IN BOOLEAN DEFAULT FALSE,
      showqualify   IN BOOLEAN DEFAULT FALSE,
      showpt        IN BOOLEAN DEFAULT FALSE,
      showid        IN BOOLEAN DEFAULT FALSE
);

showlevel

Specify TRUE to show level in BT/NT expansions.

showqualify

Specify TRUE to show phrase qualifiers.

showpt

Specify TRUE to show preferred terms with an asterisk *.

showid

Specify TRUE to show phrase ids.

Notes

The general syntax of the return string for CTX_THES expansion functions is:

{pt indicator:phrase (qualifier):level:phraseid}

Preferred term indicator is an asterisk then a colon at the start of the phrase. The qualifier is in parentheses after a space at the end of the phrase. Level is a number.

The following is an example return string for turkey the bird:

*:TURKEY (BIRD):1:1234 
 

---

PT

This function returns the preferred term of a phrase as recorded in the specified thesaurus.

Syntax

CTX_THES.PT(phrase IN VARCHAR2,
            tname  IN VARCHAR2 DEFAULT 'DEFAULT')
RETURN varchar2;

phrase

Specify phrase to lookup in thesaurus.

tname

Specify thesaurus name. If not specified, system default thesaurus is used.

Returns

This function returns the preferred term as a string in the form:

{pt}

Example

Consider a thesaurus MY_THES with the following preferred term definition for automobile:

AUTOMOBILE 
  PT CAR 

To look up the preferred term for automobile, execute the following code:

 declare 
  terms varchar2(2000); 
begin 
  terms := ctx_thes.pt('AUTOMOBILE','MY_THES'); 
  dbms_output.put_line('The prefered term for automobile is: '||terms); 
end; 

Related Topics

OUTPUT_STYLE

Preferred Term (PT) Operator in Chapter 4

---

RT

This function returns the related terms of a term in the specified thesaurus.

Syntax

CTX_THES.RT(phrase IN VARCHAR2,
            tname  IN VARCHAR2 DEFAULT 'DEFAULT')
RETURN varchar2;

phrase

Specify phrase to lookup in thesaurus.

tname

Specify thesaurus name. If not specified, system default thesaurus is used.

Returns

This function returns a string of related terms in the form:

{rt1}|{rt2}|{rt3}| ...

Example

Consider a thesaurus MY_THES with the following related term definition for dog:

DOG 
  RT WOLF 
  RT HYENA 

To look up the related terms for dog, execute the following code:

 declare 
  terms varchar2(2000); 
begin 
  terms := ctx_thes.rt('DOG','MY_THES'); 
  dbms_output.put_line('The related terms for dog are: '||terms); 
end; 

This codes produces the following output:

The related terms for dog are: {dog}|{wolf}|{hyena}

Related Topics

OUTPUT_STYLE

Related Term (RT) Operator in Chapter 4

---

SYN

This function returns all synonyms of a phrase as recorded in the specified thesaurus.

Syntax

CTX_THES.SYN(phrase IN VARCHAR2, 
             tname  IN VARCHAR2 DEFAULT 'DEFAULT') 
RETURN VARCHAR2;

phrase

Specify phrase to lookup in thesaurus.

tname

Specify thesaurus name. If not specified, system default thesaurus is used.

Returns

This function returns a string of the form:

 {syn1}|{syn2}|{syn3} ...

Example

Consider a thesaurus named ANIMALS that has an entry for cat as follows:

CAT 
  SYN KITTY 
  SYN FELINE 
 

To look-up the synonym for cat, issue the following statements:

declare 
  synonyms varchar2(2000); 
begin 
  synonyms := ctx_thes.syn('CAT','ANIMALS'); 
  dbms_output.put_line('the synonym expansion for CAT is: '||synonyms); 
end; 

This code produces the following output:

the synonym expansion for CAT is: {cat}|{kitty}|{feline}

Related Topics

OUTPUT_STYLE

SYNonym (SYN) Operator in Chapter 4

---

TR

This function returns the foreign equivalent of a phrase as recorded in the specified thesaurus.

Syntax

CTX_THES.TR(phrase IN VARCHAR2, 
            lang   IN VARCHAR2 DEFAULT NULL,
            tname  IN VARCHAR2 DEFAULT 'DEFAULT') 
RETURN VARCHAR2;

phrase

Specify phrase to lookup in thesaurus.

lang

Specify the foreign language. Specify 'ALL' for all translations of phrase.

tname

Specify thesaurus name. If not specified, system default thesaurus is used.

Returns

This function returns a string of foreign terms in the form:

 {ft1}|{ft2}|{ft3} ...

Example

Consider a thesaurus MY_THES with the following entries for cat:

cat 
  SPANISH: gato 
  FRENCH:  chat 
  SYN lion 
    SPANISH: leon 

To look up the translation for cat, you can issue the following statements:

declare 
  trans      varchar2(2000);
  span_trans varchar2(2000); 
begin 
  trans := ctx_thes.tr('CAT','ALL','MY_THES'); 
  span_trans := ctx_thes.tr('CAT','SPANISH','MY_THES') 
  dbms_output.put_line('the translations for CAT are: '||trans); 
  dbms_output.put_line('the Spanish translations for CAT are: '||span_trans); 
end; 
 

This codes produces the following output:

the translations for CAT are: {CAT}|{CHAT}|{GATO} 
the Spanish translations for CAT are: {CAT}|{GATO} 

Related Topics

OUTPUT_STYLE

Translation Term (TR) Operator in Chapter 4

---

TRSYN

This function returns the foreign equivalent of a phrase, synonyms of the phrase, and foreign equivalent of the synonyms as recorded in the specified thesaurus.

Syntax

CTX_THES.TRSYN(phrase IN VARCHAR2, 
            lang   IN VARCHAR2 DEFAULT NULL,
            tname  IN VARCHAR2 DEFAULT 'DEFAULT') 
RETURN VARCHAR2;

phrase

Specify phrase to lookup in thesaurus.

lang

Specify the foreign language. Specify 'ALL' for all translations of phrase.

tname

Specify thesaurus name. If not specified, system default thesaurus is used.

Returns

This function returns a string of foreign terms in the form:

 {ft1}|{ft2}|{ft3} ...

Example

Consider a thesaurus MY_THES with the following entries for cat:

cat 
  SPANISH: gato 
  FRENCH:  chat 
  SYN lion 
    SPANISH: leon 

To look up the translation and synonyms for cat, you can issue the following statements:

declare 
  synonyms   varchar2(2000);
  span_syn   varchar2(2000); 
begin 
  synonyms := ctx_thes.trsyn('CAT','ALL','MY_THES'); 
  span_syn := ctx_thes.trsyn('CAT','SPANISH','MY_THES') 
  dbms_output.put_line('all synonyms for CAT are: '||synonyms); 
  dbms_output.put_line('the Spanish synonyms for CAT are: '||span_syn); 
end; 
 

This codes produces the following output:

all synonyms for CAT are: {CAT}|{CHAT}|{GATO}|{LION}|{LEON} 
the Spanish synonyms for CAT are: {CAT}|{GATO}|{LION}|{LEON} 

Related Topics

OUTPUT_STYLE

Translation Term Synonym (TRSYN) Operator in Chapter 4

---

TT

This function returns the top term of a phrase as recorded in the specified thesaurus.

Syntax

CTX_THES.TT(phrase IN VARCHAR2,
            tname  IN VARCHAR2 DEFAULT 'DEFAULT')
RETURN varchar2;

phrase

Specify phrase to lookup in thesaurus.

tname

Specify thesaurus name. If not specified, system default thesaurus is used.

Returns

This function returns the top term string in the form:

{tt}

Example

Consider a thesaurus MY_THES with the following broader term entries for dog:

dog 
   BT1 canine 
     BT2 mammal 
       BT3 vertebrate 
         BT4 animal

To look up the top term for dog, execute the following code:

 declare 
  terms varchar2(2000); 
begin 
  terms := ctx_thes.rt('DOG','MY_THES'); 
  dbms_output.put_line('The top term for dog is: '||terms); 
end; 

This codes produces the following output:

The top term for dog is: {animal}

Related Topics

OUTPUT_STYLE

Top Term (TT) Operator in Chapter 4

---