This chapter provides reference information on PL/SQL APIs available for use with Oracle Ultra Search. The APIs are grouped as follows:
The following tables show the contents of each API group.
Table 11-1 shows the Instance-Related APIs.
Table 11-1 Instance-Related APIs
Name | Function |
---|---|
CREATE_INSTANCE | create an Oracle Ultra Search instance |
DROP_INSTANCE | drop an Oracle Ultra Search instance |
GRANT_ADMIN | grant instance administrator privileges |
REVOKE_ADMIN | revoke instance administrator privileges |
SET_INSTANCE | operate on an Oracle Ultra Search instance |
Table 11-2 shows the Schedule-Related APIs.
Table 11-2 Schedule-Related APIs
Name | Function |
---|---|
CREATE_SCHEDULE | create a crawler schedule |
DROP_SCHEDULE | drop a crawler schedule |
INTERVAL | generate a schedule interval string |
SET_SCHEDULE | run, resume, or stop a schedule |
UPDATE_SCHEDULE | update a crawler schedule |
Table 11-3 shows the Crawler Configuration APIs.
Table 11-3 Crawler Configuration APIs
Name | Function |
---|---|
IS_ADMIN_READONLY | check if a crawler configuration setting is read-only |
SET_ADMIN_READONLY | make a read-only crawler configuration |
UPDATE_CRAWLER_CONFIG | update crawler configurations |
This section provides reference information for using the instance-related APIs.
Use this procedure to create an Oracle Ultra Search instance.
OUS_ADM.CREATE_INSTANCE( inst_name IN VARCHAR2, schema_name IN VARCHAR2, password IN VARCHAR2 DEFAULT NULL, lexer IN VARCHAR2 DEFAULT NULL, stop_list IN VARCHAR2 DEFAULT NULL, data_store IN VARCHAR2 DEFAULT NULL, snapshot IN NUMBER DEFAULT ous_adm.NO, );
The name of the instance.
The name of the schema.
The password for the schema.
The Oracle Text index lexer preference.
The Oracle Text index stoplist preference.
The Oracle Text index datastore preference.
If OUS_ADM
is set to YES
, create an instance for the snapshot.
Use this procedure to grant instance administrator privileges to the specified user either for the current instance or all the instances.
OUS_ADM.GRANT_ADMIN ( user_name IN VARCHAR2, user_type IN NUMBER DEFAULT DB_USER, scope IN NUMBER DEFAULT CURRENT_INSTANCE, grant_option IN NUMBER DEFAULT NO_OPTION );
The name of the user to whom the administrator privilege should be assigned.
The user type (OUS_ADM.DB_USER
: database user, OUS_ADM.LDAP_USER
: lightweight single sign-on
user).
The scope of the granting; CURRENT_INSTANCE
or ALL_INSTANCE
.
Options for granting privileges: NO_OPTION
or WITH_GRANT
, which enables the grantee to grant the privilege to other users.
Use this procedure to revoke instance administrator privileges from the specified user.
OUS_ADM.REVOKE_ADMIN ( user_name IN VARCHAR2, user_type IN NUMBER DEFAULT DB_USER, scope IN NUMBER DEFAULT CURRENT_INSTANCE );
The name of the user whose privileges are to be revoked.
The user type (OUS_ADM.DB_USER
: database user, OUS_ADM.LDAP_USER
: lightweight single sign-on
user).
The scope of the granting; CURRENT_INSTANCE
or ALL_INSTANCE
.
Use this procedure to operate on an Oracle Ultra Search instance. Almost all OUS_ADM
APIs require SET_INSTANCE
be called first.
This procedure takes two forms. In the first, you specify the name of the instance to be set.
OUS_ADM.SET_INSTANCE( inst_name IN VARCHAR2 );
The name of the instance to be set.
In the second form, you specify the ID of the instance to be set.
OUS_ADM.SET_INSTANCE( inst_id IN NUMBER );
The ID of the instance to be set.
This section provides reference information for using the schedule related APIs.
Use this procedure to create a crawler schedule. It returns an ID for the schedule.
OUS_ADM.CREATE_SCHEDULE ( name IN VARCHAR2, interval IN VARCHAR2, crawl_mode IN NUMBER DEFAULT REGULAR_CRAWL, recrawl_policy IN NUMBER DEFAUL RECRAWL_WHEN_MODIFIED, crawler_id IN NUMBER DEFAULT LOCAL_CRAWLER ) return number;
The name of the schedule.
The schedule interval. This is a string generated from the OUS_INTERVAL function.
The crawl mode can be REGULAR_CRAWL
, CRAWL_ONLY
, or INDEX_ONLY
.
The recrawl condition can be RECRAWL_WHEN_MODIFIED
or RECRAWL_ON_EVERYTHING
.
The ID of the crawler used to run the schedule. This can be LOCAL_CRAWLER
or the remote crawler ID.
Use this function to generate a schedule interval string.
OUS_ADM.INTERVAL ( type IN NUMBER, frequency IN NUMBER DEFAULT 1, start_hour IN NUMBER DEFAULT 1, start_day IN NUMBER DEFAULT 1 ) return varchar2;
The schedule interval type. This permitted values are defined as package constants: HOURLY
, DAILY
, WEEKLY
, MONTHLY
, and MANUAL
.
The schedule frequency. This depends on the interval type, it can be "every x number of hours/days/weeks/months." Not used for MANUAL
interval type.
The schedule's launching hour, in 24-hour format, where 1 represents 1 AM. Not used for HOURLY
and MANUAL
schedules.
The schedule's start day; this parameter is only used for WEEKLY
and MONTHLY
intervals. The day of the week is specified as 0 through 6, where 0 is Sunday; the day of the month is specified as 1 through 31.)
This specifies an interval of every 5 days starting at 6 PM:
OUS_ADM.INTERVAL(OUS_ADM.DAILY, 5, 18);
This specifies launch-on-demand:
OUS_ADM.INTERVAL(OUS_ADM.MANUAL);
This specifies every 2 weeks on Monday, starting at 6 AM:
OUS_ADM.INTERVAL(type=>OUS_ADM.WEEKLY,frequency=>2,start_day=>2,start_hour=>6);
This specifies every 3 months, starting on the first day of the month at 11 PM:
OUS_ADM.INTERVAL(OUS_ADM.MONTHLY, 3, 23, 1);
Use this procedure to update a crawler schedule.
OUS_ADM.UPDATE_SCHEDULE ( name IN VARCHAR2, operation IN NUMBER, value IN VARCHAR2 DEFAULT null );
The name of the schedule that is to be updated.
The desired update operation.
Some operations may need a value. Possible values include RENAME
, ADD_DS
, REMOVE_DS
, SET_INTERVAL
, CRAWL_MODE
, RECRAWL_POLICY
, and SET_CRAWLER
. Values that are not permitted include ENABLE_SCHEDULE
and DISABLE_SCHEDULE
.
This parameter is context-sensitive to the update operation. It can be a new schedule name (RENAME
), a data source name (ADD_DS
or REMOVE_DS
), an interval string (SET_INTERVAL
), a crawl mode value (CRAWL_MODE
), a recrawl policy (RECRAWL
), or a crawler ID (SET_CRAWLER
).
OUS_ADM.UPDATE_SCHEDULE('marketing site schedule', ous_adm.SET_INTERVAL, OUS_ADM.INTERVAL(ous_adm.HOURLY,3); )
OUS_ADM.UPDATE_SCHEDULE('marketing site schedule', OUS_ADM.RENAME, 'marketing site');
OUS_ADM.UPDATE_SCHEDULE('marketing site', OUS_ADM.ADD_DS, 'marketing primary site');
OUS_ADM.UPDATE_SCHEDULE('marketing site', ous_adm. DISABLE_SCHEDULE);
OUS_ADM.UPDATE_SCHEDULE('marketing site', OUS_ADM.RECRAWL_POLICY, ous_adm.RECRAWL_ON_EVERYTHING);
In this example, 1001
is the ID of a remote crawler:
OUS_ADM.UPDATE_SCHEDULE('marketing site', ous_adm.CRAWLER_ID, 1001);
This section provides reference information for using the crawler configuration APIs.
Use this procedure to prevent a crawler configuration setting from being modified from the administration GUI page. This procedure is useful when a setting, such as the location of a cache directory, should not be controlled by the administration GUI, for example, when employess who manage the server do not manage the Oracle Ultra Search.
OUS_ADM.SET_ADMIN_READONLY ( config_name IN NUMBER, read_only IN NUMBER DEFAULT YES, crawler_id IN NUMBER DEFAULT LOCAL_CRAWLER );
The name of the crawler configuration setting. Possible values are:
Configuration Name | Description |
---|---|
CC_CACHE_DIRECTORY |
crawler cache directory path |
CC_CACHE_SIZE |
size of the cache in megabytes |
CC_CACHE_DELETION |
enable/disable removing cache files after indexing |
CC_LOG_DIRECTORY |
crawler log file location |
Set to YES
to prevent the setting from being modified from the GUI.
The ID of the crawler whose configuration you are modifying. This may be set either to LOCAL_CRAWLER
or the ID of a remote crawler.
Use this function to check whether a crawler configuration setting is read-only or not. IS_ADMIN_READONLY
returns 1 if the configuration is read-only, 0 if it is not.
OUS_ADM.IS_ADMIN_READONLY ( config_name IN NUMBER, crawler_id IN NUMBER DEFAULT LOCAL_CRAWLER ) return number;
The name of the crawler configuration. Possible values are:
Configuration Name | Description |
---|---|
CC_CACHE_DIRECTORY |
crawler cache directory path |
CC_CACHE_SIZE |
size of the cache in megabytes |
CC_CACHE_DELETION |
enable/disable removing cache files after indexing |
CC_LOG_DIRECTORY |
crawler log file location |
The ID of the crawler whose configuration you are checking. This may be set either to LOCAL_CRAWLER
or the ID of a remote crawler.
Use this procedure to update crawler configurations.
OUS_ADM.UPDATE_CRAWLER_CONFIG ( config_name IN NUMBER, config_value IN VARCHAR2 );
The name of the crawler configuration.
The configuration value. Possible values are:
Configuration Name | Description | Value |
---|---|---|
CC_CACHE_DIRECTORY |
crawler cache directory path | any valid directory path |
CC_CACHE_SIZE |
size of the cache in megabytes | any positive integer |
CC_CACHE_DELETION |
enable/disable removing cache files after indexing | OUS_ADM.DELETE_CACHE or OUS_ADM_KEEP_CACHE |
CC_LOG_DIRECTORY |
crawler log file location | any valid directory path |
CC_DATABASE |
connection string to the backend database | any valid JDBC connection string |
CC_PASSWORD |
database connection password for the crawler to connect to the database | database connect password for the schema that owns the instance |
CC_JDBC_DRIVER |
JDBC driver type used by the local crawler | OUS_ADM.THIN_DRIVER or OUS_ADM.OCI_DRIVER |