FILTER

Use the CTX_DOC.FILTER procedure to generate either a plain text or HTML version of a document.

You can store the rendered document in either a result table or in memory. This procedure is generally called after a query, from which you identify the document to be filtered.

Note: The resultant HTML document does not include graphics.

Syntax 1: In-memory Result Storage

exec CTX_DOC.FILTER(
          index_name  IN VARCHAR2,
          textkey     IN VARCHAR2,
          restab      IN OUT NOCOPY CLOB,
          plaintext   IN BOOLEAN DEFAULT FALSE,
          use_saved_copy IN NUMBER DEFAULT CTX_DOC.SAVE_COPY_FALLBACK);

Syntax 2: Result Table Storage

exec CTX_DOC.FILTER(
          index_name  IN VARCHAR2,
          textkey     IN VARCHAR2,
          restab      IN VARCHAR2,
          query_id    IN NUMBER DEFAULT 0,
          plaintext   IN BOOLEAN DEFAULT FALSE,
          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 CTX_DOC.PKENCODE

• the rowid of the row containing the document

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

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 table to which you want to store results must exist before you make this call.

See Also: “Filter Table” in Oracle Text Result Tables for more information about the structure of the filter result table

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

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

query_id

Specify an identifier to use 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 a plaintext version of the document. Specify FALSE to generate an HTML version of the document if you are using the AUTO_FILTER filter or indexing HTML documents.

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 datastore.

• CTX_DOC.SAVE_COPY_ERROR: Fetch the copy of the document from the $D table. If the SAVE_COPY option of the index is set to none and the document is not present in the $D table, then show the CTX_DOC.SAVE_COPY_ERROR error. If the SAVE_COPY option of the index is set to plaintext or filtered and the document is not present in the $D table, then show the nodoc_err error. If the document is present in the $D table, then retrieve the document from the datastore.

• CTX_DOC.SAVE_COPY_IGNORE: Always fetch the document from the datastore.

The default value is CTX_DOC.SAVE_COPY_FALLBACK.

Example

In-Memory Filter

The following code shows how to filter a document to HTML in memory.

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

begin
 ctx_doc.filter('myindex','1', mklob, FALSE);
 -- mklob is NULL when passed-in, so ctx-doc.filter 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;

Create the filter result table to store the filtered document as follows:

create table filtertab (query_id  number,
                        document  clob);

To obtain a plaintext version of document with textkey 20, enter the following statement:

begin
ctx_doc.filter('newsindex', '20', 'filtertab', '0', TRUE);
end;