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

Defined in:

marten/db/model/querying.cr

Instance Method Summary

Instance Method Detail

def all #

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.


[View source]
def any? #

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


[View source]
def default_queryset #

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


[View source]
def exclude(**kwargs) #

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.


[View source]
def exclude(&) #

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

[View source]
def exists? #

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


[View source]
def exists?(**kwargs) #

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.


[View source]
def exists?(&) #

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

[View source]
def filter(**kwargs) #

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.


[View source]
def filter(&) #

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

[View source]
def first #

Returns the first record for the considered model.

nil will be returned if no records can be found.


[View source]
def first! #

Returns the first record for the considered model.

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


[View source]
def get(**kwargs) #

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.


[View source]
def get(&) #

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.


[View source]
def get!(**kwargs) #

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.


[View source]
def get!(&) #

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.


[View source]
def get_or_create(**kwargs) #

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.


[View source]
def get_or_create(**kwargs, &) #

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.


[View source]
def get_or_create!(**kwargs) #

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.


[View source]
def get_or_create!(**kwargs, &) #

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.


[View source]
def join(*relations : String | Symbol) #

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)

[View source]
def last #

Returns the last record for the considered model.

nil will be returned if no records can be found.


[View source]
def last! #

Returns the last record for the considered model.

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


[View source]
def pluck(fields : Array(String | Symbol)) : Array(Array(Field::Any)) #

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]]

[View source]
def pluck(*fields : String | Symbol) : Array(Array(Field::Any)) #

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]]

[View source]
def raw(query : String, params : Array) #

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

[View source]
def raw(query : String, params : Hash | NamedTuple) #

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

[View source]
def raw(query : String, *args) #

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

[View source]
def raw(query : String, **kwargs) #

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

[View source]
def using(db : String | Symbol) #

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.


[View source]