|Oracle® Ultra Search User's Guide
10g Release 1 (10.1)
Part Number B10731-01
This chapter contains the following topics:
For the Oracle Database Release:
After the database is installed, all user schema accounts are locked. To log on as user
WKPROXY) by running the following statement as the
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
WKPROXY), change the
WKPROXY) schema password by following the link Change Schema Password from the Oracle Enterprise Manager Infrastructure page.
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.
Locate redo log files and determine their sizes:
SELECT v$logfile.member, v$logfile.group#, v$log.status, v$log.bytes FROM v$log, v$logfile WHERE v$log.group# = v$logfile.group#;
Add larger redo log files:
ALTER DATABASE ADD LOGFILE 'redo_log_directory/newredo1.log' size 100m; ALTER DATABASE ADD LOGFILE 'redo_log_directory/newredo2.log' size 100m; ALTER DATABASE ADD LOGFILE 'redo_log_directory/newredo3.log' size 100m;
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
LOGFILE 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.
Then, drop the old redo log file with the following statement:
ALTER DATABASE DROP LOGFILE 'redo_log_directory/redo01.log'; ALTER DATABASE DROP LOGFILE 'redo_log_directory/redo02.log'; ALTER DATABASE DROP LOGFILE 'redo_log_directory/redo03.log';
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.
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.
See Also:Oracle Database Administrator's Guide for details on using automatic undo management
Set the following values in the initialization file:
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.
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
SYS user. Assign the temporary tablespace to the
CTXSYS user with the following statement:
ALTER USER CTXSYS TEMPORARY TABLESPACE new_temporary_tablespace;
See Also:Oracle Database Administrator's Guide for information on how to create a temporary tablespace
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.
Here is an example of how to create a new tablespace:
CREATE TABLESPACE lmtbsb DATAFILE '/u02/oracle/data/lmtbsb01.dbf' SIZE 150M;
Pay attention to the
STORAGE clause in your
TABLESPACE 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:
DR$WK$DOC_PATH_IDX$I (initial extent size 5M, next extent size 50M, PCTINCEASE 1) DR$WK$DOC_PATH_IDX$K (initial extent size 5M, next extent size 50M, PCTINCEASE 1)
If you want greater read and write performance, create the tablespace on raw devices.
Be sure to create a new large tablespace for each Oracle Ultra Search instance user.
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.
See Also:"Users Page"
CREATE USER username IDENTIFIED BY password DEFAULT TABLESPACE default_tbs TEMPORARY TABLESPACE temporary_tbs QUOTA UNLIMITED ON default_tbs;
where username = name of the Oracle Ultra Search instance owner
and password = password of the Oracle Ultra Search instance owner
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.
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
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.
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.
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
sql, which is run at installation).
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.
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.
Modify the default stoplist before creating the instance:
To remove the stopword "web" from the default stoplist, log on as user
WKSYS in SQL*Plus, and run the following statement:
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:
ALTER INDEX wk$doc_path_idx rebuild parameters('replace stoplist example_stoplist');
See Also:"Changing Oracle Ultra Search Schema Passwords" for information about changing the
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.
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.
This section contains the following topics:
See Also:"Oracle Ultra Search Release Information" describes the Oracle Ultra Search release numbering
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.
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.
Follow the steps in "Installing the Oracle Ultra Search Middle Tier on Web Server Hosts" to install the new Oracle Ultra Search middle tier.
To upgrade Oracle Ultra Search shipped with the Oracle Application Server, do the following:
Install the new Oracle Application Server and use Oracle Application Server Upgrade Assistant to upgrade the middle tier. See the Oracle Application Server 10g Upgrading to 10g (9.0.4) section "Upgrading the Middle Tier" for details.
Perform the upgrade on the Oracle Ultra Search schema in the Oracle Application Server Metadata Repository. See the Oracle Application Server 10g Upgrading to 10g (9.0.4) section "Upgrading the Metadata Repository->Executing the Oracle Ultra Search Schema Upgrade Script" 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:
Get the Oracle Collaboration Suite release 1 software and upgrade your Oracle Ultra Search to Oracle Collaboration Suite release 1 first. See section "Upgrading Oracle Ultra Search to Oracle Collaboration Suite Release 1" for details.
Install the latest Oracle Collaboration Suite release and use Oracle Collaboration Suite Upgrade Assistant to upgrade both Oracle Ultra Search middle tier and backend. See the Oracle Collaboration Suite installation guide that is appropriate for your platform.
Oracle Ultra Search supports the following upgrades:
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.
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.
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.
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
Use the SQL script
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
WKSYSPW: password of the user
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.
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
Re-create user instance schemas and related database objects
Re-create user instances
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.
CONN_STRING: database connect string
SRC_WKSYSPW: password of the source database (9.0.1 database) user
SRC_CONN_STRING: source database connect string
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
The current execution step
Any error message raised from the stored procedures
Number of data records backup
Number of data records copied or migrated
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.
Launch Oracle Collaboration Suite release1 installer, and perform the infrastructure install.
Specify the directory of the Oracle Application Server 9.0.2 infrastructure as the Oracle home.
The Oracle Universal Installer then detects a previously installed database and automatically upgrades the infrastructure database and the Oracle Ultra Search backend.
Because Oracle Ultra Search 9.2 uses the same database schema as Oracle Ultra Search 9.0.2, the upgrade procedure is the same.
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
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.
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".
See Also:"Editing the data-sources.xml File"
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:
String m_datasource_name = "jdbc/UltraSearchPooledDS";