SNIPPET

Use the CTX_DOC.SNIPPET procedure to produce a concordance for a document. The output of a snippet is a collection of segments. A concordance is a text fragment that contains a query term with some of its surrounding text. This is also sometimes known as Key Word in Context or KWIC, because it returns query keywords marked up in their surrounding text, which enables the user to evaluate them in context. The returned text can also contain themes that satisfy an ABOUT query.

For example, a search on brillig and slithey might return one relevant fragment of a document as follows:

'Twas <b>brillig</b>, and the <b>slithey</b> toves did gyre and

CTX_DOC.SNIPPET returns one or more most relevant fragments for a document that contains the query term. Because CTX_DOC.SNIPPET returns surrounding text, you can immediately evaluate how useful the returned term is. CTX_DOC.SNIPPET returns the entire document if no words in the returned text are marked up.

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

See Also: CTX_DOC.POLICY_SNIPPET for a policy-based version of this procedure

Syntax

Syntax 1

exec CTX_DOC.SNIPPET(
index_name               IN VARCHAR2,
textkey                  IN VARCHAR2,
text_query               IN VARCHAR2,
starttag                 IN VARCHAR2 DEFAULT '<b>',
endtag                   IN VARCHAR2 DEFAULT '</b>',
entity_translation       IN BOOLEAN  DEFAULT TRUE,
separator                IN VARCHAR2 DEFAULT '<b>...</b>',
radius	                   IN INTEGER DEFAULT 25,
max_length               IN INTEGER DEFAULT 250
use_saved_copy           IN NUMBER DEFAULT CTX_DOC.SAVE_COPY_FALLBACK
return varchar2
);

Syntax 2

exec CTX_DOC.SNIPPET_CLOB_QUERY(
index_name               IN VARCHAR2,
textkey                  IN VARCHAR2,
text_query               IN CLOB,
starttag                 IN VARCHAR2 DEFAULT '<b>',
endtag                   IN VARCHAR2 DEFAULT '</b>',
entity_translation       IN BOOLEAN DEFAULT TRUE,
separator                IN VARCHAR2 DEFAULT '<b>...</b>',
radius	                   IN INTEGER DEFAULT 25,
max_length               IN INTEGER DEFAULT 250
use_saved_copy           IN NUMBER DEFAULT CTX_DOC.SAVE_COPY_FALLBACK
return varchar2
);

index_name

Specify the name of the index for the text column.

textkey

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

The textkey parameter can be as follows:

Use CTX_DOC.SET_KEY_TYPE to toggle between primary key and rowid identification.

text_query

Specify the original query expression used to retrieve the document. If NULL, no highlights are generated.

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

If text_query contains the threshold operator, the operator is ignored.

starttag

Specify the start tag for marking up the query keywords. Default is <b>.

endtag

Specify the end tag for marking up the query keywords. Default is </b>.

entity_translation

Specify if you want HTML entities to be translated. The default is TRUE, which means that the special entities (<, >, and &) are translated into their alternative forms (‘<’, ‘>’, and ‘&’) when output by the procedure. However, special characters in the markup tags that are generated by CTX_DOC.SNIPPET will not be translated.

separator

Specify the string separating different returned fragments. Default is <b>...</b>.

radius

Specify the number of characters to be shown on either side of the hit query in a segment. The character count before the hit query begins on the first character of the first hit query displayed in a segment. Accordingly, the character count after the hit query begins on the last character of the last hit query displayed on a specific segment. Two segments are merged into one if their radii overlap. The displayed number of characters on each side may be modified by +/-10 chars to best match the beginning or ending of a sentence or word.

Special attention is required for the value 0. When specified, the radius is set to automatic and varies between sentences. A best guess of the results is displayed, which attempts to match a full sentence. Note that the length of the radius on each side of the hit query will most likely significantly differ.

The default value is 25.

max_length

Specify the maximum length of the snippet output in characters. This value is currently upper-bounded by the current return type of CTX_DOC.SNIPPET and CTX_DOC.POLICY_SNIPPET (VARCHAR2). Should the output be longer than the return type VARCHAR2, the result will be truncated. The default value for max_length is 250.

If you set max_length value to a very low value, no snippet may be generated. For example, if max_length is set to 0 or if max_length is lower than the length of query tokens themselves, no snippet may be generated at all.

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. The default value is CTX_DOC.SAVE_COPY_FALLBACK.

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

Example

create table tdrbhk01 (id number primary key, text varchar2(4000));

insert into tdrbhk01 values (1, 'Oracle Text adds powerful search
 and intelligent text management to the Oracle
database.  Complete.  You can search and manage documents, web pages,
catalog entries in more than 150 formats in any language.  Provides a
complete text query language and complete character support.  Simple.  You
can index and search text using SQL. Oracle Text Management can be done
using Oracle Enterprise Manager - a GUI tool.  Fast.  You can search
millions of documents, document,web pages, catalog entries using the
power and scalability of the database.  Intelligent.  Oracle Text''s
unique knowledge-base enables you to search, classify, manage
documents, clusters and summarize text based on its meaning as well as
its content. ');

create index tdrbhk01x on tdrbhk01(text) indextype is ctxsys.context;

create or replace function my_snippet_wrapper(
 key in varchar2,
 query in varchar2,
 radius in number,
 max_length in number) return varchar2 is
  buff varchar2(4000);
 begin
  buff := ctx_doc.snippet('tdrbhk01x', key, query, '<b>', '<b>', true, '<b>..<b>', radius, max_length);
  return buff;
 end;
/
show errors;

select my_snippet_wrapper('1','Oracle', 10, 100) from dual;

The result looks something like this:

CTX_DOC.SNIPPET('TDRBHK01X','1','SEARCH|CLASSIFY')
------------------------------------------------------------------------

Text's unique knowledge-base enables you to <b>search</b>,
<b>classify</b>, manage documents, clusters and summarize

Limitations

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

CTX_DOC.SNIPPET displays marked-up keywords in context when used with NULL_SECTION_GROUP. However, there are limitations when using this procedure with XML documents. When used with XML_SECTION_GROUP or AUTO_SECTION_GROUP, the XML structure is ignored and user-specified tags are stripped out, which results in parts of surrounding text to be included in the returned snippet.

“POLICY_SNIPPET”

“HIGHLIGHT”

“MARKUP”