Summary: Using indexes to improve performance.
OverviewWhen 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 IndexOne 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:
When to Use IndexingNaturally 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 favour less footprint, or faster performance for a specific query, and adding/removing an index should be considered.
Index TypesThe index type is determined by the SpaceIndexType enumeration. The index types are: NONE - No indexing is used. Indexing at Design-timeSpecifying which properties of a class are indexed is done using annotations or gs.xml.
Annotations
@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 Integer getAge() {return age;} public void setAge(Integer age) {this.age = age;} } XML <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> InheritanceBy 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). If you need to change the index type of a property in a subclass you can override the property and annotate it with @SpaceIndex using the requested index type (to disable indexing use NONE). Indexing at Run-timeIndexes can be added dynamically at run-time using the GigaSpaces Management Center GUI or via API using the GigaSpaceTypeManager interface.
Nested Properties IndexingAn 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() AttributeThe path() attribute represents the path of the property within the nested object. Below is an example of defining an index on a nested property:
Single Index Annotation
@SpaceClass public 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 } Multiple Indexes Annotation @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 } XML <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");
Collection IndexingAn index can be defined on a Collection property (java.util.Collection implementation) or Array. Setting such an index means that each of the Collection's or Array's items is indexed. Setting an index on a Collection / Array done using the SpaceIndex.path() attribute where a Collection / Array property should be followed by "[*]". The following example shows how to define an index on a List of Integers: @SpaceClass public class CollectionIndexingExample { private Integer id; private List<Integer> numbers; // Getter and setter methods... @SpaceIndex(path="[*]") // This means that each Integer in the List is indexed. public List<Integer> getNumbers() { return this.numbers; } } The following query shows how to use the index: SQLQuery<CollectionIndexingExample> sqlQuery = new SQLQuery<CollectionIndexingExample>( CollectionIndexingExample.class, "numbers[*] = 30"); CollectionIndexingExample[] result = gigaspace.readMultiple(sqlQuery, Integer.MAX_VALUE);
Nested property within a CollectionIts also possible to index a nested property within a collection. The following example shows how to define an index on Book.id property which resides in a Collection property in Author: @SpaceClass public class Author { private String name; private Collection<Book> books; // Getter and setter methods... @SpaceIndex(path="[*].id") // This means that each Book.id in the Collection is indexed. public Collection<Book> getBooks() { return this.books; } } public class Book { private Integer id; private String name; // Getter and setter methods... public Integer getId() { return this.id; } } The following query shows how to take advantage of the defined index: SQLQuery<Author> sqlQuery = new SQLQuery<Author>(Author.class, "books[*].id = 57"); Author result = gigaspace.read(sqlQuery); Setting an index on a Collection within a nested property is also accepted: @SpaceClass public class Employee { private Long id; private Information information; // Getter and setter methods... @SpaceIndex(path="phoneNumbers[*]") public Information getInformation() { return this.information; } } public class Information { private Address address; private List<String> phoneNumbers; // Getter and setter methods... public List<String> getPhoneNumbers() { return this.phoneNumbers; } }
Performance TipsProperties that are not indexed and not used for queries can be grouped within a user defined class (also known as payload class). This improves the read/write performance since these properties would not be introduced to the space class model. Deprecated Indexing OptionsImplicit IndexingIf 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.
Query Execution FlowWhen 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.
|
![]() |
GigaSpaces.com - Legal Notice - 3rd Party Licenses - Site Map - API Docs - Forum - Downloads - Blog - White Papers - Contact Tech Writing - Gen. by Atlassian Confluence |