The returning mode of the SQL statement.

How many rows the statement answers with, which decides what the generated method returns. It is written returning in the front matter.

The row type comes from elsewhere — resultRowType or resultRowConverter , or a Map<String, Object> when neither is named. This setting only wraps it.

single is for a statement that can answer with at most one row. A second row is silently ignored unless throwOnMultipleResults is on, which is worth turning on wherever you believe the query really is unique.

cursor reads rows as the stream is consumed, so a result larger than memory is fine — but the stream holds the ResultSet, the statement and, for the DataSource form, the connection until it is closed. Close it. Most drivers also need a fetch size and auto-commit off before they stream rather than buffer, and both are connection settings.

none on a write answers with the number of rows changed unless writesReturnUpdateCount says otherwise. A write that returns rows — insert ... returning * — takes single or multiple like a read.

Configuration Options

Option: ‘single’

At most one row, so the method answers with an Optional:

public final class TenantRepository {

    public Optional<Tenant> findTenant(final UUID id) {
        // ... rest of generated code
    }

}

Option: ‘multiple’

Every row, read into a list before the method returns:

public final class TenantRepository {

    public List<Tenant> findTenants(final UUID accountId) {
        // ... rest of generated code
    }

}

Option: ‘cursor’

Rows as they are read, for a result that need not fit in memory. Close the stream:

public final class TenantRepository {

    public Stream<Tenant> findTenants(final UUID accountId) {
        // ... rest of generated code
    }

}

Option: ’none'

No rows. A write answers with the number it changed:

public final class TenantRepository {

    public int insertTenant(final UUID id, final String slug) {
        // ... rest of generated code
    }

}

Related Options

Also in this group: annotations , catchAndRethrow , createConnection , description , executeBatch , executeOnce , generateConnectionOverloads , generateResultRowType , injectConverter , name , parameters , repository , resultRowColumns , resultRowConverter , resultRowType , throwOnMultipleResults , type , validateSchema , vendor , writesReturnUpdateCount .

Front Matter

In order to configure this option, place the following code in the front matter of your SQL statement:

-- returning: single
SELECT  something
FROM    your_database_schema
WHERE   some_column = :some_value