Overview

When a space is looking for a match for a read or take operation, it iterates over non-null values in the template, looking for matches in the space. This process can be time consuming, especially when there are many potential matches. To improve performance, it is possible to index one or more properties. The space maintains additional data for indexed properties, which shortens the time required to determine a match, thus improving performance.

Choosing which Properties to Index

One might wonder why properties are not always indexed, or why all the properties in all the classes are not always indexed. The reason is that indexing has its downsides as well:

• An indexed property can speed up read/take operations, but might also slow down write/update operations.
• An indexed property consumes more resources, specifically memory footprint per entry.

When to Use Indexing

Naturally the question arises of when to use indexing. Usually it is recommended to index properties that are used in common queries. However, in some scenarios one might favor less footprint, or faster performance for a specific query, and adding/removing an index should be considered.

Remember that "Premature optimization is the root of all evil". It is always recommended to benchmark your code to get better results.

Adding or removing an index in runtime is currently not supported.

Setting a Property Index Type

New in 7.1 This API is new to 7.1 - the previous API has been deprecated. If you are using GigaSpaces XAP version 7.0.1 or older - please use the old API. Please also note that this section is relevant to the GigaSpace interface. The JDBC API allows you to index columns using standard SQL syntax.

The index type is determined by the SpaceIndexType enumeration. The index types are:

BASIC - Basic index is used - this speeds up equality matches (equal to/not equal to).
EXTENDED - Extended index - this speeds up comparison matches (bigger than/less than).

Code sample

You can specify which properties of a class are indexed, using annotations or gs.xml.

@SpaceClass
public class Person
{
    private String lastName;
    private String firstName;
    private Integer age;

    ...
    @SpaceIndex(type=SpaceIndexType.BASIC)
    public String getFirstName() {return firstName;}
    public void setFirstName(String firstName) {this.firstName = firstName;}

    @SpaceIndex(type=SpaceIndexType.BASIC)
    public String getLastName() {return lastName;}
    public void setLastName(String name) {this.lastName = name;}

    @SpaceIndex(type=SpaceIndexType.EXTENDED)
    public String getAge() {return age;}
    public void setAge(String age) {this.age = age;}
}

<gigaspaces-mapping>
    <class name="com.gigaspaces.examples.Person" persist="false" replicate="false" fifo="false" >
        <property name="lastName">
            <index type="BASIC"/> 
        </property>
        <property name="firstName">
            <index type="BASIC"/> 
        </property>
        <property name="age">
             <index type="EXTENDED"/> 
        </property>
    </class>
</gigaspaces-mapping>

Inheritance

By default, a property's index is inherited in sub classes (i.e. if a property is indexed in a super class, it is also indexed in a sub class). This behavior can be changed by specifying inheritIndexes=false in the space class annotation or gs.xml element.

Nested Properties Indexing

An index can be defined on a nested property to improve performance of nested queries - this is highly recommended.

Nested properties indexing uses an additional @SpaceIndex attribute - path().

The SpaceIndex.path() Attribute

The path() attribute represents the path of the property within the nested object.

Below is an example of defining an index on a nested property:

@SpaceClass
public static class Person {
    private int id;
    private Info personalInfo;
    private String description;
    //getter and setter methods
    ... 

    // this defines and EXTENDED index on the personalInfo.socialSecurity property
    @SpaceIndex(path = "socialSecurity", type = SpaceIndexType.EXTENDED)
    public Info getPersonalInfo() {
         return personalInfo;
    }
}

public static class Info implements Serializable {
	private String name;
	private Address address;
	private Date birthday;
	private long socialSecurity;
	private int _id;
	//getter and setter methods
}

public static class Address implements Serializable {
	private int zipCode;
	private String street;
	//getter and setter methods
}

@SpaceClass
public static class Person {
	private int id;
	private Info personalInfo;
	private String description;
	private HashMap<String, String> map;

	//getter and setter methods
	... 

	// this defines several indexes on the same personalInfo property
	 @SpaceIndexes( { @SpaceIndex(path = "socialSecurity", type = SpaceIndexType.EXTENDED),
			@SpaceIndex(path = "address.zipCode", type = SpaceIndexType.BASIC)})
	public Info getPersonalInfo() {
		 return personalInfo;
	}

	// this defines indexes on map keys
	@SpaceIndexes(	{@SpaceIndex(path="key1" , type = SpaceIndexType.BASIC),
			@SpaceIndex(path="key2" , type = SpaceIndexType.BASIC)})
	public HashMap<String, String> getMap() {
		return map;
	}
	public void setMap(HashMap<String, String> map) {
		this.map = map;
	}
}

public static class Info implements Serializable {
	private String name;
	private Address address;
	private Date birthday;
	private long socialSecurity;
	private int _id;
	//getter and setter methods
}

public static class Address implements Serializable {
	private int zipCode;
	private String street;
	//getter and setter methods
}

<gigaspaces-mapping>
    <class name="com.gigaspaces.examples.Person"  >
         <property name="personalInfo">
		<index path="socialSecurity" type = "extended"/>			
		<index path="address.zipCode" type = "basic"/>									
	</property>
    </class>
</gigaspaces-mapping>

The following is an example of query code that automatically triggers this index:

SQLQuery<Person> query = new SQLQuery<Person>(Person.class,
	"personalInfo.socialSecurity<10000050L and personalInfo.socialSecurity>=10000010L");

For more information, see Nested Object Queries

Map based nested properties Note that the same indexing techniques above are also applicable to Map-based nested properties, which means that in the example above the Info and Address classes could be replaced with a java.util.Map<String,Object>, with the map keys representing the property names.

Other Indexing Options

Implicit Indexing

If no properties are indexed explicitly, the space implicitly indexes the first n properties (in alphabetical order), where n is determined by the number-implicit-indexes property in the space schema.

Using this feature is not recommended, since adding/removing properties can have unexpected side effects. It is deprecated, and might be removed in future versions.

Query Execution Flow

When a read, take, readMultiple, or takeMultiple call is performed, a template is used to locate matching space objects. The template might have multiple field values - some might include values and some might not (i.e. null field values acting as wildcard). The fields that do not include values are ignored during the matching process. In addition, some class fields might be indexed and some might not be indexed.

When multiple class fields are indexed, the space looks for the field value index that includes the smallest amount of matching space objects with the corresponding template field value as the index key.

The smallest set of space objects is the list of objects to perform the matching against (matching candidates). Once the candidates space object list has been constructed, it is scanned to locate space objects that fully match the given template - i.e. all non-null template fields match the corresponding space object fields.

Class fields that are not indexed are not used to construct the candidates list.