English | 简体中文

api-docs / me.liuwj.ktorm.schema / Table

Table

open class Table<E : Entity<E>> : BaseTable<E> (source code)

Base class of Ktorm’s table objects. This class extends from BaseTable, additionally providing a binding mechanism
with Entity interfaces based on functions such as bindTo, references.

Table implements the doCreateEntity function from the parent class. The function automatically creates an
entity object using the binding configuration specified by bindTo and references, reading columns’ values from
the result set and filling them into corresponding entity properties.

To use this class, we need to define our entities as interfaces extending from Entity. Here is an example. More
documents can be found at https://ktorm.liuwj.me/en/entities-and-column-binding.html

interface Department : Entity<Department> {
val id: Int
var name: String
var location: String
}
object Departments : Table<Department>("t_department") {
val id by int("id").primaryKey().bindTo { it.id }
val name by varchar("name").bindTo { it.name }
val location by varchar("location").bindTo { it.location }
}

Constructors

NameSummary

<init>

Table(
    tableName: String,
    alias: String? = null,
    entityClass: KClass<E>? = null)

Base class of Ktorm’s table objects. This class extends from BaseTable, additionally providing a binding mechanism
with Entity interfaces based on functions such as bindTo, references.

Inherited Properties

NameSummary

alias

val alias: String?

The table’s alias.

columns

val columns: List<Column<*>>

Return all columns of the table.

entityClass

val entityClass: KClass<E>?

The entity class this table is bound to.

primaryKey

val primaryKey: Column<*>?

The primary key column of this table.

tableName

val tableName: String

The table’s name.

Functions

NameSummary

aliased

open fun aliased(alias: String): Table<E>

Return a new-created table object with all properties (including the table name and columns and so on) being
copied from this table, but applying a new alias given by the parameter.

bindTo

fun <C : Any> BaseTable.ColumnRegistration<C, E>.bindTo(
    selector: (E) -> C?
): BaseTable.ColumnRegistration<C, E>

Bind the column to nested properties, eg. employee.manager.department.id.

doCreateEntity

fun doCreateEntity(
    row: QueryRowSet,
    withReferences: Boolean
): E

Create an entity object from the specific row of query results.

references

fun <C : Any, R : Entity<R>> BaseTable.ColumnRegistration<C, E>.references(
    referenceTable: Table<R>,
    selector: (E) -> R?
): BaseTable.ColumnRegistration<C, E>

Bind the column to a reference table, equivalent to a foreign key in relational databases.
Entity sequence APIs would automatically left join all references (recursively) by default.

Inherited Functions

NameSummary

asExpression

fun asExpression(): TableExpression

Convert this table to a TableExpression.

copyDefinitionsFrom

fun copyDefinitionsFrom(src: BaseTable<*>): Unit

Copy column definitions from src to this table.

createEntity

fun createEntity(
    row: QueryRowSet,
    withReferences: Boolean = true
): E

Create an entity object from the specific row of query results. This function uses the binding configurations
of the table, filling column values into corresponding properties of the returned entity.

createEntityWithoutReferences

fun createEntityWithoutReferences(row: QueryRowSet): E

Create an entity object from the specific row without obtaining referenced entities’ data automatically.

equals

fun equals(other: Any?): Boolean

Indicates whether some other object is “equal to” this table.
Two tables are equal only if they are the same instance.

get

operator fun get(name: String): Column<*>

Obtain a column from this table by the name.

hashCode

fun hashCode(): Int

Return a hash code value for this table.

primaryKey

Mark the registered column as the primary key.

registerColumn

fun <C : Any> registerColumn(
    name: String,
    sqlType: SqlType<C>
): BaseTable.ColumnRegistration<C, E>

Register a column to this table with the given name and sqlType.

toString

open fun toString(): String

Return a string representation of this table.

transform

fun <C : Any, R : Any> BaseTable.ColumnRegistration<C, E>.transform(
    fromUnderlyingValue: (C) -> R,
    toUnderlyingValue: (R) -> C
): BaseTable.ColumnRegistration<R, E>

Transform the registered column’s SqlType to another. The transformed SqlType has the same typeCode and
typeName as the underlying one, and performs the specific transformations on column values.

Extension Functions

NameSummary

add

fun <E : Entity<E>> Table<E>.add(entity: E): Int

Insert the given entity into this table and return the affected record number.

batchInsert

fun <T : BaseTable<*>> T.batchInsert(
    block: BatchInsertStatementBuilder<T>.() -> Unit
): IntArray

Construct insert expressions in the given closure, then batch execute them and return the effected
row counts for each expression.

batchUpdate

fun <T : BaseTable<*>> T.batchUpdate(
    block: BatchUpdateStatementBuilder<T>.() -> Unit
): IntArray

Construct update expressions in the given closure, then batch execute them and return the effected
row counts for each expression.

bulkInsert

fun <T : BaseTable<*>> T.bulkInsert(
    block: BulkInsertStatementBuilder<T>.() -> Unit
): Int

Construct a bulk insert expression in the given closure, then execute it and return the effected row count.

crossJoin

fun BaseTable<*>.crossJoin(
    right: QuerySourceExpression,
    on: ColumnDeclaring<Boolean>? = null
): JoinExpression

fun BaseTable<*>.crossJoin(
    right: BaseTable<*>,
    on: ColumnDeclaring<Boolean>? = null
): JoinExpression

Join the right table and return a JoinExpression, translated to cross join in SQL.

delete

fun <T : BaseTable<*>> T.delete(
    predicate: (T) -> ColumnDeclaring<Boolean>
): Int

Delete the records in the table that matches the given predicate.

deleteAll

fun BaseTable<*>.deleteAll(): Int

Delete all the records in the table.

findMapByIds

fun <E : Entity<E>, K : Any> Table<E>.findMapByIds(
    ids: Collection<K>
): Map<K, E>

Obtain a map of entity objects by IDs, auto left joining all the reference tables.

innerJoin

fun BaseTable<*>.innerJoin(
    right: QuerySourceExpression,
    on: ColumnDeclaring<Boolean>? = null
): JoinExpression

fun BaseTable<*>.innerJoin(
    right: BaseTable<*>,
    on: ColumnDeclaring<Boolean>? = null
): JoinExpression

Join the right table and return a JoinExpression, translated to inner join in SQL.

insert

fun <T : BaseTable<*>> T.insert(
    block: AssignmentsBuilder.(T) -> Unit
): Int

Construct an insert expression in the given closure, then execute it and return the effected row count.

insertAndGenerateKey

fun <T : BaseTable<*>> T.insertAndGenerateKey(
    block: AssignmentsBuilder.(T) -> Unit
): Any

Construct an insert expression in the given closure, then execute it and return the auto-generated key.

insertOrUpdate

fun <T : BaseTable<*>> T.insertOrUpdate(
    block: InsertOrUpdateStatementBuilder.(T) -> Unit
): Int

Insert a record to the table, determining if there is a key conflict while it’s being inserted, and automatically
performs an update if any conflict exists.

insertOrUpdate

fun <T : BaseTable<*>> T.insertOrUpdate(
    block: InsertOrUpdateStatementBuilder.(T) -> Unit
): Int

Insert a record to the table, determining if there is a key conflict while it’s being inserted, and automatically
performs an update if any conflict exists.

joinReferencesAndSelect

fun BaseTable<*>.joinReferencesAndSelect(): Query

Return a new-created Query object, left joining all the reference tables, and selecting all columns of them.

leftJoin

fun BaseTable<*>.leftJoin(
    right: QuerySourceExpression,
    on: ColumnDeclaring<Boolean>? = null
): JoinExpression

fun BaseTable<*>.leftJoin(
    right: BaseTable<*>,
    on: ColumnDeclaring<Boolean>? = null
): JoinExpression

Join the right table and return a JoinExpression, translated to left join in SQL.

naturalJoin

fun BaseTable<*>.naturalJoin(
    right: QuerySourceExpression
): NaturalJoinExpression

fun BaseTable<*>.naturalJoin(
    right: BaseTable<*>
): NaturalJoinExpression

Join the right table and return a NaturalJoinExpression, translated to natural join in MySQL.

rightJoin

fun BaseTable<*>.rightJoin(
    right: QuerySourceExpression,
    on: ColumnDeclaring<Boolean>? = null
): JoinExpression

fun BaseTable<*>.rightJoin(
    right: BaseTable<*>,
    on: ColumnDeclaring<Boolean>? = null
): JoinExpression

Join the right table and return a JoinExpression, translated to right join in SQL.

select

fun BaseTable<*>.select(
    columns: Collection<ColumnDeclaring<*>>
): Query

fun BaseTable<*>.select(
    vararg columns: ColumnDeclaring<*>
): Query

Create a query object, selecting the specific columns or expressions from this table.

selectDistinct

fun BaseTable<*>.selectDistinct(
    columns: Collection<ColumnDeclaring<*>>
): Query

fun BaseTable<*>.selectDistinct(
    vararg columns: ColumnDeclaring<*>
): Query

Create a query object, selecting the specific columns or expressions from this table distinctly.

update

fun <T : BaseTable<*>> T.update(
    block: UpdateStatementBuilder.(T) -> Unit
): Int

Construct an update expression in the given closure, then execute it and return the effected row count.