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