class

Clear::Model::CollectionBase(T)

Inherits Clear::SQL::SelectBuilder < Clear::SQL::Query::WithPagination < Clear::SQL::Query::BeforeQuery < Clear::SQL::Query::Change < Clear::SQL::Query::Connection < Clear::SQL::Query::Pluck < Clear::SQL::Query::Fetch < Clear::SQL::Query::Execute < Clear::SQL::Query::Lock < Clear::SQL::Query::Window < Clear::SQL::Query::CTE < Clear::SQL::Query::Aggregate < Clear::SQL::Query::OffsetLimit < Clear::SQL::Query::GroupBy < Clear::SQL::Query::OrderBy < Clear::SQL::Query::Having < Clear::SQL::Query::Where < Clear::SQL::Query::Join < Clear::SQL::Query::From < Clear::SQL::Query::Select < Enumerable < Reference < Object

CollectionBase(T) is the base class for collection of model. Collection of model are a SQL SELECT query mapping & building system. They are Enumerable and are `Clear::SQL::SelectBuilder` behavior; therefore, they can be used array-like and are working with low-level SQL Building.

The CollectionBase(T) is extended by each model. For example, generating the model MyModel will generate the class MyModel::Collection which inherits from CollectionBase(MyModel)

Collection are instantiated using Model.query method.

Class methods

item_class

Return the model class for this collection

Instance methods

<<(item : T)

Add an item to the current collection.

If the current collection is not originated from a has_many or has_many through: relation, calling << over the collection will raise a Clear::SQL::OperationNotPermittedError

Returns self and therefore can be chained

[](range : Range(Number, Number), fetch_columns = false) : Array(T)

Get a range of models

[](off, fetch_columns = false) : T

Basically a fancy way to write OFFSET x LIMIT 1

[]?(off, fetch_columns = false) : T | Nil

Basically a fancy way to write OFFSET x LIMIT 1

add(item : T)

Alias for Collection#<<

any?

Check whether the query return any row.

build(x : NamedTuple) : T

Build a new collection; if the collection comes from a has_many relation (e.g. my_model.associations.build), the foreign column which store the primary key of my_model will be setup by default, preventing you to forget it. You can pass extra parameters using a named tuple: my_model.associations.build({a_column: "value"})

build

Build a new collection; if the collection comes from a has_many relation (e.g. my_model.associations.build), the foreign column which store the primary key of my_model will be setup by default, preventing you to forget it.

count(type : X.class = Int64) forall X

Use SQL COUNT over your query, and return this number as a Int64

delete_all

Delete all the rows which would have been returned by this collection. Is equivalent to collection.to_delete.execute

dup

Duplicate the current request. Select query are mutable objects, and many of the methods will change the state of the collection:

collection = User.query # SELECT * FROM users;
collection.select("id") # SELECT id FROM users;
collection.select("id") # SELECT id, id FROM users;

Therefore, you may want to use dup to duplicate the current state of the collection.

each(fetch_columns = false, &block : T -> )

Build the SQL, send the query then iterate through each models gathered by the request.

each_with_cursor(batch = 1000, fetch_columns = false, &block : T -> )

Build the SQL, send the query then iterate through each models gathered by the request. Use a postgres cursor to avoid memory bloating. Useful to fetch millions of rows at once.

empty?

Inverse of any?, return true if the request return no rows.

find(fetch_columns = false, &) : T | Nil

A convenient way to write where{ condition }.first

find(tuple : NamedTuple, fetch_columns = false) : T | Nil

A convenient way to write where({any_column: "any_value"}).first

find(x) : T | Nil

Returns a model using primary key equality Returns nil if not found.

find!(fetch_columns = false, &) : T

A convenient way to write where({any_column: "any_value"}).first!

find!(tuple : NamedTuple, fetch_columns = false) : T

A convenient way to write where{ condition }.first!

find!(x) : T

Returns a model using primary key equality. Raises error if the model is not found.

find_or_build

find_or_build

Try to fetch a row. If not found, build a new object and setup the fields like setup in the condition tuple.

find_or_create

Try to fetch a row. If not found, build a new object and setup the fields like setup in the condition tuple. Just after building, save the object.

find_or_create

Try to fetch a row. If not found, build a new object and setup the fields like setup in the condition tuple. Just after building, save the object.

first(fetch_columns = false) : T | Nil

Get the first row from the collection query. if not found, return nil

first!(fetch_columns = false) : T

Get the first row from the collection query. if not found, throw an error

item_class

Return the model class for this collection

last(fetch_columns = false) : T | Nil

Get the last row from the collection query. if not found, return nil

last!(fetch_columns = false) : T

Get the last row from the collection query. if not found, throw an error

map(fetch_columns = false, &block : T -> X) : Array(X) forall X

Build the SQL, send the query then build and array by applying the block transformation over it.

tags

to_a(fetch_columns = false) : Array(T)

Create an array from the query.

unlink(item : T)

Unlink the model currently referenced through a relation has_many through

If the current colleciton doesn't come from a has_many through relation, this method will throw Clear::SQL::OperationNotPermittedError

Returns true if unlinking is successful (e.g. one or more rows have been updated), or false otherwise