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 Lustra::SQL::OperationNotPermittedError

Returns self and therefore can be chained

Get a range of models

Basically a fancy way to write OFFSET x LIMIT 1

Basically a fancy way to write OFFSET x LIMIT 1

Alias for Collection#<<

Check whether the query return any row.

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 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 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 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"})

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

Build a new object and setup the fields like setup in the condition tuple. Just after building, save the object.

Build a new object and setup the fields like setup in the condition tuple. Just after building, save the object.

Build a new object and setup the fields like setup in the condition tuple. Just after building, save the object.

Build a new object and setup the fields like setup in the condition tuple. Just after building, save the object.

Build a new object and setup the fields like setup in the condition tuple. Just after building, save the object. But instead of returning self if validation failed, raise Lustra::Model::InvalidError exception

Build a new object and setup the fields like setup in the condition tuple. Just after building, save the object. But instead of returning self if validation failed, raise Lustra::Model::InvalidError exception

Build a new object and setup the fields like setup in the condition tuple. Just after building, save the object. But instead of returning self if validation failed, raise Lustra::Model::InvalidError exception

Build a new object and setup the fields like setup in the condition tuple. Just after building, save the object. But instead of returning self if validation failed, raise Lustra::Model::InvalidError exception

Delete all the rows which would have been returned by this collection WITHOUT callbacks. This is a bulk operation that doesn't load models into memory. Is equivalent to collection.to_delete.execute

User.query.where { active == false }.delete_all

Returns self for chaining.

Destroy all the rows which would have been returned by this collection WITH callbacks. This loads each model into memory and calls destroy on it, triggering all :delete callbacks. Use #delete_all if you don't need callbacks (much faster for large datasets).

# With callbacks - slower but safe
User.query.where { active == false }.destroy_all

# Without callbacks - faster
User.query.where { active == false }.delete_all

Returns self for chaining.

Duplicate the query

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

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.

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

A convenient way to write where { condition }.first(fetch_columns)

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

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

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

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

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

Find a model by column values. Returns nil if not found. This is an alias for #find(**tuple) with better naming.

user = User.query.find_by(email: "test@example.com")
user = User.query.where { active == true }.find_by(role: "admin")

Find a model by column values. Returns nil if not found. This is an alias for #find(**tuple) with better naming.

user = User.query.find_by(email: "test@example.com")
user = User.query.where { active == true }.find_by(role: "admin")

Find a model by column values. Raises error if not found. This is an alias for #find!(**tuple) with better naming.

user = User.query.find_by!(email: "test@example.com")

Find a model by column values. Raises error if not found. This is an alias for #find!(**tuple) with better naming.

user = User.query.find_by!(email: "test@example.com")

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

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.

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.

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.

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.

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

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

FULL_OUTER JOIN using association name (auto-detects join conditions)

Convenient shortcut to get an array of primary key values. Equivalent to pluck_col(T.__pkey__) but more readable.

User.query.where { active == true }.ids
# => [1, 2, 3, 4, 5]

Post.query.where { published == true }.ids
# => [10, 25, 42, 100]

Returns an array of primary key values (typically Array(Int64) or Array(Int32)).

INNER JOIN using association name (auto-detects join conditions)

Return the model class for this collection

Join a relation using association name (auto-detects join conditions) Overrides the parent join to handle association names without blocks

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

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

LEFT JOIN using association name (auto-detects join conditions)

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

Parent model context for autosave functionality

Parent model context for autosave functionality

RIGHT JOIN using association name (auto-detects join conditions)

Save a model and handle append_operation for has_many through relationships This allows the build + save pattern to work

Create an array from the query.

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 Lustra::SQL::OperationNotPermittedError

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

Update all the rows which would have been returned by this collection without loading the models into memory. Bypasses validations and callbacks.

This is useful for bulk updates where you don't need to run validations or callbacks on each individual model.

# Update all inactive users to have a specific status
affected = User.query.where { active == false }.update_all(status: "inactive")
puts "Updated #{affected} users"

# Update multiple columns at once
Post.query.where { published == false }.update_all(published: true, published_at: Time.utc)

# With complex conditions
User.query.where { created_at < 1.year.ago }.update_all(archived: true)

Returns the number of rows affected.

Update all the rows which would have been returned by this collection without loading the models into memory. Bypasses validations and callbacks.

This is useful for bulk updates where you don't need to run validations or callbacks on each individual model.

# Update all inactive users to have a specific status
affected = User.query.where { active == false }.update_all(status: "inactive")
puts "Updated #{affected} users"

# Update multiple columns at once
Post.query.where { published == false }.update_all(published: true, published_at: Time.utc)

# With complex conditions
User.query.where { created_at < 1.year.ago }.update_all(archived: true)

Returns the number of rows affected.

Update all the rows which would have been returned by this collection without loading the models into memory. Bypasses validations and callbacks.

This is useful for bulk updates where you don't need to run validations or callbacks on each individual model.

# Update all inactive users to have a specific status
affected = User.query.where { active == false }.update_all(status: "inactive")
puts "Updated #{affected} users"

# Update multiple columns at once
Post.query.where { published == false }.update_all(published: true, published_at: Time.utc)

# With complex conditions
User.query.where { created_at < 1.year.ago }.update_all(archived: true)

Returns the number of rows affected.