4.1 Changing Oracle Ultra Search Schema Passwords

There are two Oracle Ultra Search system schemas created during installation: WKSYS and WKPROXY. You can update the schema password in the following way:

For the Oracle Database Release:

After the database is installed, all user schema accounts are locked. To log on as user WKSYS (or WKPROXY), unlock WKSYS (or WKPROXY) by running the following statement as the SYSTEM or SYS database user:

ALTER USER WKSYS ACCOUNT UNLOCK IDENTIFIED BY desired_password;

For the Oracle Application Server or the Oracle Collaboration Suite Release:

After the infrastructure database is installed, all user schema passwords are randomized. To log on as user WKSYS (or WKPROXY), change the WKSYS (or WKPROXY) schema password by following the link Change Schema Password from the Oracle Enterprise Manager Infrastructure page.

4.2 Configuring the Oracle Server for Oracle Ultra Search

The operations described in this section are database administration operations. They can be performed using Oracle Enterprise Manager or SQL*Plus.

4.2.1 Step 1: Tune the Oracle Database

Increase the Size of the Oracle Redo Logs, if necessary

Every instance of an Oracle database has an associated online redo log, which is a set of two or more online log files that record all committed changes made to the database. Online redo logs protect the database in the event of an instance failure. The size of redo log files determines the frequency of redo log file switches. This, in turn, significantly impacts text indexing speed. To reduce the frequency of log file switches, ensure that the redo log files are each 100MB or more.

The following section lists some tips on how to increase the redo log file sizes, if necessary. Enter the statements in the following section with the appropriate Oracle administrator privileges.

A production database should have more log members for each log group, and different storage devices should be used to increase performance and reliability.

Drop the old log files. For each old redo log file, enter the ALTERSYSTEMSWITCHLOGFILE statement until that log file's status is INACTIVE. This is necessary to ensure that Oracle is not using that log file when you try to drop it.

Manually delete the old log files from the file system. For each old redo log file, use the appropriate operating system statement to delete the unwanted log file from the file system.

Increase the Size of the Undo Space

Every Oracle database must have a method of maintaining information that is used to roll back, or undo, changes to the database. Such information consists of records of the actions of transactions, primarily before they are committed. Oracle refers to these records collectively as undo. The undo space created by the Oracle Installer may be too small. Oracle recommends that you use automatic undo management and increase the undo space.

JOB_QUEUE_PROCESSES: Set this to three or higher. (Set it to at least one.) This is needed because the Oracle Ultra Search crawler is launched by scheduling a database job. If this is zero, then no database jobs are run. As a result, any attempts to launch the Oracle Ultra Search crawler fail. Also consider other requirements for job queue processes when you set this value.

For the latest information on initialization parameters relating to Oracle Ultra Search, see the Oracle Ultra Search Readme.

4.2.2 Step 2: Create and Assign the Temporary Tablespace to the CTXSYS User

The starter database created by the Oracle Installer may create a temporary tablespace that is too small. Oracle Ultra Search uses the Oracle Text engine intensively. Therefore, a large temporary tablespace must be created for the Oracle Text system user CTXSYS. If you want greater read and write performance, create the tablespace on raw devices.

When you have created the temporary tablespace, assign it as the temporary tablespace for the CTXSYS user. To do so, you must log on as the SYSTEM or SYS user. Assign the temporary tablespace to the CTXSYS user with the following statement:

For each Oracle Ultra Search instance, you must create a tablespace large enough to contain all data obtained during the crawling and indexing processes. This amount is subject to the amount of data you intend to crawl and index. However, it is often not possible to know in advance how much data you intend to collect. Try to obtain an estimate of the cumulative size of all data you want to crawl.

If you cannot estimate the size, then try to allocate as much space as possible. If you run out of disk space, then Oracle Ultra Search is able to resume crawling after you add more datafiles to the instance tablespace.

Pay attention to the STORAGE clause in your CREATETABLESPACE statement. The amount of data to be stored in the tablespace can be very large. This can cause the Oracle server to progressively allocate many new extents when more storage space is needed. If the extent management clause specifies that each new extent is to be larger than the previous extent (that is, the PCTINCREASE setting is nonzero), then you could encounter the situation where the next extent that the Oracle server wants to allocate is larger than what is available. In such a situation, indexing halts until new extents can be added to the tablespace.

To mitigate this problem, certain instance-specific tables have explicit storage parameter settings. The initial extent size, next extent size, and PCTINCREASE setting are defined for these tables. These tables are created when a new instance is created. The tables and their storage clause settings are as follows:

Oracle Ultra Search uses Oracle's fine grained access control feature to support multiple Oracle Ultra Search instances within one physical database. This is especially useful for large organizations or application service providers (ASPs) that want to host multiple disjoint search indexes within one installation of Oracle.

Note:

Oracle Ultra Search requires that each Oracle Ultra Search virtual instance belong to a unique database user. Therefore, as part of the installation process, you must create one or more new database users to own all data for your Oracle Ultra Search instance.

If you intend to create more than one database instance, you should also create multiple user tablespaces: one for each user.

You must grant the WKUSER role to database users hosting new Oracle Ultra Search instances.

and default_tbs = default tablespace for the Oracle Ultra Search instance created in step 3

and temporary_tbs = temporary tablespace created in step 2

GRANT WKUSER TO username;

After these steps are completed, WKSYS or an Oracle Ultra Search super-user can create an Oracle Ultra Search instance on this user schema.

If you want this user to have the general administrative privilege or the super-user privilege, then log on as an Oracle Ultra Search super-user or WKSYS and click go to the Users page in the administration tool to grant the appropriate privilege.

4.2.5 Step 5: Alter the Index Preferences

This step is optional.

An empty index is created when an Oracle Ultra Search instance is created. The existing index preferences, such as language-specific parameters, are defined in the $ORACLE_HOME/ultrasearch/admin/wk0pref.sql file.

You can modify these preferences so that all new Oracle Ultra Search instances use the modified preferences, or you can alter the index using your own preferences immediately after an instance is created. Alter the index using SQL.

Note:

The crawler transforms all documents into HTML files with binary document filtering before indexing begins.

4.3 Managing Stoplists

Every Oracle Ultra Search instance has a stoplist associated with it. A stoplist is a list of words that are ignored during the indexing process. These words are known as stopwords. Stopwords are not indexed because they are deemed not useful, or even disruptive, to the performance and accuracy of indexing.

4.3.1 Default Oracle Ultra Search Stoplist

During the installation process, a default stoplist is created for the Oracle Ultra Search product. Subsequently, when an Oracle Ultra Search instance is created, a copy of the default stoplist is created for the Oracle Ultra Search instance.

The default stoplist is created under the WKSYS schema. The default stoplist name is wk_stoplist. (This list is defined in the file $ORACLE_HOME/ultrasearch/admin/wk0pref.sql, which is run at installation).

4.3.2 Modifying Instance Stoplists

Modify the default stoplist by adding or removing stopwords from it. However, remember that these modifications do not affect existing Oracle Ultra Search instances. They only affect Oracle Ultra Search instances that are created after the modifications are made.

Modifying instance stoplists should be done as a last resort. Use one of the following methods:

Modify the default stoplist before creating the instance.

Replace the instance stoplist immediately after creating the instance.

Replacing the instance stoplist immediately after creating the instance affects only that instance. You must first create a user-defined stoplist.

In both cases, the result is that the Oracle Ultra Search instance stoplist is modified and defined before initial crawling. This means that all documents collected by the Oracle Ultra Search crawler are evaluated against the correct stoplist. It is important to modify the stoplist before initial crawling to avoid having to recrawl all documents again.

4.3.2.1 Modifying Instance Stoplists Before Initial Crawling

Modify the default stoplist before creating the instance:

For example, to add the stopword "web" to the default stoplist, log on as user WKSYS in SQL*Plus, and run the following statement:

EXEC ctx_ddl.add_stopword('wk_stoplist','web');

To remove the stopword "web" from the default stoplist, log on as user WKSYS in SQL*Plus, and run the following statement:

EXEC ctx_ddl.remove_stopword('wk_stoplist','web');

Subsequently, the stoplists of all new instances reflect the modifications made to the default stoplist.

Replace the instance stoplist immediately after creating the instance:

You must create a new user-defined stoplist. Log on as the owner of the instance in SQL*Plus, and run the following statements:

BEGIN ctx_ddl.create_stoplist('example_stoplist');
ctx_ddl.add_stopword('example_stoplist','example_stopword');
... (add more stopwords by repeated the previous
line with new stopwords) ...
END;
/

To replace an instance stoplist with this new stoplist, log on as the owner of the instance in SQL*Plus, and run the following statement:

4.3.2.2 Modifying Instance Stoplists After Initial Crawling

If necessary, alter an instance stoplist after initial crawling with one of the following methods:

Add stopwords to the instance stoplist:

Choosing to add stopwords to the instance stoplist does not affect any documents already crawled or indexed. This operation is not an expensive operation.

For example, to add the stopword "web" to the instance stoplist, log on as the owner of the instance in SQL*Plus, and run the following statement:

ALTER INDEX wk$doc_path_idx rebuild parameters('add stopword web');

Replace the instance stoplist after initial crawling:

Defining a new stoplist and replacing the instance stoplist with it invalidates the entire index. If you choose this method, you must force the Oracle Ultra Search crawler to recrawl all documents in the index. To do this, click Process All Documents in the Edit Schedule page. This is a very expensive operation. Therefore, this option should be the last resort.

4.4 Upgrading Oracle Ultra Search

Oracle Ultra Search is shipped with the Oracle Database, the Oracle Application Server, and the Oracle Collaboration Suite. To upgrade Oracle Ultra Search from a previous release to the most recent release, you must apply different procedures based on the product you are using.

4.4.1 Pre-Upgrade Steps

Before you upgrade, log on to the Oracle Ultra Search administration tool. Stop and disable all crawler synchronization schedules in every Oracle Ultra Search instance. You can enable all crawler synchronization schedules after the upgrade. See "Schedules Page" for details on how to stop and disable the synchronization schedule.

4.4.2 Upgrading Oracle Ultra Search Shipped with Oracle Database

To upgrade Oracle Ultra Search shipped with the Oracle Database release, do the following:

Run the Oracle Ultra Search backend upgrade. This includes upgrading the Oracle Ultra Search database schemas and server files. Install the new Oracle software, and run Oracle Database Upgrade Assistant to upgrade the database and Oracle Ultra Search component to the new release. See the Oracle Database Upgrade Guide for details.

If you are using the Oracle Collaboration Suite release 1 and want to upgrade to the most recent Oracle Collaboration release, install the latest Oracle Collaboration Suite release and use the Oracle Collaboration Suite Upgrade Assistant to upgrade both the Oracle Ultra Search middle tier and backend. See the Oracle Collaboration Suite installation guide that is appropriate for your platform.If you are using Oracle Ultra Search 9.0.2 (shipped with Oracle Application Sever release) or Oracle Ultra Search 1.0.3 or 9.2 (shipped with Oracle Database release) and want to upgrade to the most recent Oracle Collaboration release, then perform the following upgrade procedures:

Upgrade is based on the backend only. Upgrade on the middle tier is not supported. Install the 9.0.3 middle tier in a separate Oracle home.

4.4.5.1 Upgrade from Oracle Ultra Search 1.0.3 to 9.0.3

Upgrading from Oracle Ultra Search 1.0.3 (Oracle9i Database 9.0.1)to 9.0.3 requires running the upgrade script and performing some manual steps. The Oracle Ultra Search upgrade script first verifies the version of the current system, then upgrades the system and migrates user data. User data includes all dictionary and table data, such as information about the metadata, data sources, mappings, crawler schedules, authentication, and query statistics. All crawler schedules and jobs created in the older version are disabled before data and system migration. When migration is complete, the system administrator should re-activate the crawling schedule to re-index the document. You do not need to reconfigure the system or re-enter any data. You can still query documents that were crawled and indexed by the previous version.

4.4.5.1.1 Oracle Ultra Search Migration Approaches

There are two approaches to migrate user data: the in-place approach and the ETL (extract-transform-load) approach. With the in-place approach, the current ORACLE_HOME is used. With the ETL approach, a new ORACLE_HOME is created.

4.4.5.1.2 Oracle Ultra Search In-Place Migration

In-place migration upgrades existing configurations and user data to the latest Oracle Ultra Search release. Upgraded files are left in place, and the source installation is modified. The benefit to this approach is that it might conserve disk space. With the in-place approach, data migration involves the following six steps:

Back up user data

Deinstall previous database objects

Install new database objects

Re-create user instances

Restore data

Rebuild index

Use the SQL script wk0upgrade.sql to run the in-place migration steps one through five, listed in the preceding section. The script is located in the %ULTRASEARCH_HOME%/admin/ directory. It requires the following input parameters:

SYSPW: password of the user SYS

WKSYSPW: password of the user WKSYS

HOST: database host computer

PORT: database port number

ORACLE_SID: database SID

WK_TABLESPACE: tablespace for Oracle Ultra Search

WK_TEMPTABLESPACE: temporary tablespace

CONN_STRING: database connect string

ORACLE_HOME: the path of Oracle home

JAVA_EXE_PATH: Java executable file path

PATH_SEPARATOR: Java classpath separator; use ':' for UNIX or ';' for Windows

The sixth step requires the system administrator to re-activate all crawling schedules through the Oracle Ultra Search administration tool.

4.4.5.1.3 Oracle Ultra Search Extract-Transform-Load Migration

Extract-transform-load (ETL) migration extracts the useful subset of configuration data from the source installation, transforms necessary data, and loads or merges this data into a new installation of Oracle Ultra Search. This approach might require more disk space, but it offers the following benefits:

No destabilization of the source installation

Stability of target installation

No installer integration requirement

With the ETL approach, data migration involves the following five steps:

Install the new system (for example, 9.0.3) in a new ORACLE_HOME

Re-create user instance schemas and related database objects

Re-create user instances

Restore data

Rebuild index

The first two steps in the ETL approach must be done manually:

Install Oracle Ultra Search 9.0.3 in a separate ORACLE_HOME, either on the same computer or on a different computer. If the new 9.0.3 system is installed in the same computer as the old 9.0.1 system, then the database listener port number should be configured to a different number than the old 9.0.1 database. This lets both the old and the new database run at the same time.

Re-create all Oracle Ultra Search 1.0.3 user instance schemas in the new database. Also, for each table data source created in Oracle Ultra Search 1.0.3, if the base table is located in the local database, then you must copy the base table to the new database. If the table data source base table is set to a remote database table, then you must re-create the database link from the new database to the remote database.

Use the SQL script wk0migrate.sql to run the ETL migration steps three and four. The script is located in the %ULTRASEARCH_HOME%/admin/ directory. It requires the following input parameters:

The fifth step requires the system administrator to re-activate all crawling schedules through the Oracle Ultra Search administration tool.

Note:

The upgrade script does not roll back the Oracle Ultra Search system to the old version if an unexpected error occurs, such as a power failure or system failure.

For in-place migration, back up the database before starting migration. For ETL migration, because all previous data is kept, you can switch back to the previous (for example, 9.0.1) system

4.4.5.1.4 Oracle Ultra Search Migration Logs

The upgrade script provides log files to show which actions the migration has taken. The upgrade script writes the following contents to the log file:

The current execution step

Any error message raised from the stored procedures

Number of data records backup

Number of data records copied or migrated

For in-place migration, the wk0upgrade.sql script writes the execution logs to the file wk0upgrade.log in the %ULTRASEARCH_HOME%/admin/ directory.

For ETL migration, the wk0migrate.sql script writes the execution logs to the file wk0migrate.log in the %ULTRASEARCH_HOME%/admin/ directory.

4.4.5.2 Upgrade from Oracle Ultra Search 9.0.2 to 9.0.3

To upgrade Oracle Ultra Search 9.0.2 to 9.0.3, perform the following steps:

Copy all Oracle Ultra Search 9.0.2 files, recursively, under the Oracle Application Server 9.0.2 infrastructure tier $ORACLE_HOME/ultrasearch/ to a different directory in case if you need to downgrade to 9.0.2 later.

Log on to the Oracle Ultra Search 9.0.2 administration tool. Stop and disable all crawler synchronization schedules in every Oracle Ultra Search instance.

4.4.5.3 Upgrade from Oracle Ultra Search 9.2 to 9.0.3

4.5 Configuring the Query Application

The Oracle Ultra Search query application is deployed automatically with the Oracle Ultra Search installation. However, because Oracle Ultra Search allows multiple instances using different schema users, the query application is not configured for how to connect to the database automatically. Database connection is configured by creating a data source in OC4J (not to be confused with an Oracle Ultra Search data source). This is done by editing the data-sources.xml file.

4.5.1 Step 1: Edit the data-sources.xml File

The data-sources.xml file is the OC4J connection management facility. The Oracle Ultra Search query application uses OC4J to connect to the database. This is different from the administration tool, because the query user is not a database user; therefore it does not know the database login password.

By editing data-sources.xml, the database user and password information is configured with OC4J. The Oracle Ultra Search query application finds the data source by using its location, "jdbc/UltraSearchPooledDS".

Oracle Ultra Search lets multiple instances use different schema users, so multiple query applications can co-exist on the same database.

Each query application requires its database connection information to be defined with data-sources.xml. They must be defined to have different location values, such as "jdbc/UltraSearchPooledDS1", "jdbc/UltraSearchPooledDS2", and so on. Correspondingly, the query application must be deployed multiple times in OC4J.

Finally, each application deployment must be configured to use the correct entry in data-sources.xml. This is done by editing the JSP source for query. For the complete search application, edit common_customize_instance.jsp and edit the following line to use the correct location value: