14 March 2024

Explain Plan

Explain Plan can be used to obtain a description of the strategy or plan that GigaSpaces uses to implement a specific SQLQuery. Explain Plan reports on the way in which the query uses indices and how many entries were scanned.

For detailed information how to assign indexes, see the Indexing section.

Index Information

Indexes that the space considered using and the selected index at each stage of the query.
Each cluster node may produce a different result.
Information breakdown by Pojo type.

Scanning Information

Number of entries the space scanned in order to find the matching entries and how many entries were matched.
Each cluster node may produce a different result.
Information breakdown by Pojo type.

Index Types

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

NONE - No indexing is used.

EQUAL - performs equality matching (equal to/not equal to).

ORDERED - performs ordered matching (bigger than/less than).

EQUAL_AND_ORDERED - performs both equality and ordered matching, and uses a larger memory footprint than the other indexing types.

Usage

The execution plan is initiated by calling the withExplainPlan() method on the SQLQuery. After the query is executed the information is obtained with the query.getExplainPlan() method.


SQLQuery<Person> query = new SQLQuery<Person>(Person.class, "age > 20")
        .withExplainPlan();
gigaSpace.readMultiple(query);
ExplainPlan explainPlan = query.getExplainPlan();

Example

We use a Person class with several properties annotated with @SpaceIndex indicating that we want to use indexes when queries are performed.


import java.util.UUID;

import com.gigaspaces.annotation.pojo.SpaceClass;
import com.gigaspaces.annotation.pojo.SpaceId;
import com.gigaspaces.annotation.pojo.SpaceIndex;

@SpaceClass
public class Person {
    private UUID id;
    private String country;
    private String gender;
    private Long age;
    
    @SpaceId
    public UUID getId() {
        return id;
    }
    @SpaceIndex
    public String getCountry() {
        return country;
    }
    
    @SpaceIndex
    public String getGender() {
        return gender;
    }
    
    @SpaceIndex
    public Long getAge() {
        return age;
    }
    .........
}

When different SQLQuery are executed against the space, we can display for each of them the plan that GigaSpaces chooses to execute the query.

Query


SQLQuery<Person> query = new SQLQuery<Person>(Person.class, "age > ? ")
    .setParameter(1, 30L)
    .withExplainPlan();
gigaSpace.readMultiple(query);
System.out.println(query.getExplainPlan());

Output


******************** Explain plan report ********************
Query: SELECT * FROM sandbox.explainplan.Person WHERE age > ? 
Execution Information Summary:
    Total scanned partitions: 1
    Total scanned entries: 1000
    Total matched entries: 1000
Detailed Execution Information:
    Query Tree:
        AND
            GT(age, 30)
    Partition Id: 0
    Index Information: NO INDEX USED
        sandbox.explainplan.Person:
        Scanned entries: 1000
        Matched entries: 1000
*************************************************************

Limitations

Supported via the Java API. Not supported via the .NET API.
Supported operations: Read, ReadMultiple, TakeMultiple , count
Supported index types: Equal, Ordered, and Equal-and-Ordered. Unsupported index types: Compound, Unique, Collection, and Geospatial.
Supported query type : Basic.
Not Supported:
- Off-Heap
- FIFO grouping
- Operations: Take/Clear and variations, blocking operations, space iterator, aggregate , change, notifications
- JDBC V1 API (hence also WEB UI and GS UI). JDBC V3 has full support of Explain Plan and Explain Analyze.
- Regex, Is null, Sql function
Not thread Safe