MARKUP

The CTX_DOC.MARKUP procedure takes a query specification and a document textkey and returns a version of the document in which the query terms are marked up. These marked-up terms are either the words that satisfy a word query or the themes that satisfy an ABOUT query.

You can set the marked-up output to be either plaintext or HTML. The marked-up document returned by CTX_DOC.MARKUP does not include any graphics found in the original document.

You can use one of the predefined tag sets for marking highlighted terms, including a tag sequence that enables HTML navigation.

You usually call CTX_DOC.MARKUP after a query, from which you identify the document to be processed.

You can store the marked-up document either in memory or in a result table.

Note that for queries that have predicates used mainly for filtering documents at query time, the predicates are ignored during MARKUP. The following predicates are treated as filter predicates for this purpose: SDATA, HASPATH, and WITHIN/INPATH searching inside XML attributes.

See CTX_DOC.POLICY_MARKUP for a version of this procedure that does not require an index.

The performance of the procedures SNIPPET, HIGHLIGHT, and MARKUP can be improved by using the forward index feature of Oracle Text.

See Also: Oracle Text Application Developer’s Guide for more information about forward index

Note: Oracle Text does not guarantee well-formed output from CTX.DOC.MARKUP, especially for terms that are already marked up with HTML or XML. In particular, unexpected nesting of markup tags may occasionally result.

Syntax 1: In-Memory Result Storage

exec CTX_DOC.MARKUP(

index_name     IN VARCHAR2,
textkey        IN VARCHAR2,
text_query     IN VARCHAR2,
restab         IN OUT NOCOPY CLOB,
plaintext      IN BOOLEAN   DEFAULT FALSE,
tagset         IN VARCHAR2  DEFAULT 'TEXT_DEFAULT',
starttag       IN VARCHAR2  DEFAULT NULL,
endtag         IN VARCHAR2  DEFAULT NULL,
prevtag        IN VARCHAR2  DEFAULT NULL,
nexttag        IN VARCHAR2  DEFAULT NULL,
use_saved_copy IN NUMBER DEFAULT CTX_DOC.SAVE_COPY_FALLBACK);

exec CTX_DOC.MARKUP_CLOB_QUERY(
index_name     IN VARCHAR2,
textkey        IN VARCHAR2,
text_query     IN CLOB,
restab         IN OUT NOCOPY CLOB,
plaintext      IN BOOLEAN DEFAULT FALSE,
tagset         IN VARCHAR2 DEFAULT 'TEXT_DEFAULT',
starttag       IN VARCHAR2 DEFAULT NULL,
endtag         IN VARCHAR2 DEFAULT NULL,
prevtag        IN VARCHAR2 DEFAULT NULL,
nexttag        IN VARCHAR2 DEFAULT NULL,
use_saved_copy IN NUMBER DEFAULT CTX_DOC.SAVE_COPY_FALLBACK);

Syntax 2: Result Table Storage

exec CTX_DOC.MARKUP(

index_name     IN VARCHAR2,
textkey        IN VARCHAR2,
text_query     IN VARCHAR2,
restab         IN VARCHAR2,
query_id       IN NUMBER    DEFAULT 0,
plaintext      IN BOOLEAN   DEFAULT FALSE,
tagset         IN VARCHAR2  DEFAULT 'TEXT_DEFAULT',
starttag       IN VARCHAR2  DEFAULT NULL,
endtag         IN VARCHAR2  DEFAULT NULL,
prevtag        IN VARCHAR2  DEFAULT NULL,
nexttag        IN VARCHAR2  DEFAULT NULL,
use_saved_copy IN NUMBER DEFAULT CTX_DOC.SAVE_COPY_FALLBACK);

exec CTX_DOC.MARKUP_CLOB_QUERY(
index_name     IN VARCHAR2,
textkey        IN CLOB,
text_query     IN VARCHAR2,
restab         IN VARCHAR2,
query_id       IN NUMBER DEFAULT 0,
plaintext      IN BOOLEAN DEFAULT FALSE,
tagset         IN VARCHAR2 DEFAULT 'TEXT_DEFAULT',
starttag       IN VARCHAR2 DEFAULT NULL,
endtag         IN VARCHAR2 DEFAULT NULL,
prevtag        IN VARCHAR2 DEFAULT NULL,
nexttag        IN VARCHAR2 DEFAULT NULL,
use_saved_copy IN NUMBER DEFAULT CTX_DOC.SAVE_COPY_FALLBACK);

index_name

Specify the name of the index associated with the text column containing the document identified by textkey.

textkey

Specify the unique identifier (usually the primary key) for the document.

The textkey parameter can be as follows:

A single column primary key value
Encoded specification for a composite (multiple column) primary key. Use the CTX_DOC.PKENCODE procedure.
The rowid of the row containing the document

Toggle between primary key and rowid identification using CTX_DOC.SET_KEY_TYPE.

text_query

Specify the original query expression used to retrieve the document.

If text_query includes wildcards, stemming, fuzzy matching which result in stopwords being returned, MARKUP does not highlight the stopwords.

If text_query contains the threshold operator, the operator is ignored. The MARKUP procedure always returns highlight information for the entire result set.

restab

You can specify that this procedure store the marked-up text to either a table or to an in-memory CLOB.

To store results to a table specify the name of the table. The result table must exist before you call this procedure.

See Also: For more information about the structure of the markup result table, see “Markup Table” in Oracle Text Result Tables.

To store results in memory, specify the name of the CLOB locator. If restab is NULL, a temporary CLOB is allocated and returned. You must de-allocate the locator after using it.

If restab is not NULL, the CLOB is truncated before the operation.

query_id

Specify the identifier used to identify the row inserted into restab.

When query_id is not specified or set to NULL, it defaults to 0. You must manually truncate the table specified in restab.

plaintext

Specify TRUE to generate plaintext marked-up document. Specify FALSE to generate a marked-up HTML version of document if you are using the AUTO_FILTER filter or indexing HTML documents.

tagset

Specify one of the following predefined tag sets. The second and third columns show how the different tags are defined for each tagset:

Tagset	Tag	Tag Value
`TEXT_DEFAULT`	starttag	`<<<`
`TEXT_DEFAULT`	endtag	`>>>`
`HTML_DEFAULT`	starttag	`<B>`
`HTML_DEFAULT`	endtag	`</B>`
`HTML_NAVIGATE`	starttag	`<A NAME=ctx%CURNUM><B>`
`HTML_NAVIGATE`	endtag	`</B></A>`
`HTML_NAVIGATE`	prevtag	`<A HREF=#ctx%PREVNUM><</A>`
`HTML_NAVIGATE`	nexttag	`<A HREF=#ctx%NEXTNUM>></A>`

starttag

Specify the character(s) inserted by MARKUP to indicate the start of a highlighted term.

The sequence of starttag, endtag, prevtag and nexttag with respect to the highlighted word is as follows:

... prevtag starttag word endtag nexttag...

endtag

Specify the character(s) inserted by MARKUP to indicate the end of a highlighted term.

prevtag

Specify the markup sequence that defines the tag that navigates the user to the previous highlight.

In the markup sequences prevtag and nexttag, you can specify the following offset variables which are set dynamically:

Offset Variable	Value
`%CURNUM`	the current offset number
`%PREVNUM`	the previous offset number
`%NEXTNUM`	the next offset number

See the description of the HTML_NAVIGATE ”“tagset”” for an example.

nexttag

Specify the markup sequence that defines the tag that navigates the user to the next highlight tag.

Within the markup sequence, you can use the same offset variables you use for prevtag. See the explanation for ““prevtag”” and the HTML_NAVIGATE ““tagset”” for an example.

use_saved_copy

Specify whether to refer to the $D table to fetch the copy of the document, and what action to take when the copy of the document is not available in the $D table.

You can specify one of the following values for the use_saved_copy parameter:

CTX_DOC.SAVE_COPY_FALLBACK: Fetch the copy of the document from the $D table. If the copy of the document is not present in the $D table, then fetch the document from the data store.
CTX_DOC.SAVE_COPY_ERROR: Fetch the copy of the document from the $D table. If the copy of the document is not present in the $D table, then show an error message. Specify this value when you want to implement a specific fallback logic when the copy of the document is not available in the $D table.
CTX_DOC.SAVE_COPY_IGNORE: Always fetch the document from the data store.

The default value is CTX_DOC.SAVE_COPY_FALLBACK.

Examples

In-Memory Markup

The following code takes document (the dog chases the cat), performs the assigned markup on it, and stores the result in memory.

set serveroutput on

drop table mark_tab;
create table mark_tab (id number primary key, text varchar2(80) );
insert into mark_tab values ('1', 'The dog chases the cat.');

create index mark_tab_idx on mark_tab(text)
        indextype is ctxsys.context parameters
        ('filter ctxsys.null_filter');

declare
mklob clob;
amt number := 40;
line varchar2(80);

begin
 ctx_doc.markup('mark_tab_idx','1','dog AND cat', mklob);
 -- mklob is NULL when passed-in, so ctx_doc.markup will
 -- allocate a temporary CLOB for us and place the results there.
 dbms_lob.read(mklob, amt, 1, line);
 dbms_output.put_line('FIRST 40 CHARS ARE:'||line);
 -- have to de-allocate the temp lob
 dbms_lob.freetemporary(mklob);
 end;
/

The output from this example shows what the marked-up document looks like:

FIRST 40 CHARS ARE:  The <<<dog>>> chases the <<<cat>>>.

Markup Table

Create the highlight markup table to store the marked-up document as follows:

create table markuptab (query_id  number,
                        document  clob);

Word Highlighting in HTML

You can also store your MARKUP results in a table. To create HTML highlight markup for the words dog or cat for document 23, enter the following examples:

begin
  ctx_doc.markup(index_name => 'my_index',
                      textkey => '23',
                      text_query => 'dog|cat',
                      restab => 'markuptab',
                      query_id => '1',
                      tagset => 'HTML_DEFAULT');
end;

begin
  ctx_doc.markup(index_name => 'my_index',
                      textkey => '23',
                      text_query => 'dog AND cat WITHIN titlesection@name',
                      restab => 'markuptab',
                      query_id => '1',
                      tagset => 'HTML_DEFAULT');
end;

Word Highlighting in the Presence of Filters

When performing markup on queries such as the following, only the keyword (“dog” in these examples) will be marked up. The filtering predicates after the AND operator will be ignored.

begin
  ctx_doc.markup(index_name => 'my_index',
                      textkey => '23',
                      text_query => 'dog AND cat WITHIN titlesection@name',
                      restab => 'markuptab',
                      query_id => '1',
                      tagset => 'HTML_DEFAULT');
end;

begin
  ctx_doc.markup(index_name => 'my_index',
                      textkey => '23',
                      text_query => 'dog AND SDATA(price > 100)',
                      restab => 'markuptab',
                      query_id => '1',
                      tagset => 'HTML_DEFAULT');
end;

Theme Highlighting in HTML

To create HTML highlight markup for the theme of politics for document 23, enter the following statement:

begin
  ctx_doc.markup(index_name => 'my_index',
                      textkey => '23',
                      text_query => 'about(politics)',
                      restab => 'markuptab',
                      query_id => '1',
                      tagset => 'HTML_DEFAULT');
end;

Restrictions

CTX_DOC.MARKUP does not support the use of query templates.

“POLICY_MARKUP”

“SNIPPET”

MARKUP

Syntax 1: In-Memory Result Storage

Syntax 2: Result Table Storage

Examples

Restrictions

Related Topics