@AdHoc

Documentation

Home » Documentation » Using VoltDB

@AdHoc

@AdHoc — Executes an SQL statement specified at runtime.

Synopsis

@AdHoc String SQL-statement

Description

The @AdHoc system procedure lets you perform arbitrary SQL queries on a running VoltDB database.

You can execute multiple SQL queries in a single call to @AdHoc by separating the individual queries with semicolons. When you do this, the queries are performed as a single transaction. That is, the queries all succeed as a group or they all roll back if any of them fail.

Performance of ad hoc queries is optimized, where possible. However, it is important to note that ad hoc queries are not pre-compiled, like queries in stored procedures. Therefore, use of stored procedures is recommended over @AdHoc for frequent, repetitive, or performance-sensitive queries.

Return Values

Returns one VoltTable for each query, with as many rows as there are records returned by the query. The column names and datatypes match the names and datatypes of the fields returned by the query.

Examples

The following program example uses @AdHoc to execute an SQL SELECT statement and display the number of reservations for a specific customer in the flight reservation database.

try {
    VoltTable[] results = client.callProcedure("@AdHoc",
       "SELECT COUNT(*) FROM RESERVATION " +
       "WHERE CUSTOMERID=" + custid).getResults();
    System.out.printf("%d reservations found.\n",
        results[0].fetchRow(0).getLong(0));
}
catch (Exception e) {
    e.printStackTrace();
}

Note that you do not need to explicitly invoke @AdHoc when using sqlcmd. You can type your query directly into the sqlcmd prompt, like so:

$ sqlcmd
1> SELECT COUNT(*) FROM RESERVATION WHERE CUSTOMERID=12345;