The Marten web framework incorporates an intuitive object-relational mapper (ORM), streamlining the development process for users who may not possess extensive knowledge of databases and SQL. To facilitate interactions with collections of model records, Marten introduces a dynamic mechanism called "Query sets". A query set represents a collection of model records in the database. It can have filters, be paginated, sliced, etc. In this guide, we will cover how to leverage such querying capabilities.

Quick setup

Before delving into our initial examples of query sets, let's first set up a small project that will serve as the foundation for this guide. Assuming that the Marten CLI is properly installed, we can use the marten new command to do so:

marten new project qset-showcase
cd qset-showcase && shards install

Next, let's define a very simple User model by creating a src/models/user.cr file and copying the following content in it:

class User < Marten::Model
  field :id, :big_int, primary_key: true, auto: true

  field :username, :string, max_size: 128
  field :email, :email
  field :first_name, :string, max_size: 128, blank: true, null: true
  field :last_name, :string, max_size: 128, blank: true, null: true

  with_timestamp_fields
end

This provides us a good opportunity to appreciate Marten's declarative approach to model definition. In Marten, models are articulated as subclasses of the Marten::Model base class, explicitly outlining their "fields" through the use of a #field macro.

Marten’s vision when it comes to models is that everything needed to understand a model should be defined within the model itself. In this light, Marten's models drive tables (and not the reverse way around) and migrations are generated automatically from model definitions. While migrations can still be manually written using a convenient DSL if needed, the core idea revolves around the simplicity of defining a model and its fields to ensure that the framework takes care of the associated table automatically.

To generate the migration for the User model that we defined above, we can leverage the marten genmigrations command:

marten genmigrations

This should produce the following output:

Generating migrations for app 'main':
  › Creating [src/migrations/202311151921341_create_main_user_table.cr]... DONE
      ○ Create main_user table

If we inspect the generated file, we should see the following content:

# Generated by Marten 0.3.3 on 2023-11-15 19:21:34 -05:00

class Migration::Main::V202311151921341 < Marten::Migration
  def plan
    create_table :main_user do
      column :id, :big_int, primary_key: true, auto: true
      column :username, :string, max_size: 128
      column :email, :string, max_size: 254
      column :first_name, :string, max_size: 128, null: true
      column :last_name, :string, max_size: 128, null: true
      column :created_at, :date_time
      column :updated_at, :date_time
    end
  end
end

This migration essentially takes care of creating the database table corresponding to the User model we defined previously. Should any adjustments be necessary for this model in the future, the marten genmigrations command can be executed as many times as needed. When doing so, Marten will generate new migration files for each change and will ensure that the generated migrations are interdependent so that they are applied in the right order.

We can now apply our automatically-generated migration by running the marten migrate command:

marten migrate

Which should output something along those lines:

Running migrations:
  › Applying main_202311151921341_create_main_user_table... DONE

And voilà! Our database is ready.

Before delving into query sets, let's finally open a Crystal playbook and let's create a few records. To do so, let's run the following command:

crystal play

We can now head to http://localhost:8080 and paste the following Crystal snippet into the live editor:

require "./src/project"
Marten.setup

User.create!(username: "johndoe", email: "john.doe@example.com")
User.create!(username: "mary", email: "mary01@example.com", first_name: "Mary", last_name: "Williams")

This essentially requires our Marten project and creates two User records. We can keep the Crystal playground open as we will be using it for running and testing queries in the following sections.

What are query sets?

A query set represents a specific query specified for a given model. It can involve filters, be paginated, etc. Unless a specific "write" operation is performed on such query sets, they will usually be mapped to a standard SELECT statement where filters are converted to WHERE clauses.

Query sets are lazily evaluated: defining a query set will usually not involve any database operations. Additionally, most methods provided by query sets also return new query set objects. Query sets are only translated to SQL queries hitting the underlying database when records need to be extracted or manipulated by the considered codebase.

For example:

qset = User.filter(first_name: "John") # the query set is not evaluated
qset = qset.filter(last_name: "Doe") # the query set is not evaluated
puts qset # the query set is evaluated

Basic queries

Let's start with some basic query set examples.

Querying all records

Retrieving all the records of a specific model can be achieved through the use of the #all query set method:

User.all

Filtering specific records

Filtering records can be achieved by leveraging the #filter query set method. For example:

User.filter(username: "johndoe")

Will return all User records whose username is johndoe.

It is possible to filter records by applying multiple filters. To do so, either multiple arguments can be specified to #filter or calls to #filter can be chained. For example, the following queries are equivalent:

User.filter(username: "johndoe").filter(first_name: "John")
User.filter(username: "johndoe", first_name: "John")

By default, filters involving multiple parameters like in the above examples always produce SQL queries whose parameters are "AND"ed together.

Retrieving single objects

Retrieving a specific record is achieved through the use of the #get! query set method. For example:

User.get!(username: "johndoe")
User.get!(id: 1)

As you can see, any kind of filters can be specified to this method, but only one record must be returned. If the record is not found, an exception is raised by this method (Marten::DB::Errors::RecordNotFound). If multiple records are found, another kind of exception is raised too (Marten::DB::Errors::MultipleRecordsFound).

It is also possible to use the #get method, which will simply return nil if the record is not found.

Retrieving the first or last record

The #first and #last query set methods can be used to retrieve the first or last record for a given query set. For example:

User.first
User.last

User.filter(username: "johndoe").first
User.filter(username: "johndoe").last

Ordering records

The #order query set method can be used to specify in which order records should be queried. Multiple fields can be specified in order to define the final ordering.

For example:

qset = User.all
qset.order("-created_at", "username")

In the above example, records would be ordered by descending creation date (because of the - prefix), and then by username (ascending).

Advanced queries

Now that we covered some of the fundamental query set operations, let's delve into more advanced examples.

Filter predicates

Filter predicates define the type of filtering that is done at the SQL level. They map to WHERE clauses in the produced SQL queries.

For example:

User.filter(username__icontains: "john")

Will translate to a SQL query like the following one (using PostgreSQL's syntax):

SELECT * FROM main_user WHERE username LIKE UPPER("john")

By default, unless explicitly specified, the exact predicate (exact match) is used for all filters. As such, the following two query sets are equivalent:

User.filter(username: "johndoe")
User.filter(username__exact: "johndoe")

Note the double underscores notation used in the above examples: __ is used to separate the filtered field name (here, username) from the type of filtering that is intended to be performed on the corresponding column.

Other predicates can be used, such as iexact (case-insensitive match), contains (containment test), startswith (starts-with test), etc:

User.filter(username__startswith: "john")
User.filter(username__contains: "do")

Complex filters with q expressions

As mentioned previously, field predicates expressed as keyword arguments to the #filter method will use an AND operator in the produced WHERE clauses. In order to produce conditions using other operators, it is necessary to use "q expressions".

In this light, most of the methods we mentioned previously like #filter or #get can receive a block allowing to define complex conditions. Inside of this block, a #q method can be used in order to define conditions nodes that can be combined together using the following logical operators: & (logical "AND"), | (logical "OR"), and - (logical negation).

For example, the following snippet will return all the User records whose username starts with "john" or "mary":

User.filter { q(username__startswith: "john") | q(username__startswith: "mary") }

Using this approach, it is possible to produce complex conditions by combining q expressions with the &, |, and - operators. Parentheses can also be used to group statements:

User.filter { 
  (q(first_name: "John") |  q(first_name: "Mary")) & 
  -q(last_name: "Doe")
}

Paginating results

Marten query sets provide a built-in pagination mechanism that you can leverage in order to easily iterate over records that are split across several pages of data. In this light, each query set has the capability to generate "paginator" objects that are initialized with a given page size and that can be used to request specific pages.

For example:

query_set = User.all

paginator = query_set.paginator(10)
paginator.page_size   # => 10
paginator.pages_count # => 6

# Retrieve the first page and iterate over the underlying records
page = paginator.page(1)
page.each { |user| puts user }

page.number               # 1
page.previous_page?       # => false
page.previous_page_number # => nil
page.next_page?           # => true
page.next_page_number     # => 2

As you can see, each page object also gives access to some useful metadata (sibling page numbers, etc) in order to build pagination features.

Performing raw SQL queries

Marten also lets you get fully instantiated records retrieved from raw SQL queries. This can be achieved by leveraging the #raw query set method.

For example, the following snippet would allow iterating over all the User model records:

User.raw("select * from main_user").each do |user|
  # Do something with `user` record
end

It is worth mentioning that is is possible to "inject" parameters into raw SQL queries. Both positional and named arguments are supported. Positional parameters must be specified using the ? syntax while named parameters must be specified using the :param format.

For example:

# Using positional arguments:
User.raw(
  "SELECT * FROM main_user WHERE first_name = ? and created_at > ?", 
  "John", 
  "2023-11-16"
)

# Using named arguments:
User.raw(
  "SELECT * FROM main_user WHERE first_name = :first_name and created_at > :created_at", 
  first_name: "John", 
  created_at: "2023-11-16"
)

Conclusion

In this article, we delved into Marten's user-friendly object-relational mapper (ORM) and its dynamic "Query sets" mechanism, designed to simplify database interactions in web application projects. We covered both fundamental and advanced query operations, demonstrating Marten's adaptability for building efficient, database-driven applications. It's important to note that our coverage only scratched the surface of Marten's capabilities, as we did not explore more complex scenarios involving relationships, joins, and other advanced query set functionalities.