QueryBuilder (Drill : Exec : Java Execution Engine 1.20.0 API)

java.lang.Object
- org.apache.drill.test.QueryBuilder

```
public class QueryBuilder
extends Object
```
Builder for a Drill query. Provides all types of query formats, and a variety of ways to run the query.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`QueryBuilder.PlanMatcher` Collects expected and non-expected query patterns.
`static class`	`QueryBuilder.QuerySummary` Summary results of a query: records, batches, run time.
`static class`	`QueryBuilder.QuerySummaryFuture` The future used to wait for the completion of an async query.
`static class`	`QueryBuilder.SummaryOnlyQueryEventListener` Listener used to retrieve the query summary (only) asynchronously using a `QueryBuilder.QuerySummaryFuture`.
`static interface`	`QueryBuilder.VectorQueryReader<T,V>` VectorQueryReader function interface

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`QueryBuilder.PlanMatcher`	`detailedPlanMatcher()` Submits explain plan statement and creates plan matcher instance based on return query plan with all attributes.
`String`	`explain(String format)`
`String`	`explainDetailed(String format)`
`String`	`explainJson()` Submit an "EXPLAIN" statement, and return the JSON form of the plan.
`String`	`explainText()` Submit an "EXPLAIN" statement, and return text form of the plan.
`String`	`explainTextWithAllAttributes()` Submit an "EXPLAIN" statement, and return text form of the plan with all attributes.
`QueryBuilder.QuerySummaryFuture`	`futureSummary()` Run the query asynchronously, returning a future to be used to check for query completion, wait for completion, and obtain the result summary.
`QueryBuilder.PlanMatcher`	`jsonPlanMatcher()` Submits explain plan statement and creates plan matcher instance based on return query plan.
`long`	`log()` Run a query and logs the output in TSV format.
`long`	`log(QuerySubmitter.Format format)`
`long`	`log(QuerySubmitter.Format format, int colWidth)`
`long`	`logCsv()`
`QueryBuilder`	`physical(String plan)`
`QueryBuilder`	`physicalResource(String resource)`
`QueryBuilder`	`plan(List<BitControl.PlanFragment> planFragments)` Run a physical plan presented as a list of fragments.
`QueryBuilder.PlanMatcher`	`planMatcher()` Submits explain plan statement and creates plan matcher instance based on return query plan.
`long`	`print()` Runs a query and prints the output to stdout in TSV format.
`long`	`print(QuerySubmitter.Format format)`
`long`	`print(QuerySubmitter.Format format, int colWidth)`
`long`	`printCsv()`
`QueryBuilder`	`query(UserBitShared.QueryType type, String text)`
`List<QueryDataBatch>`	`results()` Run the query and return a list of the result batches.
`QueryResultSet`	`resultSet()`
`DirectRowSet`	`rowSet()` Run the query and return the first non-empty batch as a `DirectRowSet` object that can be inspected directly by the code using a `RowSetReader`.
`QueryRowSetIterator`	`rowSetIterator()`
`QueryRowSetReader`	`rowSetReader()`
`QueryBuilder.QuerySummary`	`run()` Run the query returning just a summary of the results: record count, batch count and run time.
`long`	`runAndWait(UserResultsListener listener)`
`double`	`singletonDouble()` Run the query that is expected to return (at least) one row with the only (or first) column returning a double value.
`int`	`singletonInt()` Run the query that is expected to return (at least) one row with the only (or first) column returning a int value.
`long`	`singletonLong()` Run the query that is expected to return (at least) one row with the only (or first) column returning a long value.
`org.joda.time.Period`	`singletonPeriod()` Run the query that is expected to return (at least) one row with the only (or first) column returning a `Period` value.
`String`	`singletonString()` Run the query that is expected to return (at least) one row with the only (or first) column returning a string value.
`QueryBuilder`	`sql(File file)` Parse a single SQL statement (with optional ending semi-colon) from the file provided.
`QueryBuilder`	`sql(String sql)`
`QueryBuilder`	`sql(String query, Object... args)`
`QueryBuilder`	`sqlResource(String resource)` Run a query contained in a resource file.
`QueryBuilder`	`sqlResource(String resource, Object... args)`
`<T,V> T`	`vectorValue(String columnName, Class<V> vectorClass, QueryBuilder.VectorQueryReader<T,V> reader)` Run the query which expect to return vector `V` representation of type `T` for the column `columnName`.
`BufferingQueryEventListener`	`withEventListener()` Run the query, return an easy-to-use event listener to process the query results.
`void`	`withListener(UserResultsListener listener)` Run the query with the listener provided.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - query
```
public QueryBuilder query(UserBitShared.QueryType type,
                          String text)
```
  - sql
```
public QueryBuilder sql(String sql)
```
  - sql
```
public QueryBuilder sql(String query,
                        Object... args)
```
  - plan
```
public QueryBuilder plan(List<BitControl.PlanFragment> planFragments)
```
    Run a physical plan presented as a list of fragments.
    
    Parameters:
    
    planFragments - fragments that make up the plan
    
    Returns:
    
    this builder
  - sql
```
public QueryBuilder sql(File file)
                 throws IOException
```
    Parse a single SQL statement (with optional ending semi-colon) from the file provided.
    
    Parameters:
    
    file - the file containing exactly one SQL statement, with optional ending semi-colon
    
    Returns:
    
    this builder
    
    Throws:
    
    IOException
  - physical
```
public QueryBuilder physical(String plan)
```
  - sqlResource
```
public QueryBuilder sqlResource(String resource)
```
    Run a query contained in a resource file.
    
    Parameters:
    
    resource - Name of the resource
    
    Returns:
    
    this builder
  - sqlResource
```
public QueryBuilder sqlResource(String resource,
                                Object... args)
```
  - physicalResource
```
public QueryBuilder physicalResource(String resource)
```
  - run
```
public QueryBuilder.QuerySummary run()
                              throws Exception
```
    Run the query returning just a summary of the results: record count, batch count and run time. Handy when doing performance tests when the validity of the results is verified in some other test.
    
    Returns:
    
    the query summary
    
    Throws:
    
    Exception - if anything goes wrong anywhere in the execution
  - results
```
public List<QueryDataBatch> results()
                             throws RpcException
```
    Run the query and return a list of the result batches. Use if the batch count is small and you want to work with them.
    
    Returns:
    
    a list of batches resulting from the query
    
    Throws:
    
    RpcException - if anything goes wrong
  - rowSet
```
public DirectRowSet rowSet()
                    throws RpcException
```
    Run the query and return the first non-empty batch as a DirectRowSet object that can be inspected directly by the code using a RowSetReader.
    
    Returns:
    
    a row set that represents the first non-empty batch returned from the query, or null if the query returns no data (no batches)
    
    Throws:
    
    RpcException - if anything goes wrong
    
    See Also:
    
    for a version that reads a series of batches as row sets.
  - rowSetIterator
```
public QueryRowSetIterator rowSetIterator()
```
  - rowSetReader
```
public QueryRowSetReader rowSetReader()
```
  - vectorValue
```
public <T,V> T vectorValue(String columnName,
                           Class<V> vectorClass,
                           QueryBuilder.VectorQueryReader<T,V> reader)
                    throws RpcException,
                           SchemaChangeException
```
    Run the query which expect to return vector V representation of type T for the column columnName.
```
 Example:

  Set results = queryBuilder()
      .sql(query)
      .vectorValue(
        "columnName",
        SomeVector.class,
        (resultRecordCount, vector) -> {
          Set r = new HashSet<>();
          for (int i = 0; i < resultRecordCount; i++) {
            r.add(vector.getAccessor().getAsStringBuilder(i).toString());
          }
          return r;
        }
      );
 
```
    Type Parameters:
    
    V - vector class
    
    T - return type
    
    Parameters:
    
    columnName - name of the column to read
    
    vectorClass - returned by the query vector class
    
    reader - lambda to read the vector value representation
    
    Returns:
    
    result produced by reader lambda or null if no records returned from the query
    
    Throws:
    
    RpcException
    
    SchemaChangeException
  - singletonLong
```
public long singletonLong()
                   throws RpcException
```
    Run the query that is expected to return (at least) one row with the only (or first) column returning a long value. The long value cannot be null.
    
    Returns:
    
    the value of the first column of the first row
    
    Throws:
    
    RpcException - if anything goes wrong
  - singletonDouble
```
public double singletonDouble()
                       throws RpcException
```
    Run the query that is expected to return (at least) one row with the only (or first) column returning a double value. The double value cannot be null.
    
    Returns:
    
    the value of the first column of the first row
    
    Throws:
    
    RpcException - if anything goes wrong
  - singletonInt
```
public int singletonInt()
                 throws RpcException
```
    Run the query that is expected to return (at least) one row with the only (or first) column returning a int value. The int value cannot be null.
    
    Returns:
    
    the value of the first column of the first row
    
    Throws:
    
    RpcException - if anything goes wrong
  - singletonPeriod
```
public org.joda.time.Period singletonPeriod()
                                     throws RpcException
```
    Run the query that is expected to return (at least) one row with the only (or first) column returning a Period value. The Period value cannot be null.
    
    Returns:
    
    the value of the first column of the first row
    
    Throws:
    
    RpcException - if anything goes wrong
  - singletonString
```
public String singletonString()
                       throws RpcException
```
    Run the query that is expected to return (at least) one row with the only (or first) column returning a string value. The value may be null, in which case a null string is returned.
    
    Returns:
    
    the value of the first column of the first row
    
    Throws:
    
    RpcException - if anything goes wrong
  - withListener
```
public void withListener(UserResultsListener listener)
```
    Run the query with the listener provided. Use when the result count will be large, or you don't need the results.
    
    Parameters:
    
    listener - the Drill listener
  - withEventListener
```
public BufferingQueryEventListener withEventListener()
```
    Run the query, return an easy-to-use event listener to process the query results. Use when the result set is large. The listener allows the caller to iterate over results in the test thread. (The listener implements a producer-consumer model to hide the details of Drill listeners.)
    
    Returns:
    
    the query event listener
  - logCsv
```
public long logCsv()
```
  - log
```
public long log(QuerySubmitter.Format format)
```
  - log
```
public long log(QuerySubmitter.Format format,
                int colWidth)
```
  - log
```
public long log()
```
    Run a query and logs the output in TSV format. Similar to QueryTestUtil.testRunAndLog(org.apache.drill.exec.client.DrillClient, org.apache.drill.exec.proto.UserBitShared.QueryType, java.lang.String) with one query.
    
    Returns:
    
    The number of rows returned.
  - printCsv
```
public long printCsv()
```
  - print
```
public long print(QuerySubmitter.Format format)
```
  - print
```
public long print(QuerySubmitter.Format format,
                  int colWidth)
```
  - print
```
public long print()
```
    Runs a query and prints the output to stdout in TSV format. Similar to QueryTestUtil.testRunAndLog(org.apache.drill.exec.client.DrillClient, org.apache.drill.exec.proto.UserBitShared.QueryType, java.lang.String) with one query.
    
    Returns:
    
    The number of rows returned.
  - futureSummary
```
public QueryBuilder.QuerySummaryFuture futureSummary()
```
    Run the query asynchronously, returning a future to be used to check for query completion, wait for completion, and obtain the result summary.
    
    Returns:
    
    query summary future
  - runAndWait
```
public long runAndWait(UserResultsListener listener)
```
  - explainText
```
public String explainText()
                   throws Exception
```
    Submit an "EXPLAIN" statement, and return text form of the plan.
    
    Returns:
    
    explain plan
    
    Throws:
    
    Exception - if the query fails
  - explainTextWithAllAttributes
```
public String explainTextWithAllAttributes()
                                    throws Exception
```
    Submit an "EXPLAIN" statement, and return text form of the plan with all attributes.
    
    Throws:
    
    Exception - if the query fails
  - explainJson
```
public String explainJson()
                   throws Exception
```
    Submit an "EXPLAIN" statement, and return the JSON form of the plan.
    
    Returns:
    
    explain plan
    
    Throws:
    
    Exception - if the query fails
  - explain
```
public String explain(String format)
               throws Exception
```
    Throws:
    
    Exception
  - explainDetailed
```
public String explainDetailed(String format)
                       throws Exception
```
    Throws:
    
    Exception
  - planMatcher
```
public QueryBuilder.PlanMatcher planMatcher()
                                     throws Exception
```
    Submits explain plan statement and creates plan matcher instance based on return query plan.
    
    Returns:
    
    plan matcher
    
    Throws:
    
    Exception - if the query fails
  - detailedPlanMatcher
```
public QueryBuilder.PlanMatcher detailedPlanMatcher()
                                             throws Exception
```
    Submits explain plan statement and creates plan matcher instance based on return query plan with all attributes.
    
    Returns:
    
    plan matcher
    
    Throws:
    
    Exception - if the query fails
  - jsonPlanMatcher
```
public QueryBuilder.PlanMatcher jsonPlanMatcher()
                                         throws Exception
```
    Submits explain plan statement and creates plan matcher instance based on return query plan.
    
    Returns:
    
    plan matcher
    
    Throws:
    
    Exception - if the query fails
  - resultSet
```
public QueryResultSet resultSet()
```

Class QueryBuilder

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

query

sql

sql

plan

sql

physical

sqlResource

sqlResource

physicalResource

run

results

rowSet

rowSetIterator

rowSetReader

vectorValue

singletonLong

singletonDouble

singletonInt

singletonPeriod

singletonString

withListener

withEventListener

logCsv

log

log

log

printCsv

print

print

print

futureSummary

runAndWait

explainText

explainTextWithAllAttributes

explainJson

explain

explainDetailed

planMatcher

detailedPlanMatcher

jsonPlanMatcher

resultSet