Oracle8 ConText Cartridge Application Developer's Guide
Release 2.3

A58164-01

Library

Product

Contents

Index

Prev Next

10
PL/SQL Packages

This chapter describes the ConText Option PL/SQL packages you use to develop applications. The following topics are described in this chapter are:

Developing with ConText PL/SQL Packages

Before you can develop your own PL/SQL stored procedures and triggers that call the procedures in the ConText packages described in this chapter, your ConText administrator must explicitly grant EXECUTE privileges to you for each ConText PL/SQL package you use.

.

See Also:

For more information about granting execute privileges, see Oracle8 ConText Cartridge Administrator's Guide.

For more information about creating and invoking PL/SQL packages, see Oracle8 Server Application Developer's Guide.

 

CTX_QUERY: Query and Highlighting

The CTX_QUERY package contains stored procedures and functions that enable processing of two-step queries and highlighting for documents returned by queries.

The package includes the following procedures and functions:

Name   Description  

CLOSE_CON  

Closes the in-memory query cursor.  

CONTAINS  

Selects documents in the text column for a policy and writes the results to a specified result table.  

COUNT_HITS  

Performs a query and returns the number of hits without returning a hitlist.  

COUNT_LAST  

Returns the number of hits retrieved in the last call to CONTAINS or OPEN_CON.  

FEEDBACK  

Generates query expression feedback information.  

FETCH_HIT  

Retrieves hits stored in query buffer by OPEN_CON.  

GETTAB  

Gets tables from the result table pool.  

HIGHLIGHT  

Provides filtering and/or highlighting for documents returned by a query.  

OPEN_CON  

Opens a cursor and executes an in-memory query.  

PKDECODE  

Decodes a composite textkey string (value).  

PKENCODE  

Encodes a composite textkey string (value).  

PURGE_SQE  

Deletes all SQEs from SQE tables.  

REFRESH_SQE  

Re-executes an SQE and updates the results stored in the SQE tables.  

RELTAB  

Releases tables allocated by GETTAB.  

REMOVE_SQE  

Removes a specified SQE from the SQL tables.  

STORE_SQE  

Executes a query and stores the results in stored query expression tables.  


CLOSE_CON

The CTX_QUERY.CLOSE_CON procedure closes a cursor opened by CTX_QUERY.OPEN_CON. It is used in in-memory queries and called after CTX_QUERY.FETCH_HIT, which retrieves the desired number of hits.

Syntax

CTX_QUERY.CLOSE_CON(curid NUMBER);

curid

Specify the cursor to be closed.

Examples

See CTX_QUERY.FETCH_HIT.


CONTAINS

The CTX_QUERY.CONTAINS procedure selects documents from a text column that match the specified search criteria, generates scores for each document, and writes the results to a specified hitlist result table.

Syntax

CTX_QUERY.CONTAINS(
         policy_name[@dblink]  IN VARCHAR2,
         text_query            IN VARCHAR2,
         restab                IN VARCHAR2,
         sharelevel            IN NUMBER   DEFAULT 0, 
         query_id              IN NUMBER,
         cursor_id             IN NUMBER, 
         parallel              IN NUMBER,
         struct_query          IN VARCHAR2);

policy_name

Specify the policy that identifies the text column to be searched.

If a database link to a remote database has been created, the database link can be specified as part of the policy name (using the syntax shown) to reference a policy in the remote database.

text_query

Specify the query expression to be used as criteria for selecting rows.

See Also:

For more information about how to write query expressions, see Chapter 3, "Understanding Query Expressions".

 

restab

Specify the name of the hitlist table that stores intermediate results returned by CONTAINS.

sharelevel

Specify whether the results table is shared by multiple CONTAINS. Specify 0 for exclusive use and 1 for shared use. This parameter defaults to 0 (single-use).

When you specify 0, the system automatically truncates the result table before the query. In this case, conid is set to NULL and query_id is ignored.

When you specify 1 for multiple use, you must give a query_id to distinguish the results in the shared result table. Because the system does not truncate shared result tables, you must get rid of results from a previous CONTAINS by deleting from the result table where conid = query_id before you issue the query.

query_id

Specify the ID used to identify query results returned by a CONTAINS procedure when more than one CONTAINS uses the same result table (sharelevel = 1).

cursor_id

Not currently used.

parallel

Specify the number of ConText servers (with the Query personality) which execute a query and write the results to restab.

struct_query

Specify the structured WHERE condition related to text_query. This WHERE condition can include a subquery that selects rows from a structured data column in another table.

Examples

exec ctx_query.contains('my_pol', 'cat|dog','CTX_TEMP', 1, 10)

exec ctx_query.contains('my_pol@db1', 'oracle','CTX_DB1_TEMP')

In the first example, the results of the query for the term cat or dog are stored in the ctx_temp result table. The result table is shared because sharelevel is specified as 1. The results in ctx_temp are identified by query_id of 10.

In the second example, my_pol exists in a remote database that has a database link named DB1. The result table, ctx_db1_temp exists in the same remote database.

Notes

The parallel parameter does not support the max ( : ) and first/next ( #) query expression operators. When you specify either operator in the query expression, the query is processed by a single ConText server, regardless of the specified parallel level.

sharelevel determines whether the hitlist result table is shared by multiple CONTAINS procedures.

If the result table (restab) is used to hold the results of multiple CONTAINS, a sharelevel must be specified by each CONTAINS so that the results of previous CONTAINS are not truncated.

If a query is performed on a policy in a remote database, the result table specified by restab must exist in the remote database.

In struct_query, you can use any predicate, value expression or subquery except USERENV function, CONTAINS function, SCORE function, DISPLAY function and the ROWNUM pseudo column.

If the user who includes a structured query in a two-step query is not the owner of the table containing the structured and text columns, the user must have SELECT privilege with GRANT OPTION on the table. In addition, if the object being queried is a view, the user must have SELECT privilege with GRANT OPTION on the base table for the view.

See Also:

For more information about SELECT privilege with GRANT OPTION, see Oracle8 Server SQL Reference.

 


COUNT_HITS

The CTX_QUERY.COUNT_HITS function executes a query for a policy and returns the number of hits for the query. It does not populate a result table with query results.

COUNT_HITS can be called in two modes, estimate and exact. The results in estimate mode may be inaccurate; however, the results are generally returned faster than in exact mode.

Syntax

CTX_QUERY.COUNT_HITS(
                policy_name[@dblink]  IN VARCHAR2, 
                text_query            IN VARCHAR2,
                struct_query          IN VARCHAR2,
                exact                 IN BOOLEAN DEFAULT FALSE)
RETURN NUMBER;

policy_name[@dblink]

Specify the name of the policy that defines the column to be searched.

If a database link to a remote database has been created, the database link can be specified as part of the policy name (using the syntax shown) to reference a policy in the remote database.

text_query

Specify the query expression to be used as criteria for counting returned hits (rows)

struct_query

Specify the structured where condition related to text_query.

exact

Specify TRUE to obtain an exact count of the documents in the hitlist. Specify FALSE to obtain an estimate count. The result returned when you request an estimate count includes hits for documents that have been deleted or updated. The default is FALSE.

Examples

declare count number;
begin
count := ctx_query.count_hits(my_pol, 'dog|cat', TRUE);
dbms_output.put_line('No. of Docs with dog or cat:');
dbms_output.put_line(count);
end;

Returns

NUMBER that represents the number of hits.

Notes

Counting query hits can be performed in two modes: estimate and exact. The modes are based on the method ConText uses to record deleted documents in a text index.

In exact mode, hits are returned only for those documents that satisfy the conditions of the query expression and are currently in the text column of the table.

In estimate mode, hits may be included for documents that satisfy the query condition, but have been deleted from the text column or have been updated so that they no longer satisfy the query expression. This can occur when the text index for the column has not been optimized and the internal document IDs are still present in the index.

In general, the inaccuracy of the results returned by COUNT_HITS in estimate mode is proportional to the amount of DML that has been performed on a text column.


Note:

If the index being queried has been optimized and no further DML has been performed on the text column, estimate mode will return accurate results.

 

See Also:

For more information about text indexing, DML, and optimization, see Oracle8 ConText Cartridge Administrator's Guide.

 


COUNT_LAST

Use the CTX_QUERY.COUNT_LAST function to obtain the number of hits after executing CONTAINS in a two-step query or OPEN_CON in an in-memory query. The alternative method of obtaining the number of hits is to run the query once to get the row count using CTX_QUERY.COUNT_HITS and then run the query again to get the query results.

Syntax

CTX_	QUERY.COUNT_LAST        RETURN NUMBER; 

Returns

The number of hits obtained from the last call to CTX_QUERY.CONTAINS or CTX_QUERY.OPEN_CON.

Examples

In-memory Query
declare

curid number;
count number;
begin
curid := ctx_query.open_con('mypol', 'me', score_sorted=>true);count := ctx_query.count_last ;
end

Two-step Query
declare
count number;
begin
ctx_query.contains('mypol', 'dog', 'ctx_temp');count := ctx_query.count_last ;
end

Notes

With two-step queries, COUNT_LAST always returns an exact count.

With in-memory queries, COUNT_LAST returns an exact count except when you include a structured condition, in which case it returns an estimate. This is because COUNT_LAST ignores the structured condition, specified in the struct_query parameter of OPEN_CON, when computing number of hits in an in-memory query.

For two-step queries, the COUNT_LAST function is not meant to replace calling COUNT_HITS, which is always faster than running the query. However, in the case where you want to process all hits in a two-step query, issuing the query with CONTAINS and then calling COUNT_LAST is more efficient than calling COUNT_HITS and then calling CONTAINS.

With in-memory queries, issuing OPEN_CON and then calling COUNT_LAST is always a more efficient way to obtain an estimate of the query hits over calling COUNT_HITS and then calling OPEN_CON, since COUNT_LAST returns a number faster than COUNT_HITS.


FEEDBACK

Use CTX_QUERY.FEEDBACK to generate feedback information for query expressions. This procedure creates a graphical representation of the ConText parse tree and stores the information in a feedback table.

Syntax

CTX_QUERY.FEEEDBACK(
           policy_name     IN VARCHAR2,
           text_query      IN VARCHAR2,
           feedback_table  IN VARCHAR2,
           sharelevel      IN NUMBER DEFAULT 0,
           feedback_id     IN VARCHAR2 DEFAULT NULL
);

policy_name

Specify the policy that identifies the text column to be queried.

text_query

Specify the query expression to be used as criteria for selecting rows.

feedback_table

Specify the name of the feedback table to store representation of the ConText parse tree for text_query.

sharelevel

Specify whether feedback_table is shared by multiple FEEDBACK calls. Specify 0 for exclusive use and 1 for shared use. This parameter defaults to 0 (single-use).

When you specify 0, the system automatically truncates the feedback table before the next call to FEEDBACK.

When you specify 1 for shared use, Context does not truncate the feedback table. Only results with the same feedback_id are updated. When no results with the same feedback_id exist, then new results are added to the feedback table.

feedback_id

Specify a name that identifies the feedback results returned by a FEEDBACK procedure when more than one FEEDBACK call uses the same shared feedback table. This parameter defaults to NULL.

Notes

The user must have at least INSERT and DELETE privileges on the feedback table. You must have at least CTXUSER role to call FEEDBACK.

When you include a wildcard, fuzzy, or soundex operator in text_query, ConText looks at the index tables to determine the expansion.

When you include the SQE operator in text_query, the expression feedback (expansion of the SQE expression) is based on the current state of the index and will take into account any inserts, updates, or deletes made to the base table; however, unlike a call to CONTAINS, the SQE is not updated or refreshed as a result of the call to FEEDBACK.

Wildcard, fuzzy (?), and soundex (!) expression feedback does not account for lazy deletes.

You cannot use FEEDBACK with remote queries.

To use the FEEDBACK procedure, you must have at least one Q server running.

.

See Also:

For more information on using the FEEDBACK procedure, see Chapter 5, "Query Expression Feedback".

 


FETCH_HIT

The CTX_QUERY.FETCH_HIT function returns a hit stored in the query buffer created by CTX_QUERY.OPEN_CON. You must call FETCH_HIT once for each hit in the buffer until the desired number of hits is returned or the buffer is empty.

Syntax

CTX_QUERY.FETCH_HIT(
          curid     IN  NUMBER,
          pk        OUT VARCHAR2,
          score     OUT NUMBER,
          col1      OUT VARCHAR2, 
          col2      OUT VARCHAR2,
          col3      OUT VARCHAR2, 
          col4      OUT VARCHAR2, 
          col5      OUT VARCAHR2);

curid

Specify the cursor opened by CTX_QUERY.OPEN_CON.

pk

Returns the primary key of the document. When the primary key is a composite textkey, PK is returned as encoded string. In this situation, use CTX_QUERY.PKDECODE to access an individual textkey column.

score

Returns the score of the document.

col1-5

Returns additional columns for the document.

Returns

NUMBER that indicates whether hit was retrieved: 0 if no hits fetched, 1 if hit was fetched.

Example

declare 
  score  char(5); 
  pk     char(5); 
  curid  number; 
  title  char(256);
begin 
  dbms_output.enable(100000); 
     curid := ctx_query.open_con(
                       policy_name  =>  'MY_POL', 
                       text_query   =>  'dog',
                       score_sorted =>  true, 
                       other_cols   =>  'title'); 
  while (ctx_query.fetch_hit(curid, pk, score, title)>0)
  loop 
      dbms_output.put_line(score||pk||substr(title,1,50)); 
    end loop; 
  ctx_query.close_con(curid); 

end;

Notes

If the primary key PK is a composite textkey, use CTX_QUERY.PKDECODE to access the individual columns of the textkey.


GETTAB

CTX_QUERY.GETTAB procedure allocates result tables from the result table pool to be used to store results from CTX_QUERY.HIGHLIGHT or CTX_QUERY.CONTAINS.

If no result table of the specified type exists, GETTAB creates a new table.

Syntax

CTX_QUERY.GETTAB(
          type          IN  VARCHAR2, 
          tab           OUT VARCHAR2, 
          tk_count      IN  NUMBER  DEFAULT 1);

type

Specify the type of table to be allocated for text processing. This parameter must be fully qualified with the PL/SQL package name (CTX_QUERY). The type of table you specify can be one of the following:

Table Type   Description   Stores Results For  

DOCTAB  

Result table which is used to store the marked-up text (MUTAB) or plain ASCII text (PLAINTAB) returned by CTX_QUERY.HIGHLIGHT  

MUTAB or
PLAINTAB  

RDOCTAB  

Result table which is used to store the non-filtered documents (NOFILTAB) or ICF output (ICFTAB) returned by CTX_QUERY.HIGHLIGHT  

NOFILTAB or
ICFTAB  

HIGHTAB  

Result table which is used to store the textkey, offsets, and lengths of query terms to be highlighted in documents (returned by CTX_QUERY.HIGHLIGHT)  

HIGHTAB  

HITTAB  

Result table which is used to store the hitlist data returned by CTX_QUERY.CONTAINS  

Hitlist Result Table.  

See Also:

For more information about the structure of result tables, see Appendix A, "Result Tables".

For more information about using HIGHLIGHT, see Chapter 6, "Document Presentation".

 

tab

Returns the name of the allocated table.

tk_count

Specify the number of textkeys in the allocated result table. This parameter applies only to HITTAB tables. The tk_count parameter defaults to 1.

Examples

set serveroutput on 
 declare 
   mytab varchar2(32) ; 
begin 
   ctx_query.gettab(CTX_QUERY.HITTAB, mytab, 3) ; 
   dbms_output.put_line('table : '||mytab) ; 
 end ; 

This example returns a HITTAB result table that has a three-column composite textkey. The name of the table is then output.

The schema for the returned table is: TEXTKEY, TEXTKEY2, TEXTKEY3, SCORE, CONID.

Notes

The tk_count parameter applies only to HITTAB tables; it has no effect on other table types.


HIGHLIGHT

THE CTX_QUERY.HIGHLIGHT procedure takes a query specification and a document textkey and returns information that you can use to display the document with or without the query terms highlighted. This procedure is usually used after a query, from which you identify the document to be processed.

Syntax

CTX_QUERY.HIGHLIGHT(
          cspec       IN VARCHAR2, 
          textkey     IN VARCHAR2, 
          query       IN VARCHAR2 DEFAULT NULL, 
          id          IN NUMBER   DEFAULT NULL,
          nofilttab   IN VARCHAR2 DEFAULT NULL, 
          plaintab    IN VARCHAR2 DEFAULT NULL, 
          hightab     IN VARCHAR2 DEFAULT NULL, 
          icftab      IN VARCHAR2 DEFAULT NULL, 
          mutab       IN VARCHAR2 DEFAULT NULL,
          starttag    IN VARCHAR2 DEFAULT NULL,
          endtag      IN VARCHAR2 DEFAULT NULL);

cspec

Specify the policy name for the column in which the document is stored.

textkey

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

The textkey parameter can be a single column textkey or an encoded specification for a composite (multiple column) textkey.

query

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

id

Specify the identifier to be used in the results tables to identify the rows that were returned by this procedure call. If NULL, the result tables are truncated.

nofilttab

Specify name of the RDOCTAB table where unfiltered document is stored. If NULL, the unfiltered version is not returned.

plaintab

Specify the name of the DOCTAB table where plain text version of document is stored. If NULL, the plain text is not returned.

hightab

Specify the name of the HIGHTAB table where highlight information for the document is stored. If NULL, the highlights are not returned.

icftab

Used internally by the Windows 32-bit viewer to specify where the ICF output required for WYSIWYG viewing of documents is stored. If NULL, the ICF is not returned.

mutab

Specify table where marked-up, ASCII version of document is stored. If NULL, marked-up version is not returned.

starttag

Specify the markup to be inserted by HIGHLIGHT for indicating the start of a highlighted term.

The default for ASCII and formatted documents is'<<<'.

The default for HTML documents filtered using an external filter is'<<<'.

The default for HTML documents filtered using the internal HTML filter is the HTML tag used to indicate the beginning of a font change (i.e. <FONT =...>).

endtag

Specify the markup to be inserted by HIGHLIGHT for indicating the end of a highlighted term.

The default for ASCII and formatted documents is'>>>'.

The default for HTML documents filtered using an external filter is'>>>'.

The default for HTML documents filtered using the internal HTML filter is the HTML tag used to indicate the end of a font change (i.e. </FONT>).

Examples

begin
  ctx_query.highlight(cspec => '2354',
                      textkey => '23',
                      query => 'dog|cat',
                      nofiltab => 'FORMATTED_TEXT',
                      hightab => 'HIGHLIGHTED_TEXT',
                      starttag => '<**<',
                      endtag => '>**>');
end;

Notes

Before CTX_QUERY.HIGHLIGHT is called, the highlight/display result tables (NOFILTAB, PLAINTAB, HIGHTAB, MUTAB, and ICFTAB) for the desired output must be created, either manually or using the PL/SQL procedure CTX_QUERY.GETTAB.

If the query argument is not specified or is set to NULL, highlighting is not generated.

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

When textkey is a composite textkey, you must encode the composite textkey string using the CTX_QUERY.PKENCODE procedure.

If any of the table name parameters are omitted or set to NULL, the respective table is not populated.

If the id argument is not specified or if id is set to NULL, each specified table has all its rows deleted and the session-id is used as the ID for all inserted rows. If an id is specified, all rows with the same id are deleted from the respective tables before new rows are generated with that id by the HIGHLIGHT procedure.

For HTML documents filtered through the internal HTML filter, the ASCII output generated for MUTAB retains the HTML tags from the original document.

For HTML documents filtered through an external filter, HIGHLIGHT removes all the HTML tags and stores only the plain (ASCII) marked-up text for the document in MUTAB.

See Also:

For more information about internal and external filters, see Oracle8 ConText Cartridge Administrator's Guide.

For more information about the structure of result tables, see Appendix A, "Result Tables".

 


OPEN_CON

The CTX_QUERY.OPEN_CON function opens a cursor to a query buffer and executes a query using the specified query expression. The results of the query are stored in the buffer and retrieved using CTX_QUERY.FETCH_HIT.

Syntax

CTX_QUERY.OPEN_CON(
               policy_name[@dblink]    IN VARCHAR2, 
               text_query              IN VARCHAR2, 
               score_sorted            IN BOOLEAN DEFAULT FALSE,
               other_cols              IN VARCHAR2,
               struct_query            IN VARCHAR2)
RETURN NUMBER;

policy_name[@dblink]

Specify the name of the policy that defines the column to be searched.

If a database link to a remote database has been created, the database link can be specified as part of the policy name (using the syntax shown) to reference a policy in the remote database.

text_query

Specify the query expression to be used as criteria for selecting rows.

score_sorted

Specify whether the results are sorted by score.

The default is FALSE.

other_cols

Specify a comma separated list of the table columns (up to 5) to be displayed, in addition to document ID and score, in the hitlist.

struct_query

Specify the structured WHERE condition related to text_query. This WHERE condition can include a subquery that selects rows from a structured data column in another table.

Returns

Cursor ID.

Examples

declare 
cid number;
begin
cid := ctx_query.open_con('MYPOL', 'dog', score_sorted =>true, struct_query => 'id < 900');
end;

In this example, the structured condition specifies that ConText must return the documents that contain dog and where the document id is greater than 900.

See Also:

CTX_QUERY.FETCH_HIT.

 


PKDECODE

The CTX_QUERY.PKDECODE function extracts and returns a composite textkey element from a composite textkey string.

This function is useful for in-memory queries when querying against a composite textkey table. Use PKDECODE to extract textkey columns from the primary key returned by CTX_QUERY.FETCH_HIT.

Syntax

CTX_QUERY.PKDECODE(
                 encoded_tk  IN VARCHAR2,
                 which       IN NUMBER)
RETURN VARCHAR2;

encoded_tk

Specify the encoded composite textkey string

which

Specify the ordinal position of which primary key to extract from encoded_tk. When which is 0 or a number greater than the number of textkeys in encoded_tk, encoded_tk is returned.

Returns

String that represents the decoded value of the composite textkey.

Examples

declare pkey varchar2(64);
begin
pkey := ctx_query.pkdecode('p1,p2,p3', 2)
pkey := ctx_query.pkdecode('p1,p2,p3', 0)
pkey := ctx_query.pkdecode('p1,p2,p3', 5)
end;

In this example, the value for the textkey is p1,p2,p3. The first call to PKDECODE returns the value p2. The second and third calls to PKDECODE specify ordinal positions that don't exist, thus these calls return the same value, which is the concatenated value p1,p2,p3.


PKENCODE

The CTX_QUERY.PKENCODE function converts a composite textkey list into a single string and returns the string.

The string created by PKENCODE can be used as the primary key parameter PK in other ConText procedures, such as CTX_LING.REQUEST_GIST.

Syntax

CTX_QUERY.PKENCODE(
         pk1    IN VARCHAR2,
         pk2    IN VARCHAR2, 
         pk4    IN VARCHAR2, 
         pk5    IN VARCHAR2, 
         pk6    IN VARCHAR2,
         pk7    IN VARCHAR2,
         pk8    IN VARCHAR2,
         pk9    IN VARCHAR2,
         pk10   IN VARCHAR2,
         pk11   IN VARCHAR2,
         pk12   IN VARCHAR2,
         pk13   IN VARCHAR2,
         pk14   IN VARCHAR2,
         pk15   IN VARCHAR2,
         pk16   IN VARCHAR2)
RETURN VARCHAR2;

pk1-pk16

Each PK argument specifies a column element in the composite textkey list. You can encode at most 16 column elements.

Returns

String that represents the encoded value of the composite textkey.

Examples

exec ctx_ling.request_gist('my_policy',\
CTX_QUERY.PKENCODE('pk1-date', 'pk2-data'), 'theme table')

In this example, pk1-date and pk2-data constitute the composite textkey value for the document.


PURGE_SQE

The CTX_QUERY.PURGE_SQE procedure removes all session stored query expressions for the current session. Session SQEs in other sessions are not affected by PURGE_SQE.

Syntax

CTX_QUERY.PURGE_SQE(policy_name   IN VARCHAR2);

policy_name

Specify the name of the policy for which the current session SQEs are purged.

Examples

exec ctx_query.purge_sqe(my_pol)


REFRESH_SQE

The CTX_QUERY.REFRESH_SQE procedure re-executes a stored query expression and stores the results in the SQR table, overwriting existing results.

See Also:

For more information about the structure of the SQR table, see Oracle8 ConText Cartridge Administrator's Guide.

 

Syntax

CTX_QUERY.REFRESH_SQE(
                 policy_name  IN VARCHAR2,
                 query_name   IN VARCHAR2);

policy_name

Specify the policy for the stored query expression.

query_name

Specify the name of the stored query expression to be refreshed.

Examples

exec ctx_query.refresh_sqe('my_pol', 'DOG')


RELTAB

The CTX_QUERY.RELTAB procedure releases a table previously allocated by CTX_QUERY.GETTAB.

Syntax

CTX_QUERY.RELTAB(tab  IN VARCHAR2);

tab

Specify the name of table to be released, previously assigned by CTX_QUERY.GETTAB.

Examples


set serveroutput on 
 declare 
   mytab varchar2(32) ; 
begin 
   ctx_query.gettab(CTX_QUERY.HITTAB, mytab, 3) ; 
   dbms_output.put_line('table : '||mytab) ; 

   ....

   ctx_query.reltab(mytab);
end ;

This PL/SQL example allocates a HITTAB result table with GETTAB, then releases it with RELTAB.


REMOVE_SQE

The CTX_QUERY.REMOVE_SQE procedure removes a specified stored query expression from the system SQE table and the results of the SQE from the SQR table for the policy.

See Also:

For more information about the structure of the SQE and SQR tables, see Oracle8 ConText Cartridge Administrator's Guide.

 

Syntax

CTX_QUERY.REMOVE_SQE(
                 policy_name    IN VARCHAR2,
                 query_name     IN VARCHAR2);

policy_name

Specify the policy for the stored query expression.

query_name

Specify the name of the stored query expression to be removed.

Examples

exec ctx_query.remove_sqe('my_pol', 'DOG')


STORE_SQE

The CTX_QUERY.STORE_SQE procedure executes a query for a policy and stores the named SQE in the SQE table and results from the SQE in the SQR table for the policy.

See Also:

For more information about the structure of the SQE and SQR tables, see Oracle8 ConText Cartridge Administrator's Guide.

 

Syntax

CTX_QUERY.STORE_SQE(
              policy_name    IN VARCHAR2, 
              query_name     IN VARCHAR2,
              text_query     IN VARCHAR2,
              scope          IN VARCHAR2);

policy_name

Specify the policy for the stored query expression.

query_name

Specify the name of the stored query expression to be created.

text_query

Specify the query expression.

scope

Specify whether the SQE is a session or system. When you specify session, the stored query expression exists only for the current session. When you specify system, the stored query expression can be used in all sessions including concurrent sessions. SQEs defined as system are not deleted when your session terminates.

Examples

exec ctx_query.store_sqe('my_pol', 'DOG', '$(dogs|puppy)',\
'session')

Notes

SQEs support all of the ConText query expression operators, except for:

SQEs also support all of the special characters and other components that can be used in a query expression, including PL/SQL functions and other SQEs.

CTX_LING:Linguistics

CTX_LING is the package of PL/SQL procedures used to request linguistic output and to control how requests are submitted and processed by ConText servers with the Linguistics personality.

CTX_LING contains the following stored procedures and functions:

Name   Description  

CANCEL  

Cancels all cached theme and gist requests.  

GET_COMPLETION_CALLBACK  

Returns the completion callback procedure specified for the current session.  

GET_ERROR_CALLBACK  

Returns the error callback procedure specified for the current session.  

GET_FULL_THEMES  

Returns TRUE when theme hierarchy generation is enabled for the current session.  

GET_LOG_PARSE  

Returns TRUE when parse logging is enabled for current session.  

GET_SETTINGS_LABEL  

Returns the currently active setting configuration.  

REQUEST_GIST  

Requests gists for a document.  

REQUEST_THEMES  

Requests themes for a document.  

SET_COMPLETION_CALLBACK  

Specifies a procedure to be called when a request completes.  

SET_ERROR_CALLBACK  

Specifies a procedure to be called if an error is encountered by a request.  

SET_FULL_THEMES  

Enables/disables the writing of theme hierarchy information.  

SET_LOG_PARSE  

Enables/disables logging of parse information for the current session.  

SET_SETTINGS_LABEL  

Specifies a setting configuration for the current session.  

SUBMIT  

Submits all cached theme and gist requests to Services Queue.  


CANCEL

The CTX_LING.CANCEL procedure cancels all pending linguistic requests cached in memory.

Syntax

CTX_LING.CANCEL ;

Examples

exec ctx_ling.cancel

Notes

Requests for themes and gists are cached in memory until CTX_LING.SUBMIT is called. CTX_LING.CANCEL only cancels these cached requests. After these requests have been submitted and placed in the Service Queue, CTX_LING.CANCEL has no effect.

To cancel requests that have already been submitted to the Services Queue, use CTX_SVC.CANCEL.


GET_COMPLETION_CALLBACK

The CTX_LING.GET_COMPLETION_CALLBACK function returns the name of the completion callback procedure for the current session (specified in CTX_LING.SET_COMPLETION_CALLBACK).

Syntax

CTX_LING.GET_COMPLETION_CALLBACK        RETURN VARCHAR2;

Returns

Completion callback procedure.

Examples

declare callback varchar2(60);
begin
  callback := get_completion_callback;
  dbms_output.put_line('Completion callback:');
  dbms_output.put_line(callback);
end;

Notes

To call procedures for both completed task processing as well as error processing, you must also identify the error completion processing routine with CTX_LING.SET_COMPLETION_CALLBACK.

If both completion and error callback procedures are defined, the completion callback routine is performed first, then the error callback routine.

The value assigned to VARCHAR2 in the declarative part of the PL/SQL block depends on the length of the name for the specified completion callback.


GET_ERROR_CALLBACK

The CTX_LING.GET_ERROR_CALLBACK function returns the name of the error callback procedure for the current session (specified in CTX_LING.SET_ERROR_CALLBACK).

Syntax

CTX_LING.GET_ERROR_CALLBACK     RETURN VARCHAR2;

Returns

Error callback procedure.

Examples

declare e_callback varchar2(60);
begin
   e_callback := ctx_ling.get_error_callback;
   dbms_output.put_line('Error callback:');
   dbms_output.put_line(e_callback);
end;

Notes

If both completion and error callback are set, the completion callback is performed first, then the error callback.

The value assigned to VARCHAR2 in the declarative part of the PL/SQL block depends on the length of the name for the specified completion callback.


GET_FULL_THEMES

This function returns TRUE if the generation of theme hierarchy information is enabled for the current session; otherwise it returns FALSE.

You enable the generation of theme hierarchy information with SET_FULL_THEMES. ConText writes theme hierarchy information to the THEME column of the theme table when you call REQUEST_THEMES.

Syntax

CTX_LING.GET_FULL_THEMES  RETURN BOOLEAN; 

Returns

Returns TRUE if the generation of theme hierarchy information is enabled; otherwise returns FALSE.


GET_LOG_PARSE

The CTX_LING.GET_LOG_PARSE function returns a FALSE or TRUE string to indicate whether parse logging is enabled for the current database session (specified in CTX_LING.SET_LOG_PARSE).

Syntax

CTX_LING.GET_LOG_PARSE     RETURN BOOLEAN;

Returns

TRUE if parse logging is enabled, FALSE if parse logging is not enabled.

Examples

declare parse_logging boolean;
begin
   parse_logging := get_log_parse;
end;


GET_SETTINGS_LABEL

The CTX_LING.GET_SETTINGS_LABEL function returns the label for the setting configuration that is active for the current session (specified in CTX_LING.SET_SETTINGS_LABEL).

Syntax

CTX_LING.GET_SETTINGS_LABEL  RETURN VARCHAR2;

Returns

Current settings configuration label.

Examples

declare settings varchar2(60);
begin
   settings := get_settings_label;
   dbms_output.put_line('Current setting configuration:');
   dbms_output.put_line(settings);
end;

Notes

The value assigned to VARCHAR2 in the declarative part of the PL/SQL block depends on the character length of the label for the specified setting configuration. The maximum length of a setting configuration label is 80 characters.


REQUEST_GIST

Use the CTX_LING.REQUEST_GIST procedure to generate theme summaries and a Gist for a document. You can generate paragraph-level or sentence-level Gists and theme summaries.

By default, this procedure generates theme summaries for all the themes in a document (up to 16); however, you can specify a single theme for which a theme summary is to be generated.

Syntax

CTX_LING.REQUEST_GIST(
                policy   IN VARCHAR2, 
                pk       IN VARCHAR2, 
                table    IN VARCHAR2, 
                glevel   IN VARCHAR2 DEFAULT `PARAGRAPH',
                pov      IN VARCHAR2 DEFAULT NULL);

policy

Specify the name of the ConText policy on the column.

pk

Specify the primary key (textkey) of the document (row) to be processed. The parameter pk can be a single column textkey or an encoded specification for a multiple column textkey.

table

Specify the table used to store the gist output.

glevel

Specify the type of Gist/theme summary to produce. The possible values are:

The default is paragraph.

pov

Specify the theme for which a single Gist or theme summary is generated. The type of Gist/theme summary generated (sentence-level or paragraph-level) depends on the value specified for glevel.

To generate a Gist for the document, specify a theme of `GENERIC' for pov. To generate a theme summary for the document, specify the theme from the document for which the matching paragraphs/sentences are selected.

If you specify a NULL value for pov, ConText generates a Gist for the document and a theme summary for each of the document themes (up to 16).


Note:

The pov parameter is case sensitive. To return a Gist for a document, specify `GENERIC' in all uppercase. To return a theme summary, specify the theme exactly as it is generated for the document.

The themes generated by CTX_LING.REQUEST_THEMES can be used as input for pov.

 

Examples

exec ctx_ling.request_gist('my_pol', '34', 'ctx_gist')
begin
ctx_ling.request_gist('doc_pol',
CTX_QUERY.PKENCODE('Jones','Naval Inst Pr','10-1-1970'),
'CTX_GIST');
end;

Theme Summary Generation for a Single Theme

In the following example, a single, paragraph-level theme summary is generated for a document with a pk of 1442 stored in the text column for policy my_pol. The theme (pov) for which the theme summary is generated is Oracle Corporation:

exec ctx_ling.request_gist(`my_pol','1442','ctx_gist',pov=>'Oracle Corporation')
Sentence-level Gist

In the following example, a sentence-level Gist is generated for document with a pk of 1442 stored in the text column for policy my_pol:

exec ctx_ling.request_gist(`my_pol','1442','ctx_gist','sentence','GENERIC')

Notes

You must call the CTX_LING.REQUEST_GIST procedure once for each document for which you want to generate gists.

By default, ConText linguistics generates up to 16 themes for a document. If the user settings specify that gists are to be created for only the top 10 themes of the document, the REQUEST_GIST procedure creates a total of 11 gists: one gist for the specified number of themes and one generic gist for the entire document.

The REQUEST_GIST procedure only creates gists if the setting configuration for the session in which REQUEST_GIST is called supports gist generation.

The parameter pk can be either a single column textkey or a multiple column (composite) textkey. When pk is a composite textkey, you must encode the composite textkey string using the CTX_QUERY.PKENCODE procedure as in the second example above.

Requests are not automatically entered into the Services Queue; each request is cached in memory until the application calls the CTX_LING.SUBMIT procedure.

CTX_LING.SUBMIT explicitly enters all of the cached requests into the Services Queue as a single batch.

All of the linguistic settings that can be specified for Gist-generation also apply to sentence-level Gists/theme summaries when requested. The settings simply act on sentences rather than paragraphs.

For example, the size setting for Gists, which determines the maximum number of paragraphs in a paragraph-level Gist, determines the maximum number of sentences in a sentence-level Gist, when a sentence-level Gist is requested.

See Also:

For more information about the size setting, as well as the other settings that can be specified for Gists and theme summaries, see the help system provided with the ConText System Administration tool.

 


REQUEST_THEMES

The CTX_LING.REQUEST_THEMES procedure generates a list of up to sixteen themes for a document.

Syntax

CTX_LING.REQUEST_THEMES(
                  policy       IN VARCHAR2,
                  pk           IN VARCHAR2, 
                  table        IN VARCHAR2);

policy

Specify the name of the ConText policy for the column.

pk

Specify the primary key (textkey) of the document (row) to be processed. The parameter pk can be a single column textkey or an encoded specification for a multiple column textkey.

table

Specify the table used to store the theme output.

Examples

exec ctx_ling.request_themes('my_pol', 34, 'CTX_THEMES')
begin
ctx_ling.request_themes('doc_pol',
CTX_QUERY.PKENCODE('Jones','Naval Inst Pr','10-1-1970'),
'CTX_THEMES');
end;

Notes

You must call CTX_LING.REQUEST_THEMES procedure once for each document for which you want to generate themes.

The parameter pk can be either a single column textkey or a multiple column textkey. When pk is a composite key, you must encode the composite textkey string using the CTX_QUERY.PKENCODE procedure as in the second example above.

Requests for themes are not automatically entered into the Services Queue; each request is cached in memory pending submission by CTX_LING.SUBMIT.

CTX_LING.SUBMIT explicitly enters all of the cached requests into the Services Queue as a single batch.


SET_COMPLETION_CALLBACK

The CTX_LING.SET_COMPLETION_CALLBACK procedure specifies the user-defined PL/SQL processing routine (usually a procedure) to be called when a ConText server finishes processing a request in the Services Queue.

Syntax

CTX_LING.SET_COMPLETION_CALLBACK(callback_name IN VARCHAR2);

callback_name

Specify the name of the callback procedure. See below for a description of the arguments to the callback_name procedure.

Examples

exec ctx_ling.set_completion_callback('COMP_PROCEDURE')

Notes

A completion callback procedure must be defined before SET_COMPLETION_CALLBACK can be called. The completion callback procedure must accept the following arguments:

Argument   Type   Purpose  

HANDLE  

NUMBER  

Specify the internal identifier for the request, as returned by SUBMIT.  

STATUS  

VARCHAR2  

Specify the status of the request: SUCCESS or ERROR.  

ERRCODE  

VARCHAR2  

Specify the code for the error (NULL if request processed successfully).  

Control is passed to the SET_COMPLETION_CALLBACK procedure at the completion of a linguistic request. It can log errors or otherwise notify the application when a request has finished processing. This can be particularly useful for a large job that is run asynchronously in batch mode.

To call a procedure specifically for requests that terminate with errors, use CTX_LING. SET_ERROR_CALLBACK.


SET_ERROR_CALLBACK

The CTX_LING.SET_ERROR_CALLBACK procedure specifies the user-defined PL/SQL processing routine (usually a procedure) to be called when a ConText server encounters an error while processing a linguistic request.

Syntax

CTX_LING.SET_ERROR_CALLBACK(callback_name IN VARCHAR2);

callback_name

Specify the name of the callback procedure to be used when an error occurs.

Examples

exec ctx_ling.set_error_callback('ERROR_PROCEDURE')

Notes

An error callback procedure must be defined before SET_ERROR_CALLBACK can be called. The error callback procedure must accept the following arguments:

Argument   Type   Purpose  

HANDLE  

NUMBER  

Specify the internal identifier for the request, as returned by SUBMIT  

ERRCODE  

VARCHAR2  

Specify the code for the error.  

Control is passed to the SET_ERROR_CALLBACK procedure at the completion of a linguistic request. The procedure can be used to log errors or otherwise notify the application when a request has finished processing. This can be particularly useful for a large job that is run asynchronously in batch mode.

To call a procedures for both completed task processing and error processing, use SET_COMPLETION_CALLBACK.


SET_FULL_THEMES

Use this procedure to enable the writing of theme hierarchy information to the theme table. ConText writes the theme hierarchy information when you call REQUEST_THEMES. (By default, ConText writes only theme phrase information to the theme table when you call REQUEST_THEMES.)

Syntax

CTX_LING.SET_FULL_THEMES (theme_mode  IN BOOLEAN DEFAULT TRUE);

theme_mode

Specify TRUE for ConText to write theme hierarchy information to the THEME column of the theme table.

Specify FALSE to disable the writing of theme hierarchy information to the THEME column of the theme table.

Notes

At the start of a session, the theme_mode flag is FALSE.

Calling SET_FULL_THEMES without an argument is the same as calling this procedure with theme_mode set to TRUE.

You can check whether the writing of theme hierarchy information is turned on using GET_FULL_THEMES.


SET_LOG_PARSE

The CTX_LING.SET_LOG_PARSE procedure enables/disables logging of linguistic parsing information for a session.

Syntax

CTX_LING.SET_LOG_PARSE(log_mode BOOLEAN DEFAULT TRUE);

log_mode

Specify whether to write parse information to a log file during linguistic processing in a session. The default is TRUE.

Examples

exec ctx_ling.set_log_parse(TRUE)

Notes

At start-up of a ConText server, parse information logging is disabled.

Once logging is enabled, it stays enabled for the session until it is explicitly disabled.

When logging is enabled, the text of the document being parsed and the paragraph offset information used by ConText to separate the document into its constituent paragraphs is written to the log file specified when the ConText server is started.

The log provides information about the input text used to generate linguistic output and can be used for debugging the system. The parse information is especially useful for debugging linguistic output for formatted documents from which the text is extracted before it is processed.

However, due to the large amount of information generated by ConText and written to the log file, parse logging may affect performance considerably. For this reason, you should only enable parse logging if you encounter problems with linguistics.


SET_SETTINGS_LABEL

Use the CTX_LING.SET_SETTINGS_LABEL procedure to change the linguistic settings for a database session.

Syntax

CTX_LING.SET_SETTINGS_LABEL(settings_label  IN VARCHAR2);

settings_label

Specify the label for the setting configuration used for the session. You can use one of the following predefined settings or one that you create with the administration tool:

Label   Description  

GENERIC  

Use this configuration to analyze mixed-case English text to produce theme and Gist output.

This configuration is the default.  

SA  

This configuration is identical to GENERIC, except it converts all-uppercase or all lower-case text to mixed case before processing text to produce theme or Gist output.

This setting should be used only when text is all-uppercase or all-lowercase, or where you are not sure of the accuracy of the case.  

Examples

exec ctx_ling.set_settings_label('SA')

Notes

At start-up of a ConText server, the GENERIC default setting configuration is active.

The settingspecified by SET_SETTINGS_LABEL is active for the entire session or until you call SET_SETTINGS_LABEL with a new setting configuration. In addition, the specified setting is active only for your current session; settings specified for your session have no effect on the server setting.

You can specify any predefined ConText setting configuration or any custom setting configuration. Define custom setting configurations with the Administration Tool provided with ConText Workbench.

When your text is all upper-case or all lower-case and you use the SA setting to convert the text to mixed-case, Oracle Corpration does not recommend creating theme indexes or issuing theme queries. Creating theme indexes with the SA linguistic setting does not produce consistent results.


SUBMIT

The CTX_LING.SUBMIT procedure creates a single request (row) in the Services Queue for all linguistic requests cached in memory for a single row (identified by PK) and returns a handle for the request.

Syntax

CTX_LING.SUBMIT(
              wait         IN NUMBER  DEFAULT 0,
              do_commit    IN BOOLEAN DEFAULT TRUE, 
              priority     IN NUMBER  DEFAULT 0)
RETURN NUMBER;

wait

Specify maximum time in seconds to block subsequent requests while ConText server processes request. The default is 0.

do_commit

Specify whether the job request should be committed to the database. The default is TRUE.

priority

Specify the priority for the request. Requests are processed in order of priority from lowest priority to highest priority. The default is 0.

Returns

Handle that identifies the request.

Examples

declare handle number;
begin
handle := ctx_ling.submit(500);
end;

In this example, procedures to create one or more gists and/or themes have already been executed and the requests cached in memory. The SUBMIT procedure enters the request(s) into the Services Queue and returns a handle. It this case, it also prevents the queue from accepting other submissions from the same requestor for 500 seconds.

Notes

SUBMIT does not cache requests for multiple documents nor for documents in different columns. Only requests for a single document at a time can be submitted.

If more than one request is queued in memory, SUBMIT processes all of the requests as a single batch job. If the request is a batch job, the ConText server processes each request in the batch in order.

All of the individual requests in the batch must be processed successfully or the ConText server returns an ERROR status for the entire batch. The error message stack returned by the ConText server identifies the request that caused the batch to fail.

If SUBMIT is called from a database trigger, the DO_COMMIT argument must be set to FALSE.

CTX_SVC: Services Queue Administration

The CTX_SVC package contains PL/SQL procedures used to query requests in the Services Queue and to perform administrative tasks on the Queue.

CTX_SVC contains the following stored procedures and functions:

Name   Description  

CANCEL  

Removes a pending request from the Services Queue.  

CANCEL_ALL  

Removes all pending requests from the Services Queue.  

CANCEL_USER  

Removes a pending request from the Services Queue for the current user.  

CLEAR_ALL_ERRORS  

Removes all requests with an error status from the Services Queue.  

CLEAR_ERROR  

Removes a request that produced an error from the Services Queue.  

CLEAR_INDEX_ERRORS  

Removes errored indexing requests from the Services Queue.  

CLEAR_LING_ERRORS  

Removes errored linguistic requests from the Services Queue.  

REQUEST_STATUS  

Returns the status of a request in the Services Queue.  


CANCEL

The CTX_SVC.CANCEL procedure removes a request from the Services Queue, if the request has a status of PENDING.

Syntax

CTX_SVC.CANCEL(request_handle NUMBER);

request_handle

Specify the handle, returned by CTX_LING.SUBMIT, of the service request to remove.

Examples

exec ctx_svc.cancel(3321)

Notes

To cancel requests that have not been entered in the Services Queue, use the CTX_LING.CANCEL procedure.


CANCEL_ALL

The CTX_SVC.CANCEL_ALL procedure removes all requests with a status of PENDING from the Services Queue.

Syntax

CTX_SVC.CANCEL_ALL ;

Examples

execute ctx_svc.cancel_all


CANCEL_USER

The CTX_SVC.CANCEL_USER procedure removes all requests with a status of PENDING for the current user.

Syntax

CTX_SVC.CANCEL_USER ;

Examples

execute ctx_svc.cancel_user


CLEAR_ALL_ERRORS

The CTX_SVC.CLEAR_ALL_ERRORS procedure removes all requests (text indexing, theme indexing, and linguistics) that have a status of ERROR in the Services Queue.

Syntax

CTX_SVC.CLEAR_ALL_ERRORS ;

Examples

execute ctx_svc.clear_all_errors


CLEAR_ERROR

The CTX_SVC.CLEAR_ERROR procedure removes a request with a status of ERROR from the Services Queue.

Syntax

CTX_SVC.CLEAR_ERROR(request_handle  IN NUMBER);

request_handle

Specify the handle, returned by CTX_LING.SUBMIT, of the errored service request that is to be removed.

Examples

exec ctx_svc.clear_error(3321)

Notes

When you call CTX_SVC.CLEAR_ERROR with a 0 for the REQUEST_HANDLE, ConText removes all requests in the Services Queue that have an ERROR status.

You can use CTX_SVC.REQUEST_STATUS to return the status of a request in the Services Queue.


CLEAR_INDEX_ERRORS

The CTX_SVC.CLEAR_INDEX_ERRORS procedure removes all indexing requests (text and theme) that have a status of ERROR in the Services Queue.

Syntax

CTX_SVC.CLEAR_INDEX_ERROR ;

Examples

execute ctx_svc.clear_index_errors


CLEAR_LING_ERRORS

The CTX_SVC.CLEAR_LING_ERRORS procedure removes all linguistic requests that have a status of ERROR in the Services Queue.

Syntax

CTX_SVC.CLEAR_LING_ERROR ;

Examples

execute ctx_svc.clear_ling_errors


REQUEST_STATUS

The CTX_SVC.REQUEST_STATUS function returns the status of a request in the Services Queue.

Syntax

CTX_SVC.REQUEST_STATUS(
                  request_handle   IN   NUMBER,
                  timestamp        OUT  DATE, 
                  errors           OUT  VARCHAR2) 
RETURN VARCHAR2;

request_handle

Specify the handle of the service request, as returned by CTX_LING.SUBMIT.

timestamp

Returns the time at which request was submitted.

errors

Returns the error message stack for the request; message stack is returned only if the status of the request is ERROR.

Returns

Status of the request, which is one of the following:

PENDING

The request has not yet been picked up by a ConText server.

RUNNING

The request is being processed by a ConText server.

ERROR

The request encountered an error (see ERRORS argument).

SUCCESS

The request completed successfully.

Examples

declare status varchar2(10);
declare time date;
declare errors varchar2(60)
begin
status := ctx_svc.request_status(3461,timestamp,errors);
dbms_output.put_line(status,timestamp,substr(errors,1,20));
end;

Notes

Specifying an invalid request handle in REQUEST_HANDLE causes CTX_SVC.REQUEST_STATUS to return a status of SUCCESS.




Prev

Next
Oracle
Copyright © 1997 Oracle Corporation.

All Rights Reserved.

Library

Product

Contents

Index