client/io.github.octaviusframework.client.query/RawQuery

RawQuery

class RawQuery @PublishedApi constructor(provider: SessionProvider, sql: String) : RunnableQuery<RawQuery>

SQL written by hand, with @name parameters, carrying the same terminal methods every builder carries.

What separates it from the builders is not reach. Every clause they take is SQL and is passed through, so a lateral join goes in from, a window function or DISTINCT ON in select, and recursive() is declared on all four of them - there is not much they cannot say. What they do is the mechanical part: the keywords and their order, the column list paired with its own placeholders, and the clauses that disappear when they have nothing to say. This is for the statement you would rather write whole - one that already exists, one that came from somewhere else, or one that assembling a clause at a time buys nothing.

It is also the only query with an execute, which is a different protocol rather than another terminal: DDL, SET and several statements in one round trip live here because no builder can reach them.

The SQL it was given comes back out of toSql like any other query's, rather than through a property of its own.

Constructors

RawQuery

@PublishedApi

internal constructor(provider: SessionProvider, sql: 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

Switches this query to the result style: every terminal on the returned object hands back a DataResult instead of throwing.

asStep

fun asStep(): StepBuilder

Turns this query into a step of a TransactionPlan instead of something to run now.

copyConvertersFrom

internal fun copyConvertersFrom(other: RunnableQuery<*>)

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

execute

fun execute(ignoreRows: Boolean = false)

Runs the statement and discards whatever it produced - DDL, SET, administrative commands.

fetchField

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

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, crossinline block: (T) -> Unit)

inline fun <T> forEachField(vararg params: Pair<String, Any?>, fetchSize: Int, crossinline 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, crossinline block: (T) -> Unit)

inline fun <T : Any> forEachObject(vararg params: Pair<String, Any?>, fetchSize: Int, crossinline 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)

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.

preparedQuery

@PublishedApi

internal fun OctaviusSessionOperations.preparedQuery(): NamedParameterQuery

Builds the driver query a terminal is about to run, with this query's own converters on it.

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.

registerParameterConverter

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

Registers a ParameterConverter for this query and nothing else.

registerResultConverter

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

Registers a ResultConverter for this query and nothing else.

toSql

fun toSql(): String

Renders the SQL this query would send.

update

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

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

Runs the statement and returns how many rows it affected.