@Explain

Documentation

VoltDB Home » Documentation » Using VoltDB

@Explain

@Explain — Returns the execution plan for the specified SQL query.

Synopsis

@Explain String SQL-statement

Description

The @Explain system procedure evaluates the specified SQL query and returns the resulting execution plan. Execution, or explain, plans describe how VoltDB expects to execute the query at runtime, including what indexes are used, the order the tables are joined, and so on. Execution plans are useful for identifying performance issues in query design. See the chapter on execution plans in the VoltDB Guide to Performance and Customization for information on how to interpret the plans.

Return Values

Returns one VoltTable with one row and one column.

NameDatatypeDescription
EXECUTION_PLANVARCHARThe execution plan as text.

Examples

The following program example uses @Explain to evaluate an ad hoc SQL SELECT statement against the voter sample application.

try {
    String query = "SELECT COUNT(*) FROM CONTESTANTS;"; 
    VoltTable[] results = client.callProcedure("@Explain",
       query ).getResults();
    System.out.printf("Query: %d\nPlan:\n%d",
        query, results[0].fetchRow(0).getString(0));
}
catch (Exception e) {
    e.printStackTrace();
}

In the sqlcmd utility, the "explain" command is a shortcut for "exec @Explain". So the following two commands are equivalent:

$ sqlcmd
1> exec @Explain 'SELECT COUNT(*) FROM CONTESTANTS';
2> explain SELECT COUNT(*) FROM CONTESTANTS;