Calculates the given aggregate.

Delegates to Ecto.Repo.aggregate/3 or Ecto.Repo.aggregate/4. The :repo and :relation options are automatically set based on the repository and relation module configured in the use macro, but can be overridden.

Examples

count = MyRelation.aggregate(:count)
avg_age = MyRelation.aggregate(:avg, :age)
max_id = MyRelation.aggregate(:max, :id, repo: AnotherRepo)

See Ecto.Repo.aggregate/3 and Ecto.Repo.aggregate/4 for more details.

@spec all(keyword()) :: [struct()]

Fetches all records from the relation.

This function retrieves all records from the database table associated with the relation. It can also execute a composable relation query built with functions like restrict/2 and order/2.

Parameters

• opts - Additional options (optional, defaults to [])

Options

• :repo - Override the default repository
• :timeout - Query timeout in milliseconds
• :log - Override logging configuration
• :telemetry_event - Override telemetry event name

Returns

A list of record structs. Returns an empty list if no records are found.

Examples

iex> users = MyApp.Users.all()
iex> length(users)
3
iex> hd(users).name
"John Doe"
...>
iex> active_users = MyApp.Users.restrict(active: true)
...>    |> MyApp.Users.order(:name)
...>    |> MyApp.Users.all()
iex>
iex> length(active_users)
2
iex> hd(active_users).name
"Jane Smith"

Performance Considerations

Be cautious when calling all/1 on large tables without restrictions, as it will load all records into memory.

# Better: use restrictions to limit results
recent_users = Users
               |> MyApp.Users.restrict(inserted_at: {:>, days_ago(30)})
               |> MyApp.Users.all()

See Ecto.Repo.all/2 for more details on the underlying implementation.

@spec all(struct(), keyword()) :: [struct()]

Fetches all records from a composable relation query.

This function head handles the case where a composable relation struct is passed as the first argument, allowing you to execute queries built with restrict/2, order/2, etc.

Parameters

• relation - A composable relation struct built with query functions
• opts - Additional options (optional, defaults to [])

Returns

A list of record structs matching the relation query.

Examples

# Build and execute a composable query
query = MyApp.Users.restrict(active: true)
users = MyApp.Users.all(query)

# Equivalent to:
users = Users
        |> MyApp.Users.restrict(active: true)
        |> MyApp.Users.all()

Fetches all records matching the given clauses.

Delegates to Ecto.Repo.all/2 with a where clause. The :repo and :relation options are automatically set based on the repository and relation module configured in the use macro, but can be overridden.

Parameters

• clauses - Keyword list of field-value pairs to match
• opts - Additional options (optional, defaults to [])

Options

• :repo - Override the default repository
• :timeout - Query timeout in milliseconds
• :log - Override logging configuration

Returns

A list of record structs matching the given clauses. Returns an empty list if no records are found.

Examples

iex> users = MyApp.Users.all_by(active: true)
iex> length(users)
2
iex> Enum.all?(users, & &1.active)
true

iex> # Get by multiple clauses
iex> users = MyApp.Users.all_by(name: "John Doe", active: true)
iex> length(users)
1
iex> hd(users).name
"John Doe"

iex> # Returns empty list if no matches
iex> MyApp.Users.all_by(active: false, age: 100)
[]

See Ecto.Repo.all_by/2 for more details.

Returns the average value for the given field.

This is a convenience function that delegates to aggregate/3 with :avg.

Parameters

• field - The field to calculate the average for
• opts - Additional options (optional, defaults to [])

Examples

avg_age = MyApp.Users.avg(:age)
avg_age = MyApp.Users.avg(:age, repo: AnotherRepo)

See aggregate/3 for more details.

Returns the average value for the given field from a composable relation query.

Parameters

• relation - A composable relation struct built with query functions
• field - The field to calculate the average for
• opts - Additional options (automatically provided by delegate_to)

Examples

query = MyApp.Users.restrict(active: true)
avg_age = MyApp.Users.avg(query, :age)

Checks out a connection for the duration of the function.

Delegates to Ecto.Repo.checkout/2. The :repo option is automatically set based on the repository configured in the use macro, but can be overridden.

Examples

result = MyRelation.checkout(fn ->
  # database operations with checked out connection
end)

See Ecto.Repo.checkout/2 for more details.

Returns the count of records.

Delegates to Ecto.Repo.aggregate/3. The :repo and :relation options are automatically set based on the repository and relation module configured in the use macro, but can be overridden.

Examples

iex> MyApp.Users.count()
3

See Ecto.Repo.aggregate/3 for more details.

@spec count(struct(), keyword()) :: non_neg_integer()

Returns the count of records from a composable relation query.

This function head handles the case where a composable relation struct is passed as the first argument, allowing you to count records from queries built with restrict/2, order/2, etc.

Parameters

• relation - A composable relation struct built with query functions
• opts - Additional options (automatically provided by delegate_to)

Returns

An integer representing the count of records matching the relation query.

Examples

# Build and execute a composable query
query = MyApp.Users.restrict(active: true)
count = MyApp.Users.count(query)

# Equivalent to:
count = Users
        |> MyApp.Users.restrict(active: true)
        |> MyApp.Users.count()

Deletes all entries matching the given query.

Delegates to Ecto.Repo.delete_all/2. The :repo and :relation options are automatically set based on the repository and relation module configured in the use macro, but can be overridden.

Examples

{count, _} = MyRelation.delete_all()
{count, _} = MyRelation.delete_all(repo: AnotherRepo)

See Ecto.Repo.delete_all/2 for more details.

Checks if any entry matches the given query.

Delegates to Ecto.Repo.exists?/2. The :repo and :relation options are automatically set based on the repository and relation module configured in the use macro, but can be overridden.

Parameters

• opts - Additional options (optional, defaults to [])

Options

• :repo - Override the default repository
• :timeout - Query timeout in milliseconds
• :log - Override logging configuration

Returns

• true if any records exist
• false if no records exist

Examples

iex> MyApp.Users.exists?()
true

iex> # Check if any active users exist (using basic exists)
iex> MyApp.Users.exists?()
true

See Ecto.Repo.exists?/2 for more details.

Returns the first record.

Delegates to Ecto.Repo.one/2 with Ecto.Query.first/1. The :repo and :relation options are automatically set based on the repository and relation module configured in the use macro, but can be overridden.

Parameters

• opts - Additional options (optional, defaults to [])

Options

• :repo - Override the default repository
• :timeout - Query timeout in milliseconds
• :log - Override logging configuration

Returns

The first record struct, or nil if no records exist.

Examples

iex> user = MyApp.Users.first()
iex> user.name
"John Doe"
iex> user.id
1

See Ecto.Repo.one/2 and Ecto.Query.first/1 for more details.

@spec first(struct(), keyword()) :: struct() | nil

Returns the first record from a composable relation query.

This function head handles the case where a composable relation struct is passed as the first argument, allowing you to get the first record from queries built with restrict/2, order/2, etc.

Parameters

• relation - A composable relation struct built with query functions
• opts - Additional options (automatically provided by delegate_to)

Returns

The first record struct matching the relation query, or nil if no records are found.

Examples

# Build and execute a composable query
query = MyApp.Users.restrict(active: true) |> MyApp.Users.order(:name)
user = MyApp.Users.first(query)

# Equivalent to:
user = Users
       |> MyApp.Users.restrict(active: true)
       |> MyApp.Users.order(:name)
       |> MyApp.Users.first()

@spec get(
  term(),
  keyword()
) :: struct() | nil

Fetches a single record by its primary key.

This function retrieves a single record from the database using the primary key value. It returns the record if found, or nil if no record exists with the given primary key.

Parameters

• id - The primary key value to search for
• opts - Additional options (optional, defaults to [])

Options

• :repo - Override the default repository
• :timeout - Query timeout in milliseconds
• :log - Override logging configuration
• :telemetry_event - Override telemetry event name

Returns

• The record struct if found
• nil if no record exists with the given primary key

Examples

iex> user = MyApp.Users.get(1)
iex> user.name
"John Doe"
iex> user.email
"john@example.com"
...>
iex> MyApp.Users.get(999)
nil

See Ecto.Repo.get/3 for more details on the underlying implementation.

@spec get!(
  term(),
  keyword()
) :: struct()

Fetches a single record by its primary key, raising if not found.

This function retrieves a single record from the database using the primary key value. Unlike get/2, this function raises an Ecto.NoResultsError if no record is found with the given primary key.

Parameters

• id - The primary key value to search for
• opts - Additional options (optional, defaults to [])

Options

• :repo - Override the default repository
• :timeout - Query timeout in milliseconds
• :log - Override logging configuration
• :telemetry_event - Override telemetry event name

Returns

• The record struct if found
• Raises Ecto.NoResultsError if no record exists with the given primary key

Examples

# Get user by ID
user = MyApp.Users.get!(1)
# => %MyApp.Users.Struct{id: 1, name: "John", email: "john@example.com"}

# Raises if not found
user = MyApp.Users.get!(999)
# => ** (Ecto.NoResultsError) expected at least one result but got none

# Override repository
user = MyApp.Users.get!(1, repo: AnotherRepo)

# With timeout option
user = MyApp.Users.get!(1, timeout: 5000)

Error Handling

try do
  user = MyApp.Users.get!(user_id)
  process_user(user)
rescue
  Ecto.NoResultsError ->
    {:error, :not_found}
end

See Ecto.Repo.get!/3 for more details on the underlying implementation.

Gets a single record by the given clauses.

Delegates to Ecto.Repo.get_by/3. The :repo and :relation options are automatically set based on the repository and relation module configured in the use macro, but can be overridden.

Parameters

• clauses - Keyword list of field-value pairs to match
• opts - Additional options (optional, defaults to [])

Options

• :repo - Override the default repository
• :timeout - Query timeout in milliseconds
• :log - Override logging configuration

Returns

• The record struct if found
• nil if no record matches the given clauses

Examples

iex> user = MyApp.Users.get_by(email: "jane@example.com")
iex> user.name
"Jane Smith"
iex> user.email
"jane@example.com"

iex> # Get by multiple clauses
iex> user = MyApp.Users.get_by(name: "John Doe", active: true)
iex> user.name
"John Doe"
iex> user.active
true

iex> # Returns nil if not found
iex> MyApp.Users.get_by(email: "nonexistent@example.com")
nil

See Ecto.Repo.get_by/3 for more details.

Gets a single record by the given clauses, raises if not found.

Delegates to Ecto.Repo.get_by!/3. The :repo and :relation options are automatically set based on the repository and relation module configured in the use macro, but can be overridden.

Parameters

• clauses - Keyword list of field-value pairs to match
• opts - Additional options (optional, defaults to [])

Options

• :repo - Override the default repository
• :timeout - Query timeout in milliseconds
• :log - Override logging configuration

Returns

• The record struct if found
• Raises Ecto.NoResultsError if no record matches the given clauses

Examples

iex> user = MyApp.Users.get_by!(email: "jane@example.com")
iex> user.name
"Jane Smith"
iex> user.email
"jane@example.com"

iex> # Get by multiple clauses
iex> user = MyApp.Users.get_by!(name: "John Doe", active: true)
iex> user.name
"John Doe"
iex> user.active
true

iex> # Raises if not found
iex> try do
...>   MyApp.Users.get_by!(email: "nonexistent@example.com")
...> rescue
...>   Ecto.NoResultsError -> :not_found
...> end
:not_found

See Ecto.Repo.get_by!/3 for more details.

Returns true if the current process is inside a transaction.

Delegates to Ecto.Repo.in_transaction?/0. The :repo option is automatically set based on the repository configured in the use macro, but can be overridden.

Examples

in_tx = MyRelation.in_transaction?()

See Ecto.Repo.in_transaction?/0 for more details.

Returns the last record.

Delegates to Ecto.Repo.one/2 with Ecto.Query.last/1. The :repo and :relation options are automatically set based on the repository and relation module configured in the use macro, but can be overridden.

Parameters

• opts - Additional options (optional, defaults to [])

Options

• :repo - Override the default repository
• :timeout - Query timeout in milliseconds
• :log - Override logging configuration

Returns

The last record struct, or nil if no records exist.

Examples

iex> user = MyApp.Users.last()
iex> user.name
"Bob Wilson"
iex> user.id
3

See Ecto.Repo.one/2 and Ecto.Query.last/1 for more details.

@spec last(struct(), keyword()) :: struct() | nil

Returns the last record from a composable relation query.

This function head handles the case where a composable relation struct is passed as the first argument, allowing you to get the last record from queries built with restrict/2, order/2, etc.

Parameters

• relation - A composable relation struct built with query functions
• opts - Additional options (automatically provided by delegate_to)

Returns

The last record struct matching the relation query, or nil if no records are found.

Examples

# Build and execute a composable query
query = MyApp.Users.restrict(active: true) |> MyApp.Users.order(:name)
user = MyApp.Users.last(query)

# Equivalent to:
user = Users
       |> MyApp.Users.restrict(active: true)
       |> MyApp.Users.order(:name)
       |> MyApp.Users.last()

Returns the maximum value for the given field.

This is a convenience function that delegates to aggregate/3 with :max.

Parameters

• field - The field to calculate the maximum value for
• opts - Additional options (optional, defaults to [])

Examples

max_age = MyApp.Users.max(:age)
max_age = MyApp.Users.max(:age, repo: AnotherRepo)

See aggregate/3 for more details.

Returns the maximum value for the given field from a composable relation query.

Parameters

• relation - A composable relation struct built with query functions
• field - The field to calculate the maximum value for
• opts - Additional options (automatically provided by delegate_to)

Examples

query = MyApp.Users.restrict(active: true)
max_age = MyApp.Users.max(query, :age)

Returns the minimum value for the given field.

This is a convenience function that delegates to aggregate/3 with :min.

Parameters

• field - The field to calculate the minimum value for
• opts - Additional options (optional, defaults to [])

Examples

min_age = MyApp.Users.min(:age)
min_age = MyApp.Users.min(:age, repo: AnotherRepo)

See aggregate/3 for more details.

Returns the minimum value for the given field from a composable relation query.

Parameters

• relation - A composable relation struct built with query functions
• field - The field to calculate the minimum value for
• opts - Additional options (automatically provided by delegate_to)

Examples

query = MyApp.Users.restrict(active: true)
min_age = MyApp.Users.min(query, :age)

Fetches a single result from the query.

Delegates to Ecto.Repo.one/2. The :repo and :relation options are automatically set based on the repository and relation module configured in the use macro, but can be overridden.

Parameters

• opts - Additional options (optional, defaults to [])

Options

• :repo - Override the default repository
• :timeout - Query timeout in milliseconds
• :log - Override logging configuration

Returns

• The single record struct if exactly one record is found
• nil if no records are found
• Raises Ecto.MultipleResultsError if more than one record is found

Examples

iex> # Get a single user (when only one exists matching criteria)
iex> user = MyApp.Users.restrict(name: "John Doe") |> MyApp.Users.one()
iex> user.name
"John Doe"

iex> # Returns nil when no records match
iex> MyApp.Users.restrict(name: "Nonexistent") |> MyApp.Users.one()
nil

See Ecto.Repo.one/2 for more details.

@spec one(struct(), keyword()) :: struct() | nil

Fetches a single result from a composable relation query.

This function head handles the case where a composable relation struct is passed as the first argument, allowing you to execute queries built with restrict/2, order/2, etc.

Parameters

• relation - A composable relation struct built with query functions
• opts - Additional options (automatically provided by delegate_to)

Returns

A single record struct matching the relation query, or nil if no record is found.

Examples

# Build and execute a composable query
query = MyApp.Users.restrict(active: true)
user = MyApp.Users.one(query)

# Equivalent to:
user = Users
       |> MyApp.Users.restrict(active: true)
       |> MyApp.Users.one()

Fetches a single result from the query, raises if not found or more than one.

Delegates to Ecto.Repo.one!/2. The :repo and :relation options are automatically set based on the repository and relation module configured in the use macro, but can be overridden.

Examples

user = MyRelation.one!(query)
user = MyRelation.one!(query, repo: AnotherRepo)

See Ecto.Repo.one!/2 for more details.

@spec one!(struct(), keyword()) :: struct()

Fetches a single result from a composable relation query, raises if not found or more than one.

This function head handles the case where a composable relation struct is passed as the first argument, allowing you to execute queries built with restrict/2, order/2, etc.

Parameters

• relation - A composable relation struct built with query functions
• opts - Additional options (automatically provided by delegate_to)

Returns

A single record struct matching the relation query. Raises Ecto.NoResultsError if no record is found, or Ecto.MultipleResultsError if more than one record is found.

Examples

# Build and execute a composable query
query = MyApp.Users.restrict(active: true)
user = MyApp.Users.one!(query)

# Equivalent to:
user = Users
       |> MyApp.Users.restrict(active: true)
       |> MyApp.Users.one!()

Returns a lazy enumerable that emits all entries from the data store.

Delegates to Ecto.Repo.stream/2. The :repo and :relation options are automatically set based on the repository and relation module configured in the use macro, but can be overridden.

Examples

stream = MyRelation.stream()
stream = MyRelation.stream(repo: AnotherRepo)

See Ecto.Repo.stream/2 for more details.

Returns the sum of values for the given field.

This is a convenience function that delegates to aggregate/3 with :sum.

Parameters

• field - The field to calculate the sum for
• opts - Additional options (optional, defaults to [])

Examples

total_age = MyApp.Users.sum(:age)
total_age = MyApp.Users.sum(:age, repo: AnotherRepo)

See aggregate/3 for more details.

Returns the sum of values for the given field from a composable relation query.

Parameters

• relation - A composable relation struct built with query functions
• field - The field to calculate the sum for
• opts - Additional options (automatically provided by delegate_to)

Examples

query = MyApp.Users.restrict(active: true)
total_age = MyApp.Users.sum(query, :age)

Runs the given function or Ecto.Multi inside a transaction.

Delegates to Ecto.Repo.transaction/2. The :repo option is automatically set based on the repository configured in the use macro, but can be overridden.

Examples

{:ok, result} = MyRelation.transaction(fn ->
  # database operations
end)

{:ok, changes} = MyRelation.transaction(multi, repo: AnotherRepo)

See Ecto.Repo.transaction/2 for more details.

Updates all entries matching the given query with the given values.

Delegates to Ecto.Repo.update_all/3. The :repo and :relation options are automatically set based on the repository and relation module configured in the use macro, but can be overridden.

Examples

{count, _} = MyRelation.update_all(set: [active: false])
{count, _} = MyRelation.update_all([set: [active: false]], repo: AnotherRepo)

See Ecto.Repo.update_all/3 for more details.