Marten::DB::Model::Querying::ClassMethods

Returns a queryset targetting all the records for the considered model.

This method returns a Marten::DB::Query::Set object that - if evaluated - will return all the records for the considered model.

Returns a new query set with the specified annotations.

This method returns a new query set with the specified annotations. The annotations are specified using a block where each annotation has to be wrapped using the annotate method. For example:

query_set = Book.annotate { count(:authors) }
other_query_set = Book.annotate do
  count(:authors, alias_name: :author_count)
  sum(:pages, alias_name: :total_pages)
end

Each of the specified annotations is then available for further use in the query set (in order to filter or order the records). The annotations are also available in retrieved model records via the #annotations method, which returns a hash containing the annotations as keys and their values as values.

Returns true if the model query set matches at least one record or false otherwise. Alias of #exists?.

Returns the average of a field for the current model

This method calculates the average value of the specified field for the considered model. For example:

Product.average(:price) # => 25.0

This will return the average price of all products in the database.

Bulk inserts the passed model instances into the database.

This method allows to insert multiple model instances into the database in a single query. This can be useful when dealing with large amounts of data that need to be inserted into the database. For example:

Post.bulk_create(
  [
    Post.new(title: "First post"),
    Post.new(title: "Second post"),
    Post.new(title: "Third post"),
  ]
)

An optional batch_size argument can be passed to this method in order to specify the number of records that should be inserted in a single query. By default, all records are inserted in a single query (except for SQLite databases where the limit of variables in a single query is 999). For example:

Post.bulk_create(
  [
    Post.new(title: "First post"),
    Post.new(title: "Second post"),
    Post.new(title: "Third post"),
  ],
  batch_size: 2
)

Returns the total count of records for the considered model.

This method returns the total count of records for the considered model. If a field is specified, the method will return the total count of records for which the specified field is not nil. For example:

Post.count              # => 3
Post.count(:updated_by) # => 2

Returns the default queryset to use when creating "unfiltered" querysets for the model at hand.

Returns a queryset 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:

Post.exclude(title: "Test")
Post.exclude(title__startswith: "A")

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

Returns a queryset 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:

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

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

Returns true if the query set corresponding to the specified filters matches at least one record.

This method returns true if the filters passed to this method match at least one record. These filters must be specified using the predicate format:

Post.exists?(title: "Test")
Post.exists?(title__startswith: "A")

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

Returns true if the query set corresponding to the specified advanced filters matches at least one record.

This method returns a Bool 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:

Post.exists? { (q(name: "Foo") | q(name: "Bar")) & q(is_published: true) }

Returns a query set whose records match the given raw predicate and named parameters.

This method enables filtering based on raw SQL predicates, offering greater flexibility than standard field predicates. It returns a modified Marten::DB::Query::Set.

For example:

query_set = Post.all
query_set.filter("is_published = ?", [true])

Returns a query set whose records match the given raw predicate and named parameters.

This method enables filtering based on raw SQL predicates, offering greater flexibility than standard field predicates. It returns a modified Marten::DB::Query::Set.

For example:

query_set = Post.all
query_set.filter("is_published = :published", {published: true})

Returns a query set whose records match the given raw predicate and named parameters.

This method enables filtering based on raw SQL predicates, offering greater flexibility than standard field predicates. It returns a modified Marten::DB::Query::Set.

For example:

query_set = Post.all
query_set.filter("is_published = true")

Returns a query set whose records match the given raw predicate and named parameters.

This method enables filtering based on raw SQL predicates, offering greater flexibility than standard field predicates. It returns a modified Marten::DB::Query::Set.

For example:

query_set = Post.all
query_set.filter("is_published = ?", true)

Returns a query set whose records match the given raw predicate and named parameters.

This method enables filtering based on raw SQL predicates, offering greater flexibility than standard field predicates. It returns a modified Marten::DB::Query::Set.

For example:

query_set = Post.all
query_set.filter("is_published = :published", published: true)

Returns a queryset 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:

Post.filter(title: "Test")
Post.filter(title__startswith: "A")

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

Returns a queryset 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:

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

Returns the first record for the considered model.

nil will be returned if no records can be found.

Returns the first record for the considered model.

A NilAssertionError error will be raised if no records can be found.

Returns a single model instance matching the given raw SQL predicate with positional parameters.

Returns nil if no record matches.

For example:

post = Post.get("name = ? AND is_published = ?", ["crystal", true])

Returns a single model instance matching the given raw SQL predicate with a named parameters hash. Returns nil if no record matches.

For example:

post = Post.get("name = :name", {name: "crystal"})

Returns a single model instance matching the given raw SQL predicate.

Returns nil if no record matches.

For example:

post = Post.get("is_published = true")

Returns a single model instance matching the given raw SQL predicate with positional arguments.

Returns nil if no record matches.

For example:

post = Post.get("name = ?", "crystal")

Returns a single model instance matching the given raw SQL predicate with named parameters.

Returns nil if no record matches.

For example:

post = Post.get("name = :name AND is_published = :published", name: "crystal", published: true)

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:

post_1 = Post.get(id: 123)
post_2 = Post.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:

post_1 = Post.get { q(id: 123) }
post_2 = Post.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 a single model instance matching the given raw SQL predicate with positional parameters.

If the specified raw SQL predicate doesn't match any records, a Marten::DB::Errors::RecordNotFound exception will be raised.

For example:

post = Post.get!("name = ? AND is_published = ?", ["crystal", true])

Returns a single model instance matching the given raw SQL predicate with a named parameters hash.

If the specified raw SQL predicate doesn't match any records, a Marten::DB::Errors::RecordNotFound exception will be raised.

For example:

post = Post.get!("name = :name", {name: "crystal"})

Returns a single model instance matching the given raw SQL predicate.

If the specified raw SQL predicate doesn't match any records, a Marten::DB::Errors::RecordNotFound exception will be raised.

For example:

post = Post.get!("is_published = true")

Returns a single model instance matching the given raw SQL predicate with positional arguments.

If the specified raw SQL predicate doesn't match any records, a Marten::DB::Errors::RecordNotFound exception will be raised.

For example:

post = Post.get!("name = ?", "crystal")

Returns a single model instance matching the given raw SQL predicate with named parameters.

If the specified raw SQL predicate doesn't match any records, a Marten::DB::Errors::RecordNotFound exception will be raised.

For example:

post = Post.get!("name = :name AND is_published = :published", name: "crystal", published: true)

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:

post_1 = Post.get!(id: 123)
post_2 = Post.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:

post_1 = Post.get! { q(id: 123) }
post_2 = Post.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.

Returns the model record matching the given set of filters or create a new one if no one is found.

Model fields that uniquely identify a record should be used here. For example:

tag = Tag.get_or_create(label: "crystal")

When no record is found, 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.

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 record matching the given set of filters or create a new one if no one is found.

Model fields that uniquely identify a record should be used here. The provided block can be used to initialize the model instance to create (in case no record is found). For example:

tag = Tag.get_or_create(label: "crystal") do |new_tag|
  new_tag.active = false
end

When no record is found, 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.

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 record matching the given set of filters or create a new one if no one is found.

Model fields that uniquely identify a record should be used here. For example:

tag = Tag.get_or_create!(label: "crystal")

When no record is found, the new model instance is initialized by using the attributes defined in the kwargs double splat argument. If the new model instance is valid, it is persisted to the database ; otherwise a Marten::DB::Errors::InvalidRecord exception is 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.

Returns the model record matching the given set of filters or create a new one if no one is found.

Model fields that uniquely identify a record should be used here. The provided block can be used to initialize the model instance to create (in case no record is found). For example:

tag = Tag.get_or_create!(label: "crystal") do |new_tag|
  new_tag.active = false
end

When no record is found, the new model instance is initialized by using the attributes defined in the kwargs double splat argument. If the new model instance is valid, it is persisted to the database ; otherwise a Marten::DB::Errors::InvalidRecord exception is 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.

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:

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

p2 = Post.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":

Post.join(:author__profile)

Returns the last record for the considered model.

nil will be returned if no records can be found.

Returns the last record for the considered model.

A NilAssertionError error will be raised if no records can be found.

Returns the maximum value of a field for the current model.

Finds the largest value within the specified field for the records targeted by the model. For example:

Product.maximum(:price) # => 250.0

This would identify the highest-priced product.

Returns the minimum value of a field for the current model.

Finds the smallest value within the specified field for the records targeted by the model. For example:

Product.minimum(:price) # => 250.0

This would identify the lowest-priced product.

Returns a queryset targetting all the records for the considered model with the specified ordering.

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

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

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

Returns a queryset targetting all the records for the considered model with the specified ordering.

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

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

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

Returns the primary key values of the considered model records.

This method returns an array containing the primary key values of the model records. For example:

Post.pks # => [1, 2, 3]

Returns specific column values without loading entire record objects.

This method allows to easily select specific column values from the current query set. This allows retrieving specific column values without actually loading entire records. The method returns an array containing one array with the actual column values for each record. For example:

Post.pluck(["title", "published"])
# => [["First article", true], ["Upcoming article", false]]

Returns specific column values without loading entire record objects.

This method allows to easily select specific column values from the current query set. This allows retrieving specific column values without actually loading entire records. The method returns an array containing one array with the actual column values for each record. For example:

Post.pluck("title", "published")
# => [["First article", true], ["Upcoming article", false]]

Returns a queryset that will automatically prefetch in a single batch the records for the specified relation, with a custom queryset to control how the related records are queried. The prefetched records will be populated on the returned queryset. Using this method can result in performance improvements by reducing the number of SQL queries, as illustrated by the following example:

# Prefetching with a custom queryset
posts = Post.all.prefetch(:tags, query_set: Tag.order(:name)).to_a
puts posts[0].tags # Prefetched with custom ordering

It should be noted that this method enforces type-checking for the custom queryset to ensure its model matches the relation being prefetched. If a type mismatch is detected, a Marten::DB::Errors::UnmetQuerySetCondition exception will be raised. For example:

# Valid usage
posts = Post.all.prefetch(:tags, query_set: Tag.order(:name))

# Invalid usage: Type mismatch
posts = Post.all.prefetch(:tags, query_set: Comment.order(:created_at))
# Raises Marten::DB::Errors::UnmetQuerySetCondition:
# "Can't prefetch :tags using Comment query set."

Returns a queryset that will prefetch in a single batch the records for the specified relations.

When using #prefetch, the records corresponding to the specified relationships will be prefetched in single batches and each record returned by the queryset will have the corresponding related objects already selected and populated. Using #prefetch can result in performance improvements since it can help reduce the number of SQL queries, as illustrated by the following example:

posts_1 = Post.all.to_a
puts posts_1[0].tags.to_a # hits the database to retrieve the related "tags" (many-to-many relation)

posts_2 = Post.prefetch(:tags).to_a
puts posts_2[0].tags # doesn't hit the database since the related "tags" relation was already prefetched

It should be noted that it is also possible to follow relations and reverse relations too by using the double underscores notation(__). For example the following query will prefetch the "author" relation and then the "favorite tags" relation of the author records:

Post.prefetch(:author__favorite_tags)

Finally, it is worth mentioning that multiple relations can be specified to #prefetch. For example:

Author.prefetch(:books__genres, :publisher)

Returns a raw query set for the passed SQL query and positional parameters.

This method returns a Marten::DB::Query::RawSet object, which allows to iterate over the model records matched by the passed SQL query and associated positional parameters. For example:

Article.raw("SELECT * FROM articles WHERE title = ? and created_at > ?", ["Hello World!", "2022-10-30"])

Returns a raw query set for the passed SQL query and named parameters.

This method returns a Marten::DB::Query::RawSet object, which allows to iterate over the model records matched by the passed SQL query and associated named parameters. For example:

Article.raw(
  "SELECT * FROM articles WHERE title = :title and created_at > :created_at",
  {
    title:      "Hello World!",
    created_at: "2022-10-30",
  }
)

Returns a raw query set for the passed SQL query and optional positional parameters.

This method returns a Marten::DB::Query::RawSet object, which allows to iterate over the model records matched by the passed SQL query. For example:

Article.raw("SELECT * FROM articles")

Additional positional parameters can also be specified if the query needs to be parameterized. For example:

Article.raw("SELECT * FROM articles WHERE title = ? and created_at > ?", "Hello World!", "2022-10-30")

Returns a raw query set for the passed SQL query and optional named parameters.

This method returns a Marten::DB::Query::RawSet object, which allows to iterate over the model records matched by the passed SQL query. For example:

Article.raw("SELECT * FROM articles")

Additional named parameters can also be specified if the query needs to be parameterized. For example:

Article.raw(
  "SELECT * FROM articles WHERE title = :title and created_at > :created_at",
  title: "Hello World!",
  created_at: "2022-10-30"
)

Returns the sum of a field for the current model

This method calculates the total sum of the specified field's values for the considered model. For example:

Product.sum(:price) # => 2500  (Assuming there are 100 products with prices averaging to 25)

Returns an unscoped queryset for the considered model.

Returns a queryset that will be evaluated using the specified database.

A valid database alias must be used here (it must correspond to an ID of a database configured in the project settings). If the passed database alias doesn't correspond to any defined connections, a Marten::DB::Errors::UnknownConnection error will be raised.