|Oracle® Ultra Search User's Guide
10g Release 1 (10.1)
Part Number B10731-02
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.
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.
See Also:Oracle Database Administrator's Guide for details on using automatic undo management
JOB_QUEUE_PROCESSES: Set this to three or higher. (Set it to at least one.) This is needed because the 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 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 Ultra Search, see the Ultra Search Readme.
The starter database created by the Oracle Installer may create a temporary tablespace that is too small. 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 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 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 Ultra Search instance user.
Ultra Search uses Oracle's fine grained access control feature to support multiple 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:Ultra Search requires that each 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 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 Ultra Search instance owner
and password = password of the Ultra Search instance owner
and default_tbs = default tablespace for the 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 Ultra Search super-user can create an 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 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 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 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.
Starting with Oracle Application Server 10g and Oracle Database 10g, Ultra Search supports secure socket layer (SSL), a worldwide standard for encryption over the HTTP protocol (HTTPS). In other words, all content crawling, indexing, and querying is encrypted using SSL. Ultra Search supports the crawling of Web sites with HTTPS. Also, in the Ultra Search administration tool, you can register HTML Forms, which are accessible with HTTPS.
Ultra Search uses the SSL service provided by Sun's JDK as is, including the default Trust and Key Managers. SUN also ships a default truststore, a file called cacerts, with their JRE. SUN's truststore is in SUN's proprietary JKS format.
Truststore is a list of public SSL certificates identifying entities with which Ultra Search can communicate over SSL. You are responsible for maintaining this or another truststore that your JRE is configured to use.
Over time, you will have to maintain your truststore. You might need to update expired certificates with new issues, or you might need to add new certificates to the truststore, effectively adding a new entities to the list of ones you are willing to communicate with over SSL.
For example, say you want to service a secure Oracle Portal installation using Ultra Search. And say your Oracle Portal installation does not have a certificate issued by one of the well known certificate authorities like Verisign; but rather, it uses a self-signed certificate issues by you. That means that, by default, your truststore will not list your Oracle Portal's certificate as a trusted certificate Consequently, you need to add to the truststore the certificate identifying your Oracle Portal installation.
Besides third party tools, SUN provides it's own truststore management tool called "keytool". You can use keytool to add, update, remove, and import certificates to and from SUN's truststore. Keytool also lets you create your own self-signed certificates.
Ultra Search runs on multiple JVMs: the Ultra Search crawler runs in its own JVM, a remote crawler uses another JVM, and each Ultra Search midtier runs in its Web server's JVM. Behind each of these JVMs, there is potentially a different JRE/JDK installation with its truststore, which you will need to maintain. There is one JDK in the Oracle home, which is used for both the midtier JVM and the crawler JVM.
See Also:Sun Microsystems documentation, including the JSSE User's Guide, for more information about using Sun's keytool key and certificate management utility, for information on customization of the SSL service, and for information on truststore management
Every 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 Ultra Search product. Subsequently, when an Ultra Search instance is created, a copy of the default stoplist is created for the 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 Ultra Search instances. They only affect 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 Ultra Search instance stoplist is modified and defined before initial crawling. This means that all documents collected by the 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 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 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.
Ultra Search is shipped with the Oracle Database, the Oracle Application Server, and the Oracle Collaboration Suite. To upgrade 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:"Ultra Search Release Information" describes the Ultra Search release numbering
Before you upgrade, log on to the Ultra Search administration tool. Stop and disable all crawler synchronization schedules in every 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 Ultra Search shipped with the Oracle Database release, do the following:
Run the Ultra Search backend upgrade. This includes upgrading the Ultra Search database schemas and server files. Install the new Oracle software, and run Oracle Database Upgrade Assistant to upgrade the database and Ultra Search component to the new release. See the Oracle Database Upgrade Guide for details.
Follow the steps in "Installing the Ultra Search Middle Tier on Web Server Hosts" to install the new Ultra Search middle tier.
To upgrade 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 Oracle9i Application Server Upgrading to Release 2 (9.0.4) section "Upgrading the Middle Tier" for details.
Perform the upgrade on the Ultra Search schema in the Oracle Application Server Metadata Repository. See the Oracle9i Application Server Upgrading to Release 2 (9.0.4) section about running the 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 Ultra Search middle tier and backend. See the Oracle Collaboration Suite installation guide that is appropriate for your platform.If you are using Ultra Search 9.0.2 (shipped with Oracle Application Sever release) or 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 Ultra Search to Oracle Collaboration Suite release 1 first. See section "Upgrading 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 Ultra Search middle tier and backend. See the Oracle Collaboration Suite installation guide that is appropriate for your platform.
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 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 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 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 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 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 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 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 Ultra Search 1.0.3 user instance schemas in the new database. Also, for each table data source created in 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 Ultra Search administration tool.
Note:The upgrade script does not roll back the 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 Ultra Search 9.0.2 to 9.0.3, perform the following steps:
Copy all 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 Ultra Search 9.0.2 administration tool. Stop and disable all crawler synchronization schedules in every 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 Ultra Search backend.
Because Ultra Search 9.2 uses the same database schema as Ultra Search 9.0.2, the upgrade procedure is the same.
After upgrading to the current release, follow these configuration steps:
ORACLE_SID environment variables to Oracle Database 10g.
Change directories to
Run this statement:
sqlplus "sys/password as sysdba"
Run this statement:
@wk0config.sql WKSYSPW JDBC_CONNSTR LAUNCH_ANYWHERE NET_SERVICE_NAME
WKSYSPW is the password for the
JDBC_CONNSTR is the JDBC connection string. Use the format hostname:port:sid, such as machine1:1521:iasdb, if the database is not in the Oracle Real Application Clusters (RAC) environment.
If the database is in a RAC environment, then use the TNS keyword-value format instead, because it allows connection to any node of the system:
(DESCRIPTION=(LOAD_BALANCE=yes) (ADDRESS_LIST= (ADDRESS=(PROTOCOL=TCP)(HOST=cls02a)(PORT=3001)) (ADDRESS=(PROTOCOL=TCP)(HOST=cls02b)(PORT=3001))) (CONNECT_DATA=(SERVICE_NAME=sales.us.acme.com)))
LAUNCH_ANYWHERE is the mode of the database. Setting it to
TRUE indicates that the database is in RAC mode;
FALSE indicates that the database is not in RAC mode.
NET_SERVICE_NAME is the network service name used by
wk0config.sql to establish the database connection. Setting it to
""(empty string) while running
wk0config.sql from the database host eliminates the need to specify the network service name.
The Ultra Search query application is deployed automatically with the Ultra Search installation. However, because 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 Ultra Search data source). This is done by editing the
The data-sources.xml file is the OC4J connection management facility. The 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 Ultra Search query application finds the data source by using its location, "jdbc/UltraSearchPooledDS".
See Also:"Editing the data-sources.xml File"
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";