Index and Reindex

The following events initiate index updating:

• Commits to the Subversion repository, including changes initiated by Polarion.

• Polarion start-up.

The index contains information about location of all entities in the repository and their history, so the term index refers to more things then just the index used by the Search feature. Rather it is the entire indexing scheme that enables optimal performance.

During the index update, Polarion checks all changes made to repository since the last indexed revision, and updates the index accordingly.

Changing sort order of an enumeration, dates of time points, and similar items that are already referenced will cause inconsistency in the sorting. Some referrals will be sorted by the old sort order, and some by the new. A complete index rebuild solves this problem.

Symptoms of a broken index tend to be things like some Work Items are not up-to-date, some are missing, History cannot be viewed, or shows invalid or truncated information.

If you observe the above symptoms you may not need to completely rebuild the index .

1. Try an index refresh on the repository, or on a specific project. This corrects problems with information updating.

   Go to the Administration interface and open the Repository (if you want to refresh the entire repository), or a project (if the problem seems to affect only that project). Then, in Navigation, select Maintenance. In the Index section, check the index(s) to refresh and click Refresh Index.

   Tip:

   The indexes listed varies depending on whether you are working in global or project scope.

2. If number 1 above does not fix all symptoms, try the Check Index button. The index check job should bring back Work Items that are missing from view.

If the above steps do not fix the symptoms, then you will need to rebuild the full index.

The procedure may sometimes be referred to as "index rebuild", "rebuild index", "index synchronization", or "index rebuilding".

There are two important things for an administrator to keep in mind before initiating an index rebuild:

• The Polarion server must be shut down before commencing an index rebuild.

• Depending on the size of the repository, reindexing time can range from a few minutes to several hours. End users will not be able to use the system during the reindexing process.

  If possible, you should plan to perform any re-index operation at a time when system usage is low, and downtime is not critical for end users.

Users cannot use the system while the system indexes are being rebuilt. They can, however, use the system while the historical database is being reindexed.

The embedded historical SQL database, which replicates the Subversion repository to facilitate complex queries, is indexed in the background. Although users can use the system, some features are either not available, or do not display information until the database reindex is complete. A message is displayed at the top of the Navigation panel warning users that database indexing is in progress.

• Baseline (Time Machine) feature is not available.

• Reports that contain SQL queries on the historical database do not work and display error messages.

• Burn-up and burn-down charts in Plans do not work and display error messages.

• Test management form extensions do not work.

The reindexing scripts perform the following operations:

1. Back up of the polarion-data folder. The folder is renamed to polarion-data.saved.

   Path: $POLARION_HOME$/data/workspace/polarion-data.

2. Start up of the Polarion service. This service must be shut down before running the indexing script.

3. Regenerate the index in the polarion-data folder. As previously noted, this can take considerable time during which users will not be able to access the system.

It is possible to configure how many CPU cores (workers) are used in the phases of the indexing process. There is one basic system property - com.polarion.startup.workers - that can be configured to define total number of workers for all phases of reindex that can run in parallel. Administrators can also specify different numbers for individual phases in instances of the system property com.polarion.startup.workers.phase#, where # can be any of the following:

• 3 - For Context Initialization (phase 3),

• 7 - For Data Indexing (phase 7),

• 8 - For calculating calculated fields (phase 8),

• 10 - For Attachment indexing (phase 10 AttachmentIndexer job),

  Note:

  It is possible to control which attachment file types have their content indexed, or to exclude specific file types from such indexing. For information, see Attachment file types.

• 11 - For History Indexing (phase 11DBHistoryCrator job).

By default, the number of CPU cores used for the above phases is total cores, divided by 2, plus 1. For example, on a CPU with 4 cores, the default usage is (4/2) + 1 = 3 cores.

In the default setup, the jobs are configured to run only between 19:00 and 08:00, and they can be stopped and started by scheduled jobs, so in most cases there should be no need to redefine the number of workers. Adjusting the number of workers may be worth doing for the jobs running after Polarion start-up that may cause performance to slow.

To explicitly set core usage for all index phases and/or the configurable index phases listed above, you must add the following lines to the system properties file polarion.properties:

• Total workers for all phases:

  com.polarion.startup.workers=[N] (where [N] is an integer value that should not exceed the total available CPU cores).

  Example: com.polarion.startup.workers=8

• Workers for specific phases:

  com.polarion.startup.workers.phase#=[N] (where # is the phase, and [N] is an integer value specifying the number of workers to be used for the specified phase.

  Examples:

  • com.polarion.startup.workers.phase3=2

  • com.polarion.startup.workers.phase10=3

You perform the reindexing by running the appropriate reindexing script for your operating system. Be sure you shut down the Polarion server (Polarion Service) before running the script.

• Windows: C:\Polarion\polarion\reindex.bat,

• Linux: $POLARION_HOME$/bin/polarion.init reindex,

Progress of the reindexing operation is reported in the console and written to a log file.