api-docs / org.ktorm.entity / EntitySequence
EntitySequence
class EntitySequence<E : Any, T : BaseTable<E>>
(source code)Represents a sequence of entity objects. As the name implies, the style and use pattern of Ktorm’s entity sequence
APIs are highly similar to kotlin.sequences.Sequence and the extension functions in Kotlin standard lib, as it
provides many extension functions with the same names, such as filter, map, reduce, etc.
To create an EntitySequence, we can use the extension function sequenceOf:
val sequence = database.sequenceOf(Employees)
Now we got a default sequence, which can obtain all employees from the table. Please know that Ktorm doesn’t execute
the query right now. The sequence provides an iterator of type Iterator<Employee>
, only when we iterate the
sequence using the iterator, the query is executed. The following code prints all employees using a for-each loop:
for (employee in sequence) {
println(employee)
}
This class wraps a Query object, and it’s iterator exactly wraps the query’s iterator. When an entity sequence is
iterated, its internal query is executed, and the entityExtractor function is applied to create an entity object
for each row.
Most of the entity sequence APIs are provided as extension functions, which can be divided into two groups:
- Intermediate operations: these functions don’t execute the internal queries but return new-created sequence
objects applying some modifications. For example, the filter function creates a new sequence object with the filter
condition given by its parameter. The return types of intermediate operations are usually EntitySequence, so we
can call other sequence functions continuously in chaining style. - Terminal operations: the return types of these functions are usually a collection or a computed result, as they execute the queries right now, obtain their results and perform some calculations on them. E.g. toList, reduce, etc.
For the list of sequence operations available, see the extension functions below.
Constructors
Name | Summary |
---|---|
EntitySequence( Represents a sequence of entity objects. As the name implies, the style and use pattern of Ktorm's entity sequence APIs are highly similar to kotlin.sequences.Sequence and the extension functions in Kotlin standard lib, as it provides many extension functions with the same names, such as filter, map, reduce, etc. |
Properties
Name | Summary |
---|---|
val database: Database The Database instance that the internal query is running on. | |
val entityExtractor: (row: QueryRowSet) -> E The function used to extract entity objects for each result row. | |
val expression: SelectExpression The SQL expression to be executed by this sequence when obtaining elements. | |
val query: Query The internal query of this sequence to be executed, created by database and expression. | |
val rowSet: QueryRowSet The ResultSet object of the internal query, lazy initialized after first access, obtained from the database by executing the generated SQL. | |
val sourceTable: T The source table from which elements are obtained. | |
val sql: String The executable SQL string of the internal query. | |
val The total records count of this query ignoring the pagination params. | |
val totalRecordsInAllPages: Int The total records count of this query ignoring the pagination params. |
Functions
Name | Summary |
---|---|
Create a kotlin.sequences.Sequence instance that wraps this original entity sequence returning all the elements when being iterated. | |
Return an iterator over the elements of this sequence. | |
fun withExpression( Return a copy of this EntitySequence with the expression modified. |
Extension Functions
Name | Summary |
---|---|
Insert the given entity into this sequence and return the affected record number. | |
fun <E : Any, T : BaseTable<E>, C : Any> EntitySequence<E, T>.aggregateColumns( Perform an aggregation given by aggregationSelector for all elements in the sequence, and return the aggregate result. | |
fun <E : Any, T : BaseTable<E>> EntitySequence<E, T>.all( Return | |
Return fun <E : Any, T : BaseTable<E>> EntitySequence<E, T>.any( Return | |
Return a Map containing key-value pairs provided by transform function applied to elements of the given sequence. | |
Return a Map containing the elements from the given sequence indexed by the key returned from keySelector function applied to each element. fun <E : Any, K, V> EntitySequence<E, *>.associateBy( Return a Map containing the values provided by valueTransform and indexed by keySelector functions applied to elements of the given sequence. | |
fun <E : Any, K, M : MutableMap<in K, in E>> EntitySequence<E, *>.associateByTo( Populate and return the destination mutable map with key-value pairs, where key is provided by the keySelector function applied to each element of the given sequence and value is the element itself. fun <E : Any, K, V, M : MutableMap<in K, in V>> EntitySequence<E, *>.associateByTo( Populate and return the destination mutable map with key-value pairs, where key is provided by the keySelector function and value is provided by the valueTransform function applied to elements of the given sequence. | |
fun <E : Any, K, V, M : MutableMap<in K, in V>> EntitySequence<E, *>.associateTo( Populate and return the destination mutable map with key-value pairs provided by transform function applied to each element of the given sequence. | |
Return a Map where keys are elements from the given sequence and values are produced by the valueSelector function applied to each element. | |
fun <K : Entity<K>, V, M : MutableMap<in K, in V>> EntitySequence<K, *>.associateWithTo( Populate and return the destination mutable map with key-value pairs for each element of the given sequence, where key is the element itself and value is provided by the valueSelector function applied to that key. | |
fun <E : Any, T : BaseTable<E>> EntitySequence<E, T>.averageBy( Return the average value of the column given by selector in this sequence. | |
Remove all the elements of this sequence. The sequence will be empty after this function returns. | |
Return the number of elements in this sequence. fun <E : Any, T : BaseTable<E>> EntitySequence<E, T>.count( Return the number of elements matching the given predicate. | |
fun <E : Any, T : BaseTable<E>> EntitySequence<E, T>.drop( Returns a sequence containing all elements except first n elements. | |
Return an element at the given index or throws an IndexOutOfBoundsException if the index is out of bounds of this sequence. | |
fun <E : Any, T : BaseTable<E>> EntitySequence<E, T>.elementAtOrElse( Return an element at the given index or the result of calling the defaultValue function if the index is out of bounds of this sequence. | |
Return an element at the given index or | |
infix fun <T : Any> T.eq( Equal operator, translated to | |
fun <E : Any, T : BaseTable<E>> EntitySequence<E, T>.filter( Return a sequence containing only elements matching the given predicate. | |
fun <E : Any, T : BaseTable<E>> EntitySequence<E, T>.filterColumns( Return a sequence customizing the selected columns of the internal query. | |
fun <E : Any, T : BaseTable<E>> EntitySequence<E, T>.filterNot( Return a sequence containing only elements not matching the given predicate. | |
fun <E : Any, T : BaseTable<E>, C : MutableCollection<in E>> EntitySequence<E, T>.filterNotTo( Append all elements not matching the given predicate to the given destination. | |
fun <E : Any, T : BaseTable<E>, C : MutableCollection<in E>> EntitySequence<E, T>.filterTo( Append all elements matching the given predicate to the given destination. | |
fun <E : Any, T : BaseTable<E>> EntitySequence<E, T>.find( Return the first element matching the given predicate, or | |
fun <E : Any, T : BaseTable<E>> EntitySequence<E, T>.findLast( Return the last element matching the given predicate, or | |
Return the first element, or throws NoSuchElementException if the sequence is empty. fun <E : Any, T : BaseTable<E>> EntitySequence<E, T>.first( Return the first element matching the given predicate, or throws NoSuchElementException if element was not found. | |
Return the first element, or fun <E : Any, T : BaseTable<E>> EntitySequence<E, T>.firstOrNull( Return the first element matching the given predicate, or | |
Return a single list of all elements yielded from results of transform function being invoked on each element of original sequence. | |
fun <E : Any, R> EntitySequence<E, *>.flatMapIndexed( Return a single list of all elements yielded from results of transform function being invoked on each element and its index in the original sequence. | |
fun <E : Any, R, C : MutableCollection<in R>> EntitySequence<E, *>.flatMapIndexedTo( Append all elements yielded from results of transform function being invoked on each element and its index in the original sequence, to the given destination. | |
fun <E : Any, R, C : MutableCollection<in R>> EntitySequence<E, *>.flatMapTo( Append all elements yielded from results of transform function being invoked on each element of original sequence, to the given destination. | |
Accumulate value starting with initial value and applying operation from left to right to current accumulator value and each element. | |
fun <E : Any, R> EntitySequence<E, *>.foldIndexed( Accumulate value starting with initial value and applying operation from left to right to current accumulator value and each element with its index in the original sequence. | |
Perform the given action on each element. | |
Perform the given action on each element, providing sequential index with the element. | |
Group elements of the original sequence by the key returned by the given keySelector function applied to each element and return a map where each group key is associated with a list of corresponding elements. fun <E : Any, K, V> EntitySequence<E, *>.groupBy( Group values returned by the valueTransform function applied to each element of the original sequence by the key returned by the given keySelector function applied to the element and returns a map where each group key is associated with a list of corresponding values. | |
fun <E : Any, K, M : MutableMap<in K, MutableList<E>>> EntitySequence<E, *>.groupByTo( Group elements of the original sequence by the key returned by the given keySelector function applied to each element and put to the destination map each group key associated with a list of corresponding elements. fun <E : Any, K, V, M : MutableMap<in K, MutableList<V>>> EntitySequence<E, *>.groupByTo( Group values returned by the valueTransform function applied to each element of the original sequence by the key returned by the given keySelector function applied to the element and put to the destination map each group key associated with a list of corresponding values. | |
fun <E : Any, T : BaseTable<E>, K : Any> EntitySequence<E, T>.groupingBy( Create an EntityGrouping from the sequence to be used later with one of group-and-fold operations. | |
Return | |
Return | |
fun <E : Any, A : Appendable> EntitySequence<E, *>.joinTo( Append the string from all the elements separated using separator and using the given prefix and postfix. | |
fun <E : Any> EntitySequence<E, *>.joinToString( Create a string from all the elements separated using separator and using the given prefix and postfix. | |
fun <E : Any> EntitySequence<E, *>.last(): E Return the last element, or throws NoSuchElementException if the sequence is empty. fun <E : Any, T : BaseTable<E>> EntitySequence<E, T>.last( Return the last element matching the given predicate, or throws NoSuchElementException if no such element found. | |
fun <E : Any> EntitySequence<E, *>.lastOrNull(): E? Return the last element, or fun <E : Any, T : BaseTable<E>> EntitySequence<E, T>.lastOrNull( Return the last element matching the given predicate, or | |
fun <E : Any, T : BaseTable<E>> EntitySequence<E, T>.locking( Specify the locking clause of this query, an example generated SQL could be: | |
fun <E : Any, T : BaseTable<E>> EntitySequence<E, T>.locking( Specify the locking clause of this query, an example generated SQL could be: | |
Return a List containing the results of applying the given transform function to each element in the original sequence. | |
fun <E : Any, T : BaseTable<E>, C : Any> EntitySequence<E, T>.mapColumns( Customize the selected columns of the internal query by the given columnSelector function, and return a List containing the query results. | |
fun <E : Any, T : BaseTable<E>, C : Any> EntitySequence<E, T>.mapColumnsNotNull( Customize the selected columns of the internal query by the given columnSelector function, and return a List containing the non-null results. | |
fun <E : Any, T : BaseTable<E>, C : Any, R : MutableCollection<in C>> EntitySequence<E, T>.mapColumnsNotNullTo( Customize the selected columns of the internal query by the given columnSelector function, and append non-null results to the given destination. | |
fun <E : Any, T : BaseTable<E>, C : Any, R : MutableCollection<in C?>> EntitySequence<E, T>.mapColumnsTo( Customize the selected columns of the internal query by the given columnSelector function, and append the query results to the given destination. | |
Return a List containing the results of applying the given transform function to each element and its index in the original sequence. | |
fun <E : Any, R : Any> EntitySequence<E, *>.mapIndexedNotNull( Return a List containing only the non-null results of applying the given transform function to each element and its index in the original sequence. | |
fun <E : Any, R : Any, C : MutableCollection<in R>> EntitySequence<E, *>.mapIndexedNotNullTo( Apply the given transform function to each element and its index in the original sequence and append only the non-null results to the given destination. | |
fun <E : Any, R, C : MutableCollection<in R>> EntitySequence<E, *>.mapIndexedTo( Apply the given transform function to each element and its index in the original sequence and append the results to the given destination. | |
Return a List containing only the non-null results of applying the given transform function to each element in the original sequence. | |
fun <E : Any, R : Any, C : MutableCollection<in R>> EntitySequence<E, *>.mapNotNullTo( Apply the given transform function to each element in the original sequence and append only the non-null results to the given destination. | |
fun <E : Any, R, C : MutableCollection<in R>> EntitySequence<E, *>.mapTo( Apply the given transform function to each element of the original sequence and append the results to the given destination. | |
fun <E : Any, T : BaseTable<E>, C : Comparable<C>> EntitySequence<E, T>.maxBy( Return the max value of the column given by selector in this sequence. | |
fun <E : Any, T : BaseTable<E>, C : Comparable<C>> EntitySequence<E, T>.minBy( Return the min value of the column given by selector in this sequence. | |
infix fun <T : Any> T.neq( Not-equal operator, translated to | |
Return fun <E : Any, T : BaseTable<E>> EntitySequence<E, T>.none( Return | |
infix fun <T : Any> T.notEq( Not-equal operator, translated to | |
Accumulate value starting with the first element and applying operation from left to right to current accumulator value and each element. | |
Accumulate value starting with the first element and applying operation from left to right to current accumulator value and each element with its index in the original sequence. | |
fun <E : Any> EntitySequence<E, *>.reduceIndexedOrNull( Accumulate value starting with the first element and applying operation from left to right to current accumulator value and each element with its index in the original sequence. | |
Accumulate value starting with the first element and applying operation from left to right to current accumulator value and each element. | |
fun <E : Any, T : BaseTable<E>> EntitySequence<E, T>.removeIf( Remove all the elements of this sequence that satisfy the given predicate. | |
Return the single element, or throws an exception if the sequence is empty or has more than one element. fun <E : Any, T : BaseTable<E>> EntitySequence<E, T>.single( Return the single element matching the given predicate, or throws exception if there is no or more than one matching element. | |
Return single element, or fun <E : Any, T : BaseTable<E>> EntitySequence<E, T>.singleOrNull( Return the single element matching the given predicate, or | |
fun <E : Any, T : BaseTable<E>> EntitySequence<E, T>.sortedBy( Return a sequence sorting elements by multiple columns, in ascending or descending order. For example, fun <E : Any, T : BaseTable<E>> EntitySequence<E, T>.sortedBy( Return a sequence sorting elements by a column, in ascending or descending order. For example, fun <E : Any, T : BaseTable<E>> EntitySequence<E, T>.sortedBy( Return a sequence sorting elements by the specific column in ascending order. | |
fun <E : Any, T : BaseTable<E>> EntitySequence<E, T>.sortedByDescending( Return a sequence sorting elements by the specific column in descending order. | |
fun <E : Any, T : BaseTable<E>, C : Number> EntitySequence<E, T>.sumBy( Return the sum of the column given by selector in this sequence. | |
fun <E : Any, T : BaseTable<E>> EntitySequence<E, T>.take( Returns a sequence containing first n elements. | |
fun <E : Any, C : MutableCollection<in E>> EntitySequence<E, *>.toCollection( Append all elements to the given destination collection. | |
fun <E : Any> EntitySequence<E, *>.toHashSet(): HashSet<E> Return a HashSet containing all the elements of this sequence. | |
fun <E : Any> EntitySequence<E, *>.toList(): List<E> Return a List containing all the elements of this sequence. | |
fun <E : Any> EntitySequence<E, *>.toMutableList(): MutableList<E> Return a MutableList containing all the elements of this sequence. | |
fun <E : Any> EntitySequence<E, *>.toMutableSet(): MutableSet<E> Return a MutableSet containing all the elements of this sequence. | |
fun <E : Any> EntitySequence<E, *>.toSet(): Set<E> Return a Set containing all the elements of this sequence. | |
fun <E> EntitySequence<E, *>.toSortedSet(): SortedSet<E> where E : Any, E : Comparable<E> fun <E> EntitySequence<E, *>.toSortedSet( Return a SortedSet containing all the elements of this sequence. | |
Update properties of the given entity to the database and return the affected record number. | |
fun <E : Any> EntitySequence<E, *>.withIndex(): Sequence<IndexedValue<E>> Return a lazy Sequence that wraps each element of the original sequence into an IndexedValue containing the index of that element and the element itself. |