DEV Community: George Arrowsmith

Elixir syntax for Ruby developers: a quick introduction

George Arrowsmith — Tue, 05 Sep 2023 06:09:03 +0000

This article is part of a series of extracts from Phoenix on Rails, a comprehensive guide to Elixir, Phoenix and LiveView for developers who already know Ruby on Rails. If you’re a Rails developer who wants to learn Phoenix fast, click here to learn more!

In the last lesson we covered the three most important differences between Ruby and Elixir. Specifically:

Elixir is functional, not object-oriented.
Everything in Elixir is immutable.
Elixir is compiled.

With these concepts in mind, it's time to look at some actual Elixir code. In this lesson we'll take a high-level overview of Elixir's basic syntax, understanding where it's similar to Ruby and where it's different. My aim is to give Ruby developers the fastest possible introduction to Elixir.

(If you want to try these examples for yourself, remember that you can open an interactive Elixir console using iex, the Elixir equivalent of irb.)

Variables

Like in Ruby, variable names in Elixir conventionally use snake_case:

some_number = 1

Unlike Ruby, variable names can end with ? or !:

valid? = true
password! = "foobar"

Strings

Strings in Elixir are written with "double quotes". Unlike in Ruby, they can only use double quotes. Single quotes 'like this' create something weird called a charlist which you rarely need to use in real life.

Concatenate strings with <> (it's + in Ruby):

iex> "Hello" <> " " <> "there"
"Hello there"

As in Ruby, you can interpolate data into a string using #{}:

iex> name = "James Bond"
iex> "The name's #{name}"
"The name's James Bond"
iex> "two plus two = #{2 + 2}"
"two plus two = 4"

Comments

Elixir comments, like Ruby comments, start with #. There's no "multiline comment" in Elixir.

# This is a comment and won't be executed!

Booleans and Nil

The boolean values in Elixir are just like in Ruby: true and false.

There's also a null type, which again is the same as Ruby: nil.

Like in Ruby, the only two "falsey" values in Elixir are nil and false. So if you're testing for truthiness in, say, an if condition, everything that doesn't evaluate to nil or false will be considered true.

The boolean operators &&, || and ! all work the same way as in Ruby.

Conditionals

if and else look like Ruby, except you need to write a do after the if:

if age >= 18 do
  "Adult"
else
  "Minor"
end

Like Ruby, Elixir has an unless statement as well as if:

unless age >= 18 do
  "Minor"
else
  "Adult"
end

Any variables you define within the body of an if will be scoped within that if. They won't override a previous definition of that variable:

iex> x = "Something"
iex> if true do
...>   x = "Something else"
...> end

# What's the value of x now?

iex> x
"Something"

Note that this is different to Ruby:

irb> x = "Something"
irb> if true
...>   x = "Something else"
...> end

irb> x
"Something else"

If you want to set a variable based on an if condition in Elixir, you can return a value from the if expression itself:

iex> x = if true do
...>   "Something"
...> else
...>   "Something else"
...> end

iex> x
"Something"

Elixir has no elsif. If you need multiple conditions, you could write an ugly bunch of nested ifs:

if age >= 65 do
  "OAP"
else
  if age >= 18 do
    "Adult"
  else
    if age >= 13 do
      "Teenager"
    else
      "Child"
    end
  end
end

But there's a better way: use cond:

cond do
  age >= 65 -> "OAP"
  age >= 18 -> "Adult"
  age >= 13 -> "Teenager"
end

cond checks each condition in turn until it finds one that evaluates to something truthy (that is, anything except false or nil).

If none of the conditions are true - for example if the above code is run when age == 12 - then cond will raise an error. If you want a "fallback" clause that matches when nothing else does, you can simply use true as a condition, since this will always be truthy!

age = 12
category = cond do
  age >= 65 -> "OAP"
  age >= 18 -> "Adult"
  age >= 13 -> "Teenager"
  true -> "Child"
end
IO.puts(category)
# "Child"

for

Loop over an enumerable value with for:

for number <- [1, 2, 3, 4] do
  IO.puts(number)
end

# 1
# 2
# 3
# 4

for loops are expressions that return a value. (In fact, everything in Elixir is an expression, meaning every line returns a computed value.) So you can assign the result of for to a variable:

squares = for n <- [1,2,3,4] do
  n * n
end

IO.puts squares
# [1,4,9,16]

for loops are called comprehensions and have many advanced features which you can read about in the official docs.

Elixir has no while keyword.

Numbers

Mathematical stuff mostly works the way you'd expect:

iex> 2 + 2
4
iex> 2 - 5
-3
iex> 3 * 4
12

In Ruby / performs integer division, but in Elixir it performs normal division:

# Ruby:
5 / 2
# => 2

# Elixir:
5 / 2
# => 2.5

To get integer division in Elixir, use the div function:

iex> div(5, 2)
2

In Ruby, % is the modulo operator - that is, a % b means “the remainder of a divided by b.” In Elixir, use rem:

# Ruby:
6 % 4
# => 2

# Elixir:
rem(6, 4)
# => 2

Use ** for exponentiation:

iex> 2 ** 4
16

floor, ceil, round, abs, max and min all do what you'd expect:

iex> floor(5.5)
5
iex> ceil(5.5)
6
iex> round(5.5)
6
iex> round(5.4999)
5
iex> abs(-5)
5
iex> max(2, 3)
3
iex> min(2, 3)
2

Equality

Use == or === - or their opposites, != and !== - to test equality.

== means "equals" while === means "exactly equals". The difference is best explained by example:

2 ==  2   # true
2 === 2   # true
2 ==  2.0 # true
2 === 2.0 # false

Functions

Elixir functions are written with def - but unlike Ruby, you also need to write a do:

def add(a, b) do
  a + b
end

We refer to functions with the format name/n, where name is the function's name and n is the number of arguments it takes. So the above function is called add/2.

Like in Ruby, functions always return the value computed by their last line. So add/2 returns the value of a + b.

Unlike Ruby, Elixir doesn't have a return statement. You can't "exit early" from an Elixir function - the only way to return something is to make it be the value of the function's final expression.

Use \\ to define default arguments:

def choose_color(color \\ "black") do
  IO.puts("You chose #{color}")
end

choose_color("red")
# "You chose red"
choose_color()
# "You chose black"

Like in Ruby, parentheses are optional when calling a function:

choose_color "red"
# "You chose red"
choose_color
# "You chose black"

Also like Ruby, function names can end with a ? or !. By convention, functions that end in ? return a bool:

String.contains?("England", "gland")
# => true

And functions that end an ! raise an exception in their error cases. For example, File.read and File.read! both attempt to read a file from disk, but File.read returns an error message if the file can't be found, while File.read! raises an exception:

File.read("file_that_exists.txt")
# => {:ok, "this is the file's contents"}
File.read("file_that_doesnt_exist.txt")
# => {:error, :enoent}

File.read!("file_that_exists.txt")
# => "this is the file's contents"
File.read!("file_that_doesnt_exist.txt")
# ** (File.Error) could not read file file_that_doesnt_exist.txt: no such file or directory

As in Ruby, these "rules" around ? and ! are just conventions. There's nothing to stop you from creating a function whose name ends in ? but that doesn't return a bool, or whose name ends in ! but that doesn't raise any exceptions. But it's recommended you stick to convention.

Anonymous functions

Anonymous functions are, well, anonymous - they have no name. Create one using the fn and end keywords. They can have any number of parameters, and the parameters are separated from the function body by ->. (Note: you don't need a do.)

fn x, y ->
  x + y
end

You can assign an anonymous function to a variable. To call it, you must write a . before the opening parenthesis:

iex> sum = fn x, y -> x + y end
iex> sum.(1, 2)
3

A common use for anonymous functions is to pass them as arguments to other functions:

iex> Enum.map([1, 2, 3, 4], fn n -> n ** 2 end)
[1, 4, 9, 16]

iex> Enum.reduce([1, 2, 3, 4], fn x, acc -> x + acc end)
10

There's a shorthand syntax for creating anonymous functions:

# This:
sum1 = fn x, y -> x + y end

# Is equivalent to this:
sum2 = &(&1 + &2)
sum2.(3,4)
# => 7

# The brackets are optional:
sum3 = & &1 + &2
sum3.(3,4)
# => 7

When using this syntax, &1, &2, &3, etc. are short for the first, second, third etc. arguments to the function.

iex> Enum.map([1, 2, 3, 4], &(&1 ** 2))
[1, 4, 9, 16]

iex> Enum.reduce([1, 2, 3, 4], &(&1 + &2))
10

Regexes

Regex literals in Elixir are written between ~r/ and /. That is, they ~r/look like this/.

iex> Regex.match?(~r/se[0-9]en/, "se7en")
true
iex> Regex.match?(~r/se[0-9]en/, "seven")
false

You can use other delimiters, such as ~r(…) or ~r'…':

# These are all equivalent:
~r/se[0-9]en/
~r(se[0-9]en)
~r'se[0-9]en'

For more on this, see the documentation on sigils.

inspect

As well as puts, Ruby provides a method p, which prints a coder-friendly representation of the object that's useful when debugging. Sometimes puts and p print the same thing as each other, but they often differ:

puts :symbol
# symbol
p :symbol
# :symbol

puts nil # prints nothing
#
p nil
# nil

puts [1, 2] # prints each item on a separate line
# 1
# 2
p [1, 2]
# [1, 2]

The Elixir equivalent of p is IO.inspect:

IO.puts "string"
# string
IO.inspect "string"
# "string"

There's also inspect (no IO), which returns the value that would be printed by IO.inspect, but doesn't print it.

Exceptions

As in Ruby, you can raise an exception with raise:

iex> raise "something's wrong!"
** (RuntimeError) something's wrong!

try/rescue is the equivalent of Ruby's begin/rescue:

iex> try do
...>   raise "something's wrong"
...> rescue
...>   e in RuntimeError -> e.message
...> end
"something's wrong"

Elixir's after keyword works like ensure in Ruby. else works the same in both languages.

try do
  # code that might raise an exception
rescue
  # code that handles the error
else
  # code that only executes if there was no error
after
  # code that's always executed, whether or not there was an error
end

You can also throw a value and catch it:

iex> try do
...>   throw 1
...> catch
...>   x -> "#{x} was caught"
...> end
"1 was caught"

There's almost always a better, more readable way to solve a problem than with throw and catch. Don't use them unless you truly have no other choice!

As in Ruby, if you want to catch all errors raised by a function, you can drop the try and use the rescue keyword by itself:

iex> defmodule Foo do
...>   def bar do
...>     raise "something's wrong"
...>   rescue
...>     RuntimeError -> "rescued error"
...>   end
...> end
iex> Foo.bar
"rescued error"

Generally, you shouldn't use raise, try, rescue etc. very often in Elixir. There's usually a better way to structure your code using concepts from functional programming - as we'll see in this course.

For more on exceptions, try, catch and rescue, see the docs.

Recap

Don't feel like you need to memorize all of the above before continuing. You can use this lesson as a reference; come back to it in future if you're not sure about anything.

If you're used to Ruby then most of the basic Elixir syntax should feel familiar. Just remember that:

Strings must use double quotes, not single quotes.
Functions and if/unless must have a do on their opening lines.
There are no return or elsif keywords.

Those are the three differences most likely to trip up a Ruby developer. If you remember anything for now, start with those three points.

There's still a lot to learn, including Elixir's more advanced types like atoms, maps, tuples and structs. We also haven't covered two of the most useful and powerful features in Elixir: pattern matching and the pipe operator. We'll get to that in future lessons.

Elixir for Ruby developers: the three most important differences

George Arrowsmith — Sun, 20 Aug 2023 07:37:50 +0000

Many developers who learn Elixir come from a background in Ruby. This is hardly surprising: Elixir's creator, José Valim, was formerly a prominent Ruby developer, and Elixir has been attracting Rubyists since the very beginning!

But while Elixir's syntax looks like Ruby at a glance, you'll quickly realise that these similarities are skin-deep. The two languages are very different in their underlying designs, and Elixir often requires you to structure your code in a way that looks nothing like the equivalent Ruby. Certain aspects of Elixir will feel very unfamiliar to a Rubyist, and will take some getting used to.

This series will give a brief introduction to Elixir for developers who already know Ruby. But before we get into the details of Elixir's syntax, it's worth reviewing some of the higher-level differences between the two languages. In particular, here are the three most important differences between Elixir and Ruby:

Elixir is functional. Unlike Ruby, it's not object-oriented and has no concept of "classes" or inheritance.
Everything in Elixir is immutable.
Elixir is compiled while Ruby is interpreted.

Let's look at those three points in more detail…

Elixir is Functional, not Object-Oriented

The most important difference between Elixir and Ruby is that Elixir is not object-oriented.

Elixir has no classes. You don't initialize "objects" with instance methods. Instead, you write functions that are grouped into modules. For this reason, Elixir code can be structured very differently to the equivalent Ruby.

But to be clear, Elixir still has types, like strings, integers, floats, and lists. It's just that these datatypes don't work in the object-oriented way that you're used to.

To illustrate: in Ruby, strings like "this" are instances of the class String. That class has various instance methods like upcase, reverse, or length which you can call on a particular string using .-syntax. Open irb in a terminal and try it:

irb> name = "Pikachu"
irb> name.upcase
"PIKACHU"
irb> name.reverse
"uhcakiP"
irb> name.length
7

In Elixir, String isn’t a class, because Elixir doesn't have classes. Instead, String is a module - a collection of functions that apply to a string. So instead of writing name.upcase you write String.upcase(name).

upcase isn't a method on strings (Elixir doesn't have methods). It's a function that takes a string as its first argument.

Follow the official instructions to install Elixir if you don't have it already. Then open another terminal window and start iex, the Elixir equivalent of irb. Here’s how the String operations we saw above are performed in Elixir:

iex> name = "Pikachu"
iex> String.upcase(name)
"PIKACHU"
iex> String.reverse(name)
"uhcakiP"
iex> String.length(name)
7

(Note that you exit iex by pressing Ctrl + C twice, whereas to exit irb you press Ctrl + D once.)

Elixir has modules like Integer, List and Float, each containing functions to apply to their respective types:

iex> List.first([1,2,3])
1
iex> Float.floor(3.14)
3.0
iex> Integer.digits(90210)
[9, 0, 2, 1, 0]

If a function takes more than one argument, normally the first argument has the same type as the module. See for example these two ways of testing whether a regex matches a string (regexes in Elixir are written with ~r/…/):

iex> Regex.match?(~r/se[0-9]en/, "se7en")
true
iex> String.match?("se7en", ~r/se[0-9]en/)
true

Both these functions test whether a string matches a regex, returning a boolean. The only difference is the order of the arguments: Regex.match? takes the regex first, String.match? takes the string first. That's the general rule: the name of the module tells you the type of the first argument.

To a Ruby developer, the functional style might feel weird at first. You'll find yourself reaching for instance methods that don't exist, and being initially unsure how to structure something in Elixir when you know how you'd write it in Ruby. But with time the functional style will start to feel natural, and you'll see how it leads to clear, elegant and maintainable code.

Immutability vs Mutability

The next major difference between Elixir and Ruby is that in Elixir, everything is immutable.

In Ruby it's usually possible to mutate objects, which is just a fancy way of saying "change them". For example, the following Ruby creates a string then mutates it in-place:

str = "hello"
str.capitalize!
str << "!"
puts str
# Hello!

The variable str still points to the same memory location, but the contents of that memory have mutated from "hello" to "Hello!".

The disadvantage of mutability is that it makes your code unpredictable. When you pass a string to a function, you don't necessarily know what happens to it. The function could mutate your string without you realising, causing unexpected behavior further down the line.

Not everything in Ruby is like this. For example, symbols like :foobar are immutable. They can't be changed after they've been created. The only way to "capitalize" :foobar is to create an entirely new symbol, :FOOBAR, at a new memory location.

In Elixir, everything behaves like a Ruby symbol. There's no equivalent of capitalize! on a Elixir string because Elixir can't mutate the string in place. You can only use String.capitalize (which we saw above), which returns an entirely new string, leaving the original one unchanged.

We'll see in the lessons ahead how Elixir's immutability makes for predictable, reliable and maintainable code.

Compiled vs Interpreted

Elixir is a compiled language. Elixir files end in .ex, and get compiled to BEAM files with extension .beam. These compiled files are ultimately what gets run when you execute your code.

Try it yourself by creating a file called math.ex. (Note that Elixir's IO.puts is the equivalent of Ruby's puts):

defmodule Math do
  def add(a, b) do
    a + b
  end
end

result = Math.add(2, 2)
IO.puts(result)

Compile and run the code with elixirc:

$ elixirc math.ex
4

This created a compiled file called Elixir.Math.beam in the current directory. .beam files are run on BEAM, the same virtual machine that's used to run Erlang, a veteran functional programming language that's been around since the ’80s.

(If you’re familiar with the Java ecosystem: Elixir and Erlang both run on BEAM in the same way that Java, Scala and Kotlin all run on the JVM.)

.beam files are binary files that you shouldn't edit directly. Make sure to exclude them from your version control system.

BEAM, AKA the Erlang VM, is widely used in telecoms and is renowned for its speed, scalability and fault tolerance - all good qualities for a modern web app!

Elixir might look like Ruby on the surface, but its underlying design is heavily based on Erlang. In fact it wouldn't be too far off to describe Elixir as "Erlang with Ruby syntax".

As well as the elixirc command, there's also elixir, which compiles and runs your code but doesn't save a .beam file to disk. Try creating a one-line file called hello_world.exs. (Note the different ending, .exs instead of .ex. The extra s stands for "script".)

IO.puts("Hello, world!")

Now run it using elixir instead of elixirc:

$ elixir hello_world.exs
Hello, world!

This time around, no .beam file was created. elixir compiles your code just like elixirc, but it drops the compiled output once its done with it and doesn't save it. .exs files are useful for scripting or testing.

By convention we use the .ex extension for files we intend to compile to disk with elixirc, and .exs for files we intend to run as "one-off" scripts we intend to run with elixir. This isn't mandatory - you can use elixir on an .ex file or elixirc on an .exs file if you want. But it's good to stick to convention.

In practice you'll rarely need to run the elixir or elixirc commands directly when working on an Elixir (or Phoenix) project. Most of the time you'll run or compile Elixir code using mix, Elixir's build tool, as we'll see throughout the course. (For more on what happens when you run elixir or elixirc, see this article, but it's not important for now if you're a beginner.)

With that out of the way, we can start talking about syntax. What does Elixir code actually look like? We'll see in the next extract.

ActiveRecord vs. Ecto - querying the database

George Arrowsmith — Thu, 01 Sep 2022 16:04:28 +0000

This post is the first in a planned series on Ecto. Its aim is to explain Ecto to developers who are already familiar with Rails and ActiveRecord.

Ecto in a Phoenix app performs roughly the same function as ActiveRecord in a Ruby on Rails app. Both are used to validate data and to query and update the database. However, their design is quite different, and for Rails developers learning Phoenix, Ecto can take some getting used to.

The first post in this series will cover querying the database with Ecto. It's intended as a quick reference for Rails devs who know how to load records from a DB using ActiveRecord, and want to know how to get the same functionality with Ecto in Phoenix.

(PS: if you're a Rails developer learning Phoenix, you can learn much more from the course Phoenix on Rails, a comprehensive guide to Phoenix written for developers who already know Ruby on Rails.)

The Basics

In Rails you query the DB using the class methods of an ActiveRecord model:

Person.all
Person.find(1)
Person.where(last_name: "Smith")

In Phoenix there are no "models". Instead you define the shape of your data within a schema:

defmodule Person do
  use Ecto.Schema

  # The first arg to `schema/1` tells Ecto that the name of the
  # DB table is 'people'. Note that we don't need to specify
  # that 'people' has a primary key column called 'id' because
  # `schema/1` assumes this by default.
  schema "people" do
    field :first_name, :string
    field :last_name, :string
    field :age, :integer
  end
end

Then you query the DB using functions of the Repo module in conjunction with the schema and, for more complex queries, the Ecto.Query module.

Repo.all(Person)
Repo.get(Person, 1)

import Ecto.Query

Repo.all(from p in Person, where: last_name == "Smith")

# Alternative syntax:
Person
|> where(last_name: "Smith")
|> Repo.all

Finding 1 record

The most basic way to retrieve a record is by its primary key.

# ActiveRecord
Person.find(1)

Person.find raises ActiveRecord::RecordNotFound if no record exists with the given PK.

# Ecto
Repo.get(Person, 1)
Repo.get!(Person, 1)

Repo.get returns nil if no record is found; Repo.get! raises Ecto.NoResultsError.

To find a record by its other fields, use find_by in ActiveRecord and Repo.get_by in Ecto:

# ActiveRecord
Person.find_by(first_name: "Jimi", last_name: "Hendrix")
Person.find_by!(first_name: "Jimi", last_name: "Hendrix")

# Ecto
Repo.get_by(Person, first_name: "Jimi", last_name: "Hendrix")
Repo.get_by!(Person, first_name: "Jimi", last_name: "Hendrix")

find_by and Repo.get_by both return nil if no record is found. find_by! and Repo.get_by! will raise an error.

An important difference between ActiveRecord and Ecto is that in Ecto, Repo.get_by and Repo.get_by! will raise an error if they find more than one result. (Specifically, they raise an Ecto.MultipleResultsError.) ActiveRecord's find_by and find_by!, on the other hand, don't care and simply return the first result.

Finding N records

In ActiveRecord you can use where to return all results which match a query:

Person.where(last_name: "Smith")

In Ecto you construct a query using from then pass it to Repo.all:

import Ecto.Query

query = from p in Person,
        where: p.first_name == "Jimi"
Repo.all(query)

Alternatively, instead of from you can use a functional syntax:

import Ecto.Query

Person
|> where([p], p.first_name == "Jimi")
|> Repo.all

(From here on all sample code assumes that Ecto.Query has already been imported.)

The choice of p in the above queries is arbitrary. We could have used any valid Elixir variable name:

Person
|> where([person], person.first_name == "Jimi")
|> Repo.all

For simpler queries you can pass a basic keyword list to where:

Person
|> where(first_name: "Jimi")
|> Repo.all

Existence

# ActiveRecord
Person.exists?(first_name: "Jimi")

# Ecto (declarative)
query = from p in Person, where: p.first_name == "Jimi"
Repo.exists?(query)

# Ecto (functional)
Person
|> where(first_name: "Jimi")
|> Repo.exists?

Comparison

# ActiveRecord
Person.where('age >= ?', 35)

# Ecto (declarative)
query = from p in Person,
        where: p.age >= 35
Repo.all(query)

# Ecto (functional)
Person
|> where([p], p.age >= 35)
|> Repo.all

Inclusion

# ActiveRecord
Person.where(last_name: ["Hendrix", "Clapton"])

# Ecto (declarative)
query = from p in Person,
        where: p.last_name in ["Hendrix", "Clapton"]
Repo.all(query)

# Ecto (functional)
Person 
|> where([p], p.last_name in ["Hendrix", "Clapton"])
|> Repo.all

Negation

# ActiveRecord
Person.where.not(last_name: "Smith")

# Ecto (declarative)
query = from p in Person,
        where: p.last_name != "Smith"
Repo.all(query)

# Ecto (functional)
Person
|> where([p], p.last_name != "Smith")
|> Repo.all

Use Elixir's not keyword to negate more complex queries:

# ActiveRecord
Person.where.not(last_name: ["Hendrix", "Clapton"])

# Ecto (declarative)
query = from p in Person,
        where: p.last_name not in ["Hendrix", "Clapton"]
Repo.all(query)

OR

# ActiveRecord
Person.where(last_name: "Hendrix")
    .or(Person.where(last_name: "Clapton"))

# Ecto (declarative)
query = from p in Person,
        where: [last_name: "Hendrix"],
        or_where: [last_name: "Clapton"]
Repo.all(query)

# Ecto (functional)
Person
|> where(last_name: "Hendrix")
|> or_where(last_name: "Clapton")
|> Repo.all

Ordering

# ActiveRecord
Person.order(:age) # ASC by default
Person.order(age: :desc)

# Ecto (declarative)
query = from p in Person,
        order_by: p.age # or just order_by: :age
Repo.all(query)

query = from p in Person,
        order_by: [desc: p.age] # or order_by: [desc: :age]
Repo.all(query)

# Ecto (functional)
Person
|> order_by(:age)
|> Repo.all

Person
|> order_by(desc: :age)
|> Repo.all

Note that Ecto uses the wording order_by instead of order, which can trip up ActiveRecord devs.

Also note the reversed ordering: in ActiveRecord you write age: :desc but in Ecto you write desc: :age. This is possible in Elixir because Elixir keyword lists can have duplicate keys; so for example it's possible to write desc: multiple times in an order_by query:

Person
|> order_by(desc: :age, desc: :first_name)
|> Repo.all

This wouldn't make sense in Ruby because the second value of the :desc key would overwrite the first value.

Selecting columns

# ActiveRecord
Person.select(:first_name)

query = from p in Person, select: [:first_name]
Repo.all(query)

Person
|> select([:first_name])
|> Repo.all

This returns a list of %Persons where only the first_name attribute is initialized (and the rest are nil.)

Limits

For more complex queries which you expect to return only one result, you can use Repo.one or Repo.one!:

import Ecto.Query

query = from p in Person,
        where: p.age < 18
Repo.one(query) # nil if no results
Repo.one!(query) # error if no results

This searches for people whose age is below 18. It expects to find and return one result - if it finds more than one, it will raise an Ecto.MultipleResultsError. If it finds no results, it returns nil.

To return the first N results regardless of how many exist:

# ActiveRecord
Person.limit(10)

# Ecto (declarative)
query = from p in Person, limit: 10,
Repo.all(query)

# Ecto (functional)
Person
|> limit(10)
|> Repo.all

Use limit in combination with offset to get pagination:

# ActiveRecord
Person.order(:last_name).limit(20).offset(80)

# Ecto (declarative)
query = from p in Person,
        order_by: :last_name,
        limit: 20,
        offset: 80
Repo.all(query)

# Ecto (functional)
Person
|> order_by(:last_name)
|> limit(20)
|> offset(80)
|> Repo.all

To return only the first or last from a set of results:

# ActiveRecord
Person.order(:last_name).first
Person.order(:last_name).last

# Ecto
Person
|> order_by(:last_name)
|> first
|> Repo.one

Person
|> order_by(:last_name)
|> last
|> Repo.one

Aggregates

To count all records:

# ActiveRecord
Person.count

# Ecto
Repo.aggregate(Person, :count)

Suppose we have two people with first name "John" and one with first name "Jack" in our DB. Then:

# ActiveRecord
Person.group(:first_name).count
#=> { "Jack" => 1, "John" => 2 }

# Ecto
Person
|> group_by(:first_name)
|> select([p], [p.first_name, count(p.id)])
#=> [["Jack", 1], ["John", 2]]

Uniqueness

Suppose again that our DB contains two people called "John" and one caled "Jack". Then:

# ActiveRecord
Person.distinct.pluck(:title)
#=> ["Jack", "John"]

# Ecto (declarative)
query = from p in Person, select: p.first_name, distinct: true
Repo.all(query)
#=> ["Jack", "John"]

# Ecto (functional)
Person
|> select([p], p.first_name)
|> distinct(true)
|> Repo.all
#=> ["Jack", "John"]

To count the number of distinct items:

# ActiveRecord
Person.distinct.count(:first_name)
#=> 2

# Ecto (declarative)
query = from p in Person, select: p.first_name, distinct: true
Repo.aggregate(query, :count)
#=> ["Jack", "John"]

# Ecto (functional)
person
|> select([p], p.first_name)
|> distinct(true)
|> repo.aggregate(:count)
#=> ["Jack", "John"]