1 package ctx_report authid current_user as
2
3 -- constants
4 FMT_TEXT constant varchar2(10) := 'TEXT';
5 FMT_XML constant varchar2(10) := 'XML';
6
7 -- type declaration
8 type query_record is record(times number, query varchar2(4000));
9 type query_table is table of query_record index by binary_integer;
10
11
12 /*--------------------------- query_log_summary -----------------------------*/
13 /*
14 NAME
15 query_log_summary - get the most(least) frequent queries from the query log file
16
17 DESCRIPTION
18 This version of query_summary returns the results into a PL/SQL table
19
20 ARGUMENTS
21 logfile (IN) the name of query log file
22 indexname (IN) the name of the context index, the default is null which
23 will return result for all context indexes
24 result_table (IN OUT) query_table to which to write the result
25 row_num (IN) the number of queries you want
26 most_freq (IN) whether you want the most frequent or least frequent quries
27
28 */
29 procedure query_log_summary(
30 logfile in varchar2,
31 indexname in varchar2 default null,
32 result_table in out nocopy query_table,
33 row_num in number default 50,
34 most_freq in boolean default true,
35 has_hit in boolean default true
36 );
37
38
39 /*--------------------------- describe_index --------------------------------*/
40 /*
41 NAME
42 describe_index
43
44 DESCRIPTION
45 create a report describing the index. This includes the settings of
46 the index meta-data, the indexing objects used, the settings of the
47 attributes of the objects, and index partition descriptions, if any
48
49 ARGUMENTS
50 index_name (IN) the name of the index to describe
51 report (IN OUT) CLOB locator to which to write the report
52 report_format (IN) report format
53 NOTES
54 if report is NULL, a session-duration temporary CLOB will be created
55 and returned. It is the caller's responsibility to free this temporary
56 CLOB as needed.
57
58 report clob will be truncated before report is generated, so any
59 existing contents will be overwritten by this call
60 */
61 procedure describe_index(
62 index_name in varchar2,
63 report in out nocopy clob,
64 report_format in varchar2 DEFAULT FMT_TEXT
65 );
66
67 function describe_index(
68 index_name in varchar2,
69 report_format in varchar2 DEFAULT FMT_TEXT
70 ) return clob;
71
72 /*--------------------------- describe_policy -------------------------------*/
73 /*
74 NAME
75 describe_policy
76
77 DESCRIPTION
78 create a report describing the policy. This includes the settings of
79 the policy meta-data, the indexing objects used, the settings of the
80 attributes of the objects.
81
82 ARGUMENTS
83 policy_name (IN) the name of the policy to describe
84 report (IN OUT) CLOB locator to which to write the report
85 report_format (IN) report format
86 NOTES
87 if report is NULL, a session-duration temporary CLOB will be created
88 and returned. It is the caller's responsibility to free this temporary
89 CLOB as needed.
90
91 report clob will be truncated before report is generated, so any
92 existing contents will be overwritten by this call
93 */
94 procedure describe_policy(
95 policy_name in varchar2,
96 report in out nocopy clob,
97 report_format in varchar2 DEFAULT FMT_TEXT
98 );
99
100 function describe_policy(
101 policy_name in varchar2,
102 report_format in varchar2 DEFAULT FMT_TEXT
103 ) return clob;
104
105 /*-------------------------- create_index_script ----------------------------*/
106 /*
107 NAME
108 create_index_script
109
110 DESCRIPTION
111 create a SQL*Plus script which will create a text index that duplicates
112 the named text index.
113
114 ARGUMENTS
115 index_name (IN) the name of the index
116 report (IN OUT) CLOB locator to which to write the script
117 prefname_prefix (IN) optional prefix to use for preference names
118
119 NOTES
120 the created script will include creation of preferences identical to
121 those used in the named text index
122
123 if report is NULL, a session-duration temporary CLOB will be created
124 and returned. It is the caller's responsibility to free this temporary
125 CLOB as needed.
126
127 report clob will be truncated before report is generated, so any
128 existing contents will be overwritten by this call
129
130 if prefname_prefix is omitted or NULL, index name will be used
131 prefname_prefix follows index length restrictions
132 */
133 procedure create_index_script(
134 index_name in varchar2,
135 report in out nocopy clob,
136 prefname_prefix in varchar2 default null
137 );
138
139 function create_index_script(
140 index_name in varchar2,
141 prefname_prefix in varchar2 default null
142 ) return clob;
143
144 /*-------------------------- create_policy_script ---------------------------*/
145 /*
146 NAME
147 create_policy_script
148
149 DESCRIPTION
150 create a SQL*Plus script which will create a text policy that duplicates
151 the named text policy.
152
153 ARGUMENTS
154 policy_name (IN) the name of the policy
155 report (IN OUT) CLOB locator to which to write the script
156 prefname_prefix (IN) optional prefix to use for preference names
157
158 NOTES
159 the created script will include creation of preferences identical to
160 those used in the named text policy
161
162 if report is NULL, a session-duration temporary CLOB will be created
163 and returned. It is the caller's responsibility to free this temporary
164 CLOB as needed.
165
166 report clob will be truncated before report is generated, so any
167 existing contents will be overwritten by this call
168
169 if prefname_prefix is omitted or NULL, policy name will be used
170 prefname_prefix follows policy length restrictions
171 */
172 procedure create_policy_script(
173 policy_name in varchar2,
174 report in out nocopy clob,
175 prefname_prefix in varchar2 default null
176 );
177
178 function create_policy_script(
179 policy_name in varchar2,
180 prefname_prefix in varchar2 default null
181 ) return clob;
182
183
184 /*--------------------------- index_size --------------------------------*/
185 /*
186 NAME
187 index_size
188
189 DESCRIPTION
190 create a report showing the internal objects of the text index or
191 text index partition, and their tablespaces, allocated, and used sizes
192
193 ARGUMENTS
194 index_name (IN) the name of the index to describe
195 report (IN OUT) CLOB locator to which to write the report
196 part_name (IN) the name of the index partition (optional)
197 report_format (IN) report format
198 NOTES
199 if part_name is NULL, and the index is a local partitioned text index,
200 then all objects of all partitions will be displayed. If part_name is
201 provided, then only the objects of a particular partition will be
202 displayed.
203
204 if report is NULL, a session-duration temporary CLOB will be created
205 and returned. It is the caller's responsibility to free this temporary
206 CLOB as needed.
207
208 report clob will be truncated before report is generated, so any
209 existing contents will be overwritten by this call
210 */
211 procedure index_size(
212 index_name in varchar2,
213 report in out nocopy clob,
214 part_name in varchar2 default null,
215 report_format in varchar2 DEFAULT FMT_TEXT
216 );
217
218 function index_size(
219 index_name in varchar2,
220 part_name in varchar2 default null,
221 report_format in varchar2 DEFAULT FMT_TEXT
222 ) return clob;
223
224 /*--------------------------- index_stats --------------------------------*/
225 /*
226 NAME
227 index_stats
228
229 DESCRIPTION
230 create a report showing various calculated statistics about the text
231 index
232
233 ARGUMENTS
234 index_name (IN) the name of the index to describe
235 report (IN OUT) CLOB locator to which to write the report
236 part_name (IN) the name of the index partition
237 frag_stats (IN) calculate fragmentation statistics?
238 list_size (IN) number of elements in each compiled list
239 report_format (IN) report format
240 stat_type (IN) Specify teh estimated query stats to output
241 NOTES
242 this procedure will fully scan the text index tables, so it may take
243 a long time to run for large indexes
244
245 if the index is a local partitioned index, then part_name MUST be
246 provided. INDEX_STATS will calculate the statistics for that
247 index partition.
248
249 if report is NULL, a session-duration temporary CLOB will be created
250 and returned. It is the caller's responsibility to free this temporary
251 CLOB as needed.
252
253 report clob will be truncated before report is generated, so any
254 existing contents will be overwritten by this call
255
256 if frag_stats is FALSE, the report will not show any statistics
257 relating to size of index data. However, the operation should
258 take less time and resources to calculate the token statistics.
259
260 list_size has a maximum value of 1000
261
262 index_stats will create and use a session-duration temporary
263 table, which will be created in CTXSYS temp tablespace.
264 */
265 procedure index_stats(
266 index_name in varchar2,
267 report in out nocopy clob,
268 part_name in varchar2 default null,
269 frag_stats in boolean default TRUE,
270 list_size in number default 100,
271 report_format in varchar2 DEFAULT FMT_TEXT,
272 stat_type in varchar2 DEFAULT NULL
273 );
274
275 /*--------------------------- token_info --------------------------------*/
276 /*
277 NAME
278 token_info
279
280 DESCRIPTION
281 create a report showing the information for a token, decoded
282
283 ARGUMENTS
284 index_name (IN) the name of the index
285 report (IN OUT) CLOB locator to which to write the report
286 token (IN) the token text
287 token_type (IN) the token type
288 part_name (IN) the name of the index partition
289 raw_info (IN) include a hex dump of the index data
290 decoded_info (IN) decode and include docid and offset data
291 resolve_docids (IN) resolve docids to rowids?
292 report_format (IN) report format
293 NOTES
294 this procedure will fully scan the info for a token, so it may take a
295 long time to run for really large tokens.
296
297 if the index is a local partitioned index, then part_name MUST be
298 provided. TOKEN_INFO will apply to just that index partition.
299
300 if report is NULL, a session-duration temporary CLOB will be created
301 and returned. It is the caller's responsibility to free this temporary
302 CLOB as needed.
303
304 report clob will be truncated before report is generated, so any
305 existing contents will be overwritten by this call
306
307 token may be case-sensitive, depending on the passed-in token type.
308 THEME, ZONE, ATTR, PATH, and PATH ATTR tokens are case-sensitive.
309 Everything else gets passed through the lexer, so if the index's
310 lexer is case-sensitive, the token input is case-sensitive.
311
312 if raw_info is TRUE, the report will include a hex dump of the
313 raw data in the token_info column
314
315 if decoded_info is FALSE, ctx_report will not attempt to decode the
316 token information. This is useful when you just want a dump of data.
317
318 To facilitate inline invocation, the boolean arguments are varchar2
319 in the function variant. You can pass in 'Y', 'N', 'YES', 'NO', 'T', 'F',
320 'TRUE', or 'FALSE'
321
322 */
323 procedure token_info(
324 index_name in varchar2,
325 report in out nocopy clob,
326 token in varchar2,
327 token_type in number,
328 part_name in varchar2 default null,
329 raw_info in boolean default FALSE,
330 decoded_info in boolean default TRUE,
331 report_format in varchar2 DEFAULT FMT_TEXT
332 );
333
334 function token_info(
335 index_name in varchar2,
336 token in varchar2,
337 token_type in number,
338 part_name in varchar2 default null,
339 raw_info in varchar2 default 'N',
340 decoded_info in varchar2 default 'Y',
341 report_format in varchar2 DEFAULT FMT_TEXT
342 ) return clob;
343
344 function offset_info(
345 index_name in varchar2,
346 docid in varchar2,
347 token_type in number,
348 part_name in varchar2 default null,
349 raw_info in varchar2 default 'N',
350 decoded_info in varchar2 default 'Y',
351 report_format in varchar2 DEFAULT FMT_TEXT
352 ) return clob;
353
354 /*--------------------------- token_type --------------------------------*/
355 /*
356 NAME
357 token_type
358
359 DESCRIPTION
360 this is a helper function which translates an English name into a
361 numeric token type. This is suitable for use with token_info,
362 or any other CTX API which takes in a token_type.
363
364 ARGUMENTS
365 index_name (IN) the name of the index
366 type_name (IN) an English name for token_type
367
368 NOTES
369 the following is legal input. All input is case-insensitive.
370
371 input meaning type returned
372 ------------------- ----------------------------------- -------------
373 TEXT normal text token 0
377 ATTR SEC attribute section 5
374 THEME theme token 1
375 ZONE SEC zone section 2
376 ATTR TEXT text that occurs in an attribute 4
378 PREFIX prefix token 6
379 PATH SEC path section 7
380 PATH ATTR path attribute section 8
381 STEM stem form token 9
382 ATTR TEXT PREFIX prefix token occuring in attribute 604
383 ATTR TEXT STEM stem token occuring in attribute 904
384 FIELD <name> TEXT text token in field section <name> 16-79
385 FIELD <name> PREFIX prefix token in field section <name> 616-916
386 FIELD <name> STEM stem token in field section <name> 916-979
387 NDATA <name> token in ndata section <name> 200-299
388 MVDATA <name> mvdata value in mvdata section <name> 300-399
389 MDATA <name> mdata value in mdata section <name> 400-499
390
391 example:
392
393 typenum := ctx_report.token_type('myindex', 'field author text');
394
395 For FIELD types, the index meta-data needs to be read, so if you are
396 going to be calling this a lot for such things, you might want to
397 consider caching the values in local variables rather than calling
398 token_type over and over again.
399
400 The constant types (0 - 9) also have constants in this package defined.
401 */
402 function token_type(
403 index_name in varchar2,
404 type_name in varchar2
405 ) return number;
406
407 TOKEN_TYPE_TEXT constant number := 0;
408 TOKEN_TYPE_THEME constant number := 1;
409 TOKEN_TYPE_ZONE_SEC constant number := 2;
410 TOKEN_TYPE_ATTR_TEXT constant number := 4;
411 TOKEN_TYPE_ATTR_SEC constant number := 5;
412 TOKEN_TYPE_PREFIX constant number := 6;
413 TOKEN_TYPE_PATH_SEC constant number := 7;
414 TOKEN_TYPE_PATH_ATTR constant number := 8;
415 TOKEN_TYPE_STEM constant number := 9;
416 TOKEN_TYPE_ATTR_TXT_PFIX constant number := 604;
417 TOKEN_TYPE_ATTR_TXT_STEM constant number := 904;
418
419 /*--------------------------- validate_index -------------------------------*/
420 /* validate_index - write corrupt tokens to log file */
421 procedure validate_index(index_name in varchar2,
422 part_name in varchar2 default null);
423
424 /*--------------------------- validate_mvdata ------------------------------*/
425 /* validate_mvdata - Validate mvdata mappings in $I and also return them to
426 * the user
427 */
428 function validate_mvdata(
429 index_name in varchar2,
430 token in varchar2,
431 token_type in number,
432 part_name in varchar2 default null
433 ) return clob;
434
435 end ctx_report;
[Home] [Help]