client/io.github.octaviusframework.client.query/SelectQuery

SelectQuery

class SelectQuery @PublishedApi constructor(provider: SessionProvider, selectClause: String) : RunnableQuery<SelectQuery>

A SELECT under construction. Every clause takes SQL and passes it through; the builder supplies the keywords and their order, and leaves out a clause given null or blank, so a filter assembled at runtime can go straight in.

val senators = db.select("id", "cognomen", "province_id")
    .from("senate")
    .where(filter.sql)          // null or empty leaves out the WHERE entirely
    .orderBy("cognomen")
    .page(page = 0, size = 20)
    .fetchObjects<Senator>(filter.params)

Constructors

SelectQuery

@PublishedApi

internal constructor(provider: SessionProvider, selectClause: String)

Properties

queryParameterConverters

@PublishedApi

internal var queryParameterConverters: MutableList<ParameterConverter<*>>?

queryProvider

@PublishedApi

internal val queryProvider: SessionProvider

Decides which session the terminals run on.

queryResultConverters

@PublishedApi

internal var queryResultConverters: MutableList<ResultConverter<*, *>>?

Functions

asResult

fun asResult(): ResultQuery

This query with terminals that return a DataResult instead of throwing, on the boundary dbResult applies - a fetch*Strict that found no row still throws.

asStep

fun asStep(): StepBuilder

Turns this query into a step of a TransactionPlan instead of running it. The parameters given at the step's terminal may hold TransactionValues pointing at earlier steps.

copy

fun copy(): SelectQuery

Returns an independent copy, so that variants can be built from a shared base.

copyConvertersFrom

internal fun copyConvertersFrom(other: RunnableQuery<*>)

Carries registered converters into a builder's copy(), alongside whatever clauses it copies.

executeUpdate

fun executeUpdate(params: Map<String, Any?> = emptyMap()): Long

fun executeUpdate(vararg params: Pair<String, Any?>): Long

Runs the statement and returns how many rows it affected.

fetchField

inline fun <T> fetchField(params: Map<String, Any?> = emptyMap()): T

Runs the query and returns the first column of its single row as T. A nullable T gives null for a missing row or a NULL; a non-nullable one throws for either.

inline fun <T> fetchField(vararg params: Pair<String, Any?>): T

Runs the query and returns the first column of its single row as T.

fetchFields

inline fun <T> fetchFields(params: Map<String, Any?> = emptyMap()): List<T>

inline fun <T> fetchFields(vararg params: Pair<String, Any?>): List<T>

Runs the query and returns the first column of every row as T.

fetchFieldStrict

inline fun <T> fetchFieldStrict(params: Map<String, Any?> = emptyMap()): T

inline fun <T> fetchFieldStrict(vararg params: Pair<String, Any?>): T

As fetchField, but the query must return exactly one row rather than at most one.

fetchObject

inline fun <T : Any> fetchObject(params: Map<String, Any?> = emptyMap()): T?

inline fun <T : Any> fetchObject(vararg params: Pair<String, Any?>): T?

Runs the query and maps its single row onto T, or null where none matched.

fetchObjects

inline fun <T : Any> fetchObjects(params: Map<String, Any?> = emptyMap()): List<T>

inline fun <T : Any> fetchObjects(vararg params: Pair<String, Any?>): List<T>

Runs the query and maps every row onto T.

fetchObjectStrict

inline fun <T : Any> fetchObjectStrict(params: Map<String, Any?> = emptyMap()): T

inline fun <T : Any> fetchObjectStrict(vararg params: Pair<String, Any?>): T

Runs the query and maps its single row onto T, throwing where the count was anything but one.

fetchRow

fun fetchRow(params: Map<String, Any?> = emptyMap()): Row?

fun fetchRow(vararg params: Pair<String, Any?>): Row?

Runs the query and returns its single row, or null where none matched.

fetchRows

fun fetchRows(params: Map<String, Any?> = emptyMap()): List<Row>

fun fetchRows(vararg params: Pair<String, Any?>): List<Row>

Runs the query and returns every row.

fetchRowStrict

fun fetchRowStrict(params: Map<String, Any?> = emptyMap()): Row

fun fetchRowStrict(vararg params: Pair<String, Any?>): Row

Runs the query and returns its single row, throwing where the count was anything but one.

forEachField

inline fun <T> forEachField(params: Map<String, Any?> = emptyMap(), fetchSize: Int, noinline block: (T) -> Unit)

Runs the query and hands the first column of each row, as T, to block as forEachRow does.

inline fun <T> forEachField(vararg params: Pair<String, Any?>, fetchSize: Int, noinline block: (T) -> Unit)

Runs the query and hands the first column of each row, as T, to block as it arrives.

forEachObject

inline fun <T : Any> forEachObject(params: Map<String, Any?> = emptyMap(), fetchSize: Int, noinline block: (T) -> Unit)

Runs the query and hands each row, mapped onto T, to block as it arrives, as forEachRow does.

inline fun <T : Any> forEachObject(vararg params: Pair<String, Any?>, fetchSize: Int, noinline block: (T) -> Unit)

Runs the query and hands each row, mapped onto T, to block as it arrives.

forEachRow

fun forEachRow(params: Map<String, Any?> = emptyMap(), fetchSize: Int, block: (Row) -> Unit)

Runs the query and hands each row to block as it arrives, so a result too large to hold is streamed. block runs while the result is still being read, and a query from inside it is refused with CONNECTION_BUSY.

fun forEachRow(vararg params: Pair<String, Any?>, fetchSize: Int, block: (Row) -> Unit)

Runs the query and hands each row to block as it arrives, in batches of fetchSize.

from

fun from(source: String): SelectQuery

Sets the FROM clause, passed through as written: "legions l JOIN provinces p ON l.province_id = p.id", "UNNEST(@ids) AS id", "calculate_tribute(@province, @year)".

fromSubquery

fun fromSubquery(subquery: String, alias: String? = null): SelectQuery

Sets the FROM clause to a subquery, parenthesised and optionally aliased.

groupBy

fun groupBy(columns: String?): SelectQuery

Sets the GROUP BY columns. null or blank leaves the clause out.

having

fun having(condition: String?): SelectQuery

Sets the HAVING condition, which requires a GROUP BY. null or blank leaves the clause out.

limit

fun limit(count: Long?): SelectQuery

Sets LIMIT. null leaves it out.

locking

fun locking(clause: String?): SelectQuery

Sets the locking clause, FOR included, since several may follow one another: "FOR UPDATE", "FOR UPDATE OF l FOR SHARE OF p NOWAIT". null or blank leaves it out. Outside a transaction the lock ends with the statement.

offset

fun offset(position: Long?): SelectQuery

Sets OFFSET. null leaves it out, as does 0.

orderBy

fun orderBy(ordering: String?): SelectQuery

Sets the ORDER BY clause. null or blank leaves the clause out.

page

fun page(page: Long, size: Long): SelectQuery

Sets LIMIT and OFFSET for page, counted from zero, of size rows.

preparedQuery

@PublishedApi

internal fun OctaviusSessionOperations.preparedQuery(): NamedParameterQuery

The driver query every terminal runs, carrying this query's own converters.

querySql

internal open override fun querySql(): String

Renders the SQL. Called once per terminal call, so a builder may put off assembling it until here.

recursive

fun recursive(): SelectQuery

Marks the WITH clause RECURSIVE.

registerParameterConverter

fun registerParameterConverter(converter: ParameterConverter<*>): SelectQuery

Registers a ParameterConverter for this query alone, on the terms of registerResultConverter.

registerResultConverter

fun registerResultConverter(converter: ResultConverter<*, *>): SelectQuery

Registers a ResultConverter for this query alone, consulted ahead of the session's. A later registration here wins over an earlier one.

toCountQuery

fun toCountQuery(): SelectQuery

A query counting the rows this one matches across every page, for the total a paged list shows.

toSql

fun toSql(): String

Renders the SQL this query would send. A query never carries parameters, so its @name placeholders survive embedding it in a WITH, a subquery or a UNION, and are bound by whoever runs the outer statement. Not cached: a builder walks its clauses again on every call.

where

fun where(condition: String?): SelectQuery

Sets the WHERE condition. null or blank leaves the clause out.

window

fun window(definitions: String?): SelectQuery

Sets the WINDOW clause, as SQL: the named windows the select list and ORDER BY refer to, "w AS (PARTITION BY province ORDER BY strength DESC)". null or blank leaves the clause out.

with

fun with(name: String, query: String): SelectQuery

Adds a common table expression. Call it more than once for more than one.