Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.Opens in a new tab

For information on migrating to InterSystems IRISOpens in a new tab, see Why Migrate to InterSystems IRIS?

%Library.IndexBuilder

abstract class %Library.IndexBuilder

The purpose of this class is to allow one or more indices to be added to a class on a system that can afford little downtime, and the normal %BuildIndices process would take a very long time because the large amount of data in the class/table. %Library.IndexBuilder implements an interface to build indices for a class using multiple processes.

IMPORTANT:
-- The preferred index building utilty is now the %BuildIndices method of each persistent class, not %Library.IndexBuilder/%ConstructIndicesParallel().
-- %Library.IndexBuilder/%ConstructIndicesParallel() may only be used with classes that have positive INTEGER ID values.
-- The only feature %Library.IndexBuilder/%ConstructIndicesParallel() has that %BuildIndices does not is the SortBegin flag.

Index Builder

Construct Index Parallel

Overview

The %Library.IndexBuilder class contains methods that can be inherited into persistent classes that will allow indices defined in the class to be built using multiple processes. The class allows one or more indices to be added to a class on a system that can afford little down-time, and the normal %BuildIndices process would take a very long time because the amount of data in the class/table.

To add the IndexBuilder methods to your class, your class definition must list %Library.IndexBuilder as a superclass. There is also a class parameter recognized by the methods of %Library.IndexBuilder called INDEXBUILDERFILTER. INDEXBUILDERFILTER parameter is a string value of index names delimited by a comma if there is more than one name. INDEXBUILDERFILTER is looked at to determine which indices should be built by the %ConstructIndicesParallel method. For example, suppose you add the NameIDX index to class Sample.Person and would like to build only that Index. Define the INDEXBUILDERFILTER parameter as follows:

	Parameter INDEXBUILDERFILTER = "NameIDX";
	

Then when %ConstructIndicesParallel() method is called, only the NameIDX index will be built.

If INDEXBUILDERFILTER is not defined or set to "", all indices in the class will be built.

When you are ready to build the index, call the %ConstructIndicesParallel() method of the class you want to build the index for. Above we added the NameIDX index to Sample.Person, so you would make the following call:

set sc=##class(Sample.Person).%ConstructIndicesParallel()

The arguments to %ConstructIndicesParallel are as follows:

1)  TaskId - For internal use only.  For direct, interactive callers, leave this undefined.

2)  StartId - ID of the table to start building the ID for.  Default is 1

3)  EndId - ID of the table you want to end the Index build on.  
            Default is -1 which means end at the last ID of the table

4)  Sortbegin - 1/0 Flag which determines if the index build will use the SortBegin feature.

5)  DroneCount - Number of background jobs to use to build the indices.  
	Default is 0, in which case the code will determine the number of Drones to use based on the number of CPUs and the range of rows being indexed.

6)  LockFlag - Flag that determines locking behavior for the index build.
 			0 = No locking performed for the index build
 			1 = Extent locking - Acquires an exclusive lock on the entire extent for the duration of the index build
 			2 = Row level locking - Acquires a shared lock for each row as it is processed and the index defined for the entry.
                        When index build for this row is complete, an immediate unlock of this row is performed.

7)  JournalFlag - 0/1 flag.  1 means the index building will be journalled.  
                             0 means turn off journalling for this index build

The following example will build the NameIDX of the Sample.Person table for all rows:

       set sc=##class(Sample.Person).%ConstructIndicesParallel(,,,1,,1,1)

This builds the index entry for the NameIDX for all rows with ID 1 through the last ID of the class/table. It uses SortBegin, performs Extent level locking, and the index build is journalled.

       set sc=##class(Sample.Person).%ConstructIndicesParallel(,1,50000000,1,,2,0)

This builds the index entry for the NameIDX for all rows with ID 1 through 50,000,000 of the class/table. It uses SortBegin, performs row level level locking, and the index build is not journalled.

Method Inventory

Parameters

parameter BITMAPCHUNKINMEMORY = 0;
BITMAPCHUNKINMEMORY is used during code generation to decide whether or not bitmap chunks can be constructed in memory. It is faster to construct bitmap chunks in memory but if there are a lot of bitmaps, the indexed property or properties have very low selectivity or the index values are large then STORE errors can be encountered. If BITMAPCHUNKINMEMORY is 1 then bitmap chunks are constructed in memory by %ConstructIndices. Otherwise, bitmap chunks are constructed using process-private globals. The default is 0, meaning that bitmap chunks are built using process-private globals.

Methods

classmethod %ConstructIndicesParallel(pTaskId="", pStartId As %Integer = 0, pEndId As %Integer = -1, pSortBegin As %Integer = 1, pDroneCount As %Integer = 0, pLockFlag As %Integer = 1, pJournalFlag As %Boolean = 1) as %Status

%ConstructIndicesParallel() will build the indices of this class (optionally filtered by the INDEXBUILDERFILTER class parameter)

Arguments:
	pTaskId		- TaskID of the background job - leave blank/undefined for the interactive caller
	pStartId	- ID of the table to start building the ID for.  Default is 1
	pEndId		- ID of the table you want to end the Index build on.  Default is -1 which means end at the last ID of the table
	pSortbegin	- 1/0 Flag which determines if the index build will use the SortBegin feature.
	pDroneCount	- Number of background jobs to use to build the indices.  
			  Default is 0, in which case the code will determine the number of Drones to use based on the 
			  number of CPUs and the range of rows being indexed.
	pLockFlag	- Flag that determines locking behavior for the index build.
			   0 = No locking performed for the index build
			   1 = Extent locking - Acuires an exclusive lock on the entire extent for the duration of the index build
			   2 = Row level locking - Acquires a shared lock for each row as it is processed and the index defined for the entry.
				When index build for this row is complete, and immediate unlock of this row is performed.
	pJournalFlag	- 0/1 flag.  1 means the index building will be journalled.  0 means turn off journalling for this index build
	

Subclasses

FeedbackOpens in a new tab