Program guide > Access data with client applications > Data access with indexes (Index API)



Plug-ins for indexing data

The built-in HashIndex, or com.ibm.websphere.objectgrid.plugins.index.HashIndex class) is a MapIndexPlugin plug-in that you can add into BackingMap to build static or dynamic indexes. It supports both the MapIndex and MapRangeIndex interfaces. Defining and using indexes properly can significantly improve query performance.

For information regarding indexing, see Indexing and Composite HashIndex. For information about how to use indexing, see Use indexing for non-key data access and Composite HashIndex.


Configure a composite index

You can configure composite indexing in three ways: using XML, programmatically, and (for entity maps only) with entity annotations.


Use XML

In order to configure a composite index with XML, include code such as below in the configuration file's backingMapPluginCollections element. 

Composite index - XML configuration approach
<bean id="MapIndexPlugin"  className="com.ibm.websphere.objectgrid.plugins.index.HashIndex">
<property name="Name" type="java.lang.String" value="Address.CityStateZip"/>
<property name="AttributeName" type="java.lang.String" value="city,state,zipcode"/>
</bean>


Programmatic configuration

The programmatic example code below will create the same composite index as the preceding XML. 

      HashIndex mapIndex = new HashIndex();
    mapIndex.setName("Address.CityStateZip");
    mapIndex.setAttributeName(("city,state,zipcode"));
    mapIndex.setRangeIndex(true);

    BackingMap bm = objectGrid.defineMap("mymap");
    bm.addMapIndexPlugin(mapIndex);

Note that configuring a composite index is the same as configuring a regular index with XML except for the attributeName property value. In a composite index case, the value of attributeName is a comma-delimited list of attributes. For example, the value class Address has 3 attributes: city, state, and zipcode. A composite index can be defined with the attributeName property value as "city,state,zipcode" indicating that city, state, and zipcode are included in the composite index.

Also, note that the composite HashIndexes do not support range lookups and therefore cannot have the RangeIndex property set to true.


With entity annotations

In the entity map case, annotation approach can be used to define a composite index. You can define a list of CompositeIndex within CompositeIndexes annotation on the entity class level. The CompositeIndex has a name and attributeNames property. Each CompositeIndex is associated with a HashIndex instance applied to the entity's associated BackingMap. The HashIndex is configured as a non-range index. 

@Entity
@CompositeIndexes({
    @CompositeIndex(name="CityStateZip", attributeNames="city,state,zipcode"), 
    @CompositeIndex(name="lastnameBirthday", attributeNames="lastname,birthday")
 })
public class Address {
    @Id int id;
    String street;
    String city;
    String state;
    String zipcode;
    String lastname;
    Date birthday;
}

The name property for each composite index must be unique within the entity and BackingMap. If the name is not specified, a generated name will be used. The attributeNames property is used to populate the HashIndex attributeName with the comma-delimited list of attributes. The attribute names coincide with the persistent field names when the entities are configured to use field-access, or the property name as defined for the JavaBeans™ naming conventions for property-access entities. For example: If the attribute name is "street", the property getter method is named getStreet.


Attributes to configure HashIndex

You can use the following attributes to configure HashIndex using either the ObjectGrid deployment descriptor XML file or a programmatic approach:

Name

Name of the index. The name must be unique for each map. The name is used to retrieve the index object from the ObjectMap instance for the BackingMap.

AttributeName

Comma-delimited names of the attributes to index. For field-access indexes, the attribute names are equivalent to the field names. For property-access indexes, the attribute names are the JavaBean-compatible property names. If there is only one attribute name, the HashIndex is a single attribute index, and if this attribute is a relationship, it is also a relationship index. If multiple attribute names are included in the attribute names, the HashIndex is a composite index.

FieldAccessAttribute

Used for non-entity maps. If true, the object is accessed using the fields directly. If not specified or false, the attribute's getter method is used to access the data.

POJOKeyIndex

Used for non-entity maps. If true, the index will introspect the object in the key part of the map. This is useful when the key is a composite key and the value does not have the key embedded within it. If not specified or false, then the index will introspect the object in the value part of the map.

RangeIndex

If true, range indexing is enabled and the application can cast the retrieved index object to the MapRangeIndex interface. If the RangeIndex property is configured as false, the application can only cast the retrieved index object to the MapIndex interface.


Add HashIndex into BackingMap

There are few approaches you can use to add HashIndex into BackingMap. The following example illustrates the XML configuration approach by adding static index plug-ins:


XML configuration approach to add HashIndex into BackingMap 

<backingMapPluginCollection id="person">
  
<bean id="MapIndexplugin" 
      className="com.ibm.websphere.objectgrid.plugins.index.HashIndex">
        
<property name="Name" type="java.lang.String" value="CODE" 
            description="index name" />
        
<property name="RangeIndex" type="boolean" value="true" 
            description="true for MapRangeIndex" />
        
<property name="AttributeName" type="java.lang.String" value="employeeCode" 
            description="attribute name" />
  
</bean>
</backingMapPluginCollection>

In this XML configuration example, the built-in HashIndex class is used as the index plug-in. The HashIndex supports properties that users can configure, such as Name, RangeIndex, and AttributeName in the previous example.

In summary, the previous example defines a single-attribute range HashIndex. It is a single-attribute hashIndex. It also is a range HashIndex.


Single-attribute HashIndex versus composite HashIndex

When the AttributeName property of HashIndex includes multiple attribute names, the HashIndex is a composite index. Otherwise, if it includes only one attribute name, it is a single-attribute index. For example, the AttributeName property value of a composite HashIndex might be city,state,zipcode. It includes three attributes delimited by commas. If the AttributeName property value is only zipcode that only has one attribute, it is a single-attribute HashIndex. The preceding example is a single-attribute HashIndex because the AttributeName property value is “employeeCode” that includes only one attribute name.

Composite HashIndex provides an efficient way to look up cached objects when search criteria involve many attributes. However, it does not support range index and its RangeIndex property must set to “false”.

For more information, see Composite HashIndex.


Relationship HashIndex

If the indexed attribute of single-attribute HashIndex is a relationship, either single- or multi-valued, the HashIndex is a relationship HashIndex. For relationship HashIndex, the RangeIndex property of HashIndex must set to “false”.

Relationship HashIndex can speed up queries that use cyclical references or use the IS NULL, IS EMPTY, SIZE, and MEMBER OF query filters. For more information, see Query optimization using indexes.


Key HashIndex

For non-entity maps, when the POJOKeyIndex property of HashIndex is set to true, the HashIndex is a key HashIndex and the key part of entry will be used for indexing. When the AttributeName property of HashIndex is not specified, the whole key is indexed; otherwise, the key HashIndex can only be a single-attribute HashIndex.

For example, adding the following property into the preceding sample causes the HashIndex to become key HashIndex because the POJOKeyIndex property value is true. 

<property name="POJOKeyIndex" type="boolean" value="true" 
description="indicates if POJO key HashIndex" />

In the preceding key index example, because the AttributeName property value is specified as employeeCode, the indexed attribute is the employeeCode field of the key part of map entry. If you want to build key index on the whole key part of map entry, remove the AttributeName property.


Range HashIndex

When the RangeIndex property of HashIndex is set to true, the HashIndex is a range index and can support the MapRangeIndex interface. A MapRangeIndex supports functions to find data using range functions, such as greater than, less than, or both, while a MapIndex only supports equals functions. For a single-attribute index, the RangeIndex property can be set to true only if the indexed attribute is of type Comparable. If the single-attribute index will be used by query, the RangeIndex property must set to true and the indexed attribute must be of type Comparable. For relationship HashIndex and composite HashIndex, the RangeIndex property must set to false.

The preceding sample is a range HashIndex because the RangeIndex property value is true.

The following table provides a summary for using range index.

Table 1. Support for range index. States whether HashIndex types support range index.
HashIndex type Supports range index
Single-attribute HashIndex: indexed key or attribute is of type Comparable Yes
Single-attribute HashIndex: indexed key or attribute is not of type Comparable No
Composite HashIndex No
Relationship HashIndex No


Query optimization using HashIndex

Define and using indexes properly can significantly improve query performance.WebSphere eXtreme Scale queries can use built-in HashIndex plug-ins to improve performance of queries. Although using indexes can significantly improve query performance, it might have a performance impact on transactional map operations.


Parent topic:

Data access with indexes (Index API)


+

Search Tips   |   Advanced Search