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 index all the properties in all the classes. The reason is that index has 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.

So naturally the next question is when to use indexing. Usually it is recommended to index properties which are used in common queries. However, in some scenarios one might favour less footprint, or faster performance for a specific query, adding/removing an index should be considered.

Remember that "Premature optimization is the root of all evil". It's 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

This section is relevant when using the GigaSpace interface. The JDBC API allows you to index attribute using the standard JDBC API.

GigaSpaces supports several index types. The index type is determined by the IndexType enumeration. The index types are:

• NONE - No index is used.
• BASIC - Basic index is used. Basic index speeds up equality matches (equals to / not equals to).
• EXTENDED - Extended index. Extended index speeds up comparison matches (bigger than / less than).
• NOT_SET - Default value. Lets the system automatically determine the index type/ Id and routing properties are indexed with BASIC indexing, and all other properties are not indexed (i.e. NONE).

IndexType.EXTENDED is new in 7.0.1. However, extended indexing in earlier versions is supported - see Extended Indexing via Space Schema section.
IndexType.NOT_SET is new in 7.0.1. In previous versions, the default value was NONE.

Using Code

You can specify programmatically which properties of a class are indexed using annotations.

The @SpaceProperty(index=IndexType.BASIC) or @SpaceProperty(index=IndexType.EXTENDED) should be used to index a specific property. For example:

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

    ...
    @SpaceProperty(index=IndexType.BASIC)
    public String getFirstName() {return firstName;}
    public void setFirstName(String firstName) {this.firstName = firstName;}

    @SpaceProperty(index=IndexType.BASIC)
    public String getLastName() {return lastName;}
    public void setLastName(String name) {this.lastName = name;}

    @SpaceProperty(index=IndexType.EXTENDED)
    public String getAge() {return age;}
    public void setAge(String age) {this.age = age;}
}

Using XML

When using POJO as your Space Domain Class you can use the gs.xml to specify the indxed fields. See below example:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE gigaspaces-mapping PUBLIC "-//GIGASPACES//DTD GS//EN" "http://www.gigaspaces.com/dtd/6_0/gigaspaces-metadata.dtd">
<gigaspaces-mapping>
    <class name="com.gigaspaces.examples.Person" persist="false" replicate="false" fifo="false" >
        <property name="lastName" index="BASIC" />
        <property name="firstName" index="BASIC" />
        <property name="age" index="EXTENDED" />
    </class>
</gigaspaces-mapping>

Inheritence

By default, a property's index type 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 at the space class annotation or gs.xml element.

Indexing of special properties

By default, SpaceId property with autoGenerate=false and SpaceRouting property are indexed with BASIC. Starting 7.0.1, you can add a SpaceProperty indication to use EXTENDED indexing instead, or use NONE to turn off the implicit index.

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.

Extended Indexing via Space Schema

Older versions of XAP (prior to 7.0.1) used the space schema property space-config.engine.extended-match.enabled-classes.enabled-classes to specify a comma-seperated list of classes that support extended indexing. The space treats all explicit indexes specified in those classes as extended indexes instead of basic indexes. For example:

space-config.engine.extended-match.enabled-classes.enabled-classes=pack1.classA,pack2.classB

Using this feature is not recommended, since it forces all indexes in a class to be extended and is hard to maintain. It it recommended to use the new IndexType.EXTENDED in 7.0.1. This feature is deprecated and might be removed in future versions.

Under the hood

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.