Returns the record at the given index.

If no record can be found at the given index, then an IndexError exception is raised.

Returns the records corresponding to the passed range.

If no records match the passed range, an IndexError exception is raised. If the current query set was already "consumed" (records were retrieved from the database), an array of records will be returned. Otherwise, another sliced query set will be returned.

Returns the record at the given index.

nil is returned if no record can be found at the given index.

Returns the records corresponding to the passed range.

nil is returned if no records match the passed range. If the current query set was already "consumed" (records were retrieved from the database), an array of records will be returned. Otherwise, another sliced query set will be returned.

Returns a cloned version of the current query set matching all records.

Returns the number of records that are targeted by the current query set.

Creates a model instance and saves it to the database if it is valid.

The new model instance is initialized by using the attributes defined in the kwargs double splat argument. Regardless of whether it is valid or not (and thus persisted to the database or not), the initialized model instance is returned by this method:

query_set = Post.all
query_set.create(title: "My blog post")

Creates a model instance and saves it to the database if it is valid.

This method provides the exact same behaviour as #create with the ability to define a block that is executed for the new object. This block can be used to directly initialize the object before it is persisted to the database:

query_set = Post.all
query_set.create(title: "My blog post") do |post|
  post.complex_attribute = compute_complex_attribute
end

Creates a model instance and saves it to the database if it is valid.

The model instance is initialized using the attributes defined in the kwargs double splat argument. If the model instance is valid, it is persisted to the database ; otherwise a Marten::DB::Errors::InvalidRecord exception is raised.

query_set = Post.all
query_set.create!(title: "My blog post")

Creates a model instance and saves it to the database if it is valid.

This method provides the exact same behaviour as #create! with the ability to define a block that is executed for the new object. This block can be used to directly initialize the object before it is persisted to the database:

query_set = Post.all
query_set.create!(title: "My blog post") do |post|
  post.complex_attribute = compute_complex_attribute
end

Deletes the records corresponding to the current query set and returns the number of deleted records.

By default, related objects will be deleted by following the deletion strategy defined in each foreign key field if applicable, unless the raw argument is set to true.

When the raw argument is set to true, a raw SQL delete statement will be used to delete all the records matching the currently applied filters. Note that using this option could cause errors if the underlying database enforces referential integrity.

Returns a new query set that will use SELECT DISTINCT in its query.

By doing so it is possible to eliminate any duplicated row in the query set results:

query_set = Post.all.distinct

Returns a new query set that will use SELECT DISTINCT ON in its query

By doing so it is possible to eliminate any duplicated row based on the specified fields:

query_set = Post.all.distinct(:title)

It should be noted that it is also possible to follow associations of direct related models too by using the double underscores notation(__). For example the following query will select distinct records based on a joined "author" attribute:

query_set = Post.all.distinct(:author__name)

Allows to iterate over the records that are targeted by the current query set.

This method can be used to define a block that iterates over the records that are targeted by a query set:

Post.all.each do |post|
  # Do something
end

Returns a query set whose records do not match the given query node object.

Returns a query set whose records do not match the given set of filters.

This method returns a Marten::DB::Query::Set object. The filters passed to this method method must be specified using the predicate format:

query_set = Post.all
query_set.exclude(title: "Test")
query_set.exclude(title__startswith: "A")

If multiple filters are specified, they will be joined using an AND operator at the SQL level.

Returns a query set whose records do not match the given set of advanced filters.

This method returns a Marten::DB::Query::Set object and allows to define complex database queries involving AND and OR operators. It yields a block where each filter has to be wrapped using a q(...) expression. These expressions can then be used to build complex queries such as:

query_set = Post.all
query_set.exclude { (q(name: "Foo") | q(name: "Bar")) & q(is_published: True) }

Returns true if the current query set matches at least one record, or false otherwise.

Returns a query set whose records match the given query node object.

Returns a query set matching a specific set of filters.

This method returns a Marten::DB::Query::Set object. The filters passed to this method method must be specified using the predicate format:

query_set = Post.all
query_set.filter(title: "Test")
query_set.filter(title__startswith: "A")

If multiple filters are specified, they will be joined using an AND operator at the SQL level.

Returns a query set matching a specific set of advanced filters.

This method returns a Marten::DB::Query::Set object and allows to define complex database queries involving AND and OR operators. It yields a block where each filter has to be wrapped using a q(...) expression. These expressions can then be used to build complex queries such as:

query_set = Post.all
query_set.filter { (q(name: "Foo") | q(name: "Bar")) & q(is_published: True) }

Returns the first record that is matched by the query set, or nil if no records are found.

Returns the first record that is matched by the query set, or raises a NilAssertionError error otherwise.

Returns the model instance matching a specific query node object, or nil if no record is found.

Returns the model instance matching the given set of filters.

Model fields such as primary keys or fields with a unique constraint should be used here in order to retrieve a specific record:

query_set = Post.all
post_1 = query_set.get(id: 123)
post_2 = query_set.get(id: 456, is_published: false)

If the specified set of filters doesn't match any records, the returned value will be nil.

In order to ensure data consistency, this method will raise a Marten::DB::Errors::MultipleRecordsFound exception if multiple records match the specified set of filters.

Returns the model instance matching a specific set of advanced filters.

Model fields such as primary keys or fields with a unique constraint should be used here in order to retrieve a specific record:

query_set = Post.all
post_1 = query_set.get { q(id: 123) }
post_2 = query_set.get { q(id: 456, is_published: false) }

If the specified set of filters doesn't match any records, the returned value will be nil.

In order to ensure data consistency, this method will raise a Marten::DB::Errors::MultipleRecordsFound exception if multiple records match the specified set of filters.

Returns the model instance matching a specific query node object, or raise an error otherwise.

Returns the model instance matching the given set of filters.

Model fields such as primary keys or fields with a unique constraint should be used here in order to retrieve a specific record:

query_set = Post.all
post_1 = query_set.get!(id: 123)
post_2 = query_set.get!(id: 456, is_published: false)

If the specified set of filters doesn't match any records, a Marten::DB::Errors::RecordNotFound exception will be raised.

In order to ensure data consistency, this method will also raise a Marten::DB::Errors::MultipleRecordsFound exception if multiple records match the specified set of filters.

Returns the model instance matching a specific set of advanced filters.

Model fields such as primary keys or fields with a unique constraint should be used here in order to retrieve a specific record:

query_set = Post.all
post_1 = query_set.get! { q(id: 123) }
post_2 = query_set.get! { q(id: 456, is_published: false) }

If the specified set of filters doesn't match any records, a Marten::DB::Errors::RecordNotFound exception will be raised.

In order to ensure data consistency, this method will raise a Marten::DB::Errors::MultipleRecordsFound exception if multiple records match the specified set of filters.

Appends a string representation of the query set to the passed io.

Returns a queryset whose specified relations are "followed" and joined to each result.

When using #join, the specified foreign-key relationships will be followed and each record returned by the queryset will have the corresponding related objects already selected and populated. Using #join can result in performance improvements since it can help reduce the number of SQL queries, as illustrated by the following example:

query_set = Post.all

p1 = query_set.get(id: 1)
puts p1.author # hits the database to retrieved the related "author"

p2 = query_set.join(:author).get(id: 1)
puts p2.author # doesn't hit the database since the related "author" was already selected

It should be noted that it is also possible to follow foreign keys of direct related models too by using the double underscores notation(__). For example the following query will select the joined "author" and its associated "profile":

query_set = Post.all
query_set.join(:author__profile)

Returns the last record that is matched by the query set, or nil if no records are found.

Returns the last record that is matched by the query set, or raises a NilAssertionError error otherwise.

Returns the model class associated with the query set.

Returns a queryset that will always return an empty array of record, without querying the database.

Once this method is used, any subsequent method call (such as extra filters) will continue returning an empty array of records.

Allows to specify the ordering in which records should be returned when evaluating the query set.

Multiple fields can be specified in order to define the final ordering. For example:

query_set = Post.all
query_set.order(["-published_at", "title"])

In the above example, records would be ordered by descending publication date, and then by title (ascending).

Allows to specify the ordering in which records should be returned when evaluating the query set.

Multiple fields can be specified in order to define the final ordering. For example:

query_set = Post.all
query_set.order("-published_at", "title")

In the above example, records would be ordered by descending publication date, and then by title (ascending).

Returns a paginator that can be used to paginate the current query set.

This method returns a Marten::DB::Query::Paginator object, which can then be used to retrieve specific pages.

Allows to reverse the order of the current query set.

Returns the number of records that are targeted by the current query set.

Appends a string representation of the query set to the passed io.

Updates all the records matched by the current query set with the passed values.

This method allows to update all the records that are matched by the current query set with a hash or a named tuple of values. It returns the number of records that were updated:

query_set = Post.all
query_set.update({"title" => "Updated"})

It should be noted that this methods results in a regular UPDATE SQL statement. As such, the records that are updated through the use of this method won't be validated, and no callbacks will be executed for them either.

Updates all the records matched by the current query set with the passed values.

This method allows to update all the records that are matched by the current query set with the values defined in the kwargs double splat argument. It returns the number of records that were updated:

query_set = Post.all
query_set.update(title: "Updated")

It should be noted that this methods results in a regular UPDATE SQL statement. As such, the records that are updated through the use of this method won't be validated, and no callbacks will be executed for them either.

Allows to define which database alias should be used when evaluating the query set.