Victor Björklund

A Guide to Using Fragments in Ecto

Published: Jul 29 2023

Ecto is a powerful and flexible database library for Elixir that allows developers to interact with databases using idiomatic Elixir code. One of the key features of Ecto is its ability to construct complex queries through the use of fragments. In this blog post, we will explore what fragments are, why they are useful, and how to leverage them effectively in your Ecto applications.

What are Fragments?

In Ecto, a fragment is a way to inject raw SQL expressions directly into your queries. It provides a bridge between the high-level Ecto query API and the low-level SQL commands, allowing you to execute SQL snippets within your Elixir code. Fragments are essential when you need to perform custom or advanced queries that are not easily achievable using the built-in Ecto query DSL.

Why Use Fragments?

While Ecto’s query DSL is expressive and covers most of the common use cases, there are situations where it may fall short. Some queries may involve complex subqueries, window functions, or database-specific features that the DSL doesn’t support directly. In such scenarios, fragments come to the rescue, enabling you to seamlessly integrate raw SQL with your Ecto queries.

Here are some scenarios where fragments can be useful:

  • Raw SQL Expressions: When you have complex calculations or need to use database-specific functions, fragments let you include raw SQL expressions in your queries.
  • Custom Aggregations: If you need to perform custom aggregations that are not directly supported by the DSL, fragments allow you to define these aggregations using SQL.
  • Window Functions: Some queries require window functions like ROW_NUMBER(), RANK(), or LAG(). Fragments enable you to incorporate these functions into your Ecto queries.
  • Common Table Expressions (CTEs): With fragments, you can work with CTEs, which are temporary result sets that you can reference within your main query.

Using Fragments in Ecto

To use fragments in your Ecto queries, you’ll primarily interact with two functions: fragment/1 and fragment/2.


The fragment/1 function is used to inject a single raw SQL expression into your query. The argument to this function is a string representing the SQL expression you want to include. Here’s an example:

query = from u in User, select: fragment("COUNT(?)",

In this example, we use a fragment to calculate the count of users in the User table based on their id.


The fragment/2 function is used when you need to include raw SQL expressions with placeholders (similar to Ecto’s query interpolation). This function takes two arguments: the SQL expression string and a list of values to be inserted into the placeholders. Here’s an example:

query = from u in User, select: fragment("AVG(?)", u.age, type(^"integer"))

In this example, we calculate the average age of users in the User table using a fragment with a placeholder.

Caution: SQL Injection

When using fragments, you must be cautious to avoid SQL injection vulnerabilities. Always make sure to use placeholders (?) in your SQL expressions and pass the corresponding values as the second argument to fragment/2. Ecto will handle the sanitization and binding of the values, mitigating the risk of SQL injection.

Incorporating Fragments into Queries

Fragments can be used in various parts of an Ecto query, such as the select, where, order_by, group_by, and having clauses. Additionally, you can also use fragments within subqueries and CTEs.

Let’s explore an example of using a fragment in a where clause:

from u in User,
  where: fragment("? = ?",, ^"John")

In this example, we filter the User records based on the name “John” using a fragment in the where clause.


Fragments in Ecto provide a powerful tool for incorporating raw SQL expressions into your Ecto queries. While the Ecto query DSL is expressive and covers most use cases, fragments give you the flexibility to perform custom and advanced database operations. However, always exercise caution to prevent SQL injection vulnerabilities by using placeholders and parameter binding.

By effectively leveraging fragments, you can take full advantage of the power and versatility of Ecto while still maintaining the benefits of using idiomatic Elixir code. Happy querying!

Frequently asked questions