Class RelationalQueryableExtensions

Namespace

Microsoft.EntityFrameworkCore

Assembly

Microsoft.EntityFrameworkCore.Relational.dll

Relational database specific extension methods for LINQ queries.

public static class RelationalQueryableExtensions

Inheritance

object

RelationalQueryableExtensions

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Methods

AsSingleQuery<TEntity>(IQueryable<TEntity>)

Returns a new query which is configured to load the collections in the query results in a single database query.

public static IQueryable<TEntity> AsSingleQuery<TEntity>(this IQueryable<TEntity> source) where TEntity : class

Parameters

source IQueryable<TEntity>

The source query.

Returns

IQueryable<TEntity>

A new query where collections will be loaded through single database query.

Type Parameters

TEntity

The type of entity being queried.

Remarks

This behavior generally guarantees result consistency in the face of concurrent updates (but details may vary based on the database and transaction isolation level in use). However, this can cause performance issues when the query loads multiple related collections.

The default query splitting behavior for queries can be controlled by UseQuerySplittingBehavior(QuerySplittingBehavior).

See EF Core split queries for more information and examples.

AsSplitQuery<TEntity>(IQueryable<TEntity>)

Returns a new query which is configured to load the collections in the query results through separate database queries.

public static IQueryable<TEntity> AsSplitQuery<TEntity>(this IQueryable<TEntity> source) where TEntity : class

Parameters

source IQueryable<TEntity>

The source query.

Returns

IQueryable<TEntity>

A new query where collections will be loaded through separate database queries.

Type Parameters

TEntity

The type of entity being queried.

Remarks

This behavior can significantly improve performance when the query loads multiple collections. However, since separate queries are used, this can result in inconsistent results when concurrent updates occur. Serializable or snapshot transactions can be used to mitigate this and achieve consistency with split queries, but that may bring other performance costs and behavioral difference.

The default query splitting behavior for queries can be controlled by UseQuerySplittingBehavior(QuerySplittingBehavior).

See EF Core split queries for more information and examples.

CreateDbCommand(IQueryable)

Creates a DbCommand set up to execute this query.

public static DbCommand CreateDbCommand(this IQueryable source)

Parameters

source IQueryable

The query source.

Returns

DbCommand

The query string for debugging.

Remarks

This is only typically supported by queries generated by Entity Framework Core.

Warning: there is no guarantee that executing this command directly will result in the same behavior as if EF Core had executed the command.

Note that DbCommand is an IDisposable object. The caller is responsible for disposing the returned command.

This is only typically supported by queries generated by Entity Framework Core.

See Logging, events, and diagnostics for more information and examples.

ExecuteDeleteAsync<TSource>(IQueryable<TSource>, CancellationToken)

Asynchronously deletes database rows for the entity instances which match the LINQ query from the database.

public static Task<int> ExecuteDeleteAsync<TSource>(this IQueryable<TSource> source, CancellationToken cancellationToken = default)

Parameters

source IQueryable<TSource>

The source query.

cancellationToken CancellationToken

A CancellationToken to observe while waiting for the task to complete.

Returns

Task<int>

The total number of rows deleted in the database.

Type Parameters

TSource

Remarks

This operation executes immediately against the database, rather than being deferred until Microsoft.EntityFrameworkCore.DbContext.SaveChanges is called. It also does not interact with the EF change tracker in any way: entity instances which happen to be tracked when this operation is invoked aren't taken into account, and aren't updated to reflect the changes.

See Executing bulk operations with EF Core for more information and examples.

ExecuteDelete<TSource>(IQueryable<TSource>)

Deletes all database rows for the entity instances which match the LINQ query from the database.

public static int ExecuteDelete<TSource>(this IQueryable<TSource> source)

Parameters

source IQueryable<TSource>

The source query.

Returns

int

The total number of rows deleted in the database.

Type Parameters

TSource

Remarks

This operation executes immediately against the database, rather than being deferred until Microsoft.EntityFrameworkCore.DbContext.SaveChanges is called. It also does not interact with the EF change tracker in any way: entity instances which happen to be tracked when this operation is invoked aren't taken into account, and aren't updated to reflect the changes.

See Executing bulk operations with EF Core for more information and examples.

ExecuteUpdateAsync<TSource>(IQueryable<TSource>, Expression<Func<SetPropertyCalls<TSource>, SetPropertyCalls<TSource>>>, CancellationToken)

Asynchronously updates database rows for the entity instances which match the LINQ query from the database.

public static Task<int> ExecuteUpdateAsync<TSource>(this IQueryable<TSource> source, Expression<Func<SetPropertyCalls<TSource>, SetPropertyCalls<TSource>>> setPropertyCalls, CancellationToken cancellationToken = default)

Parameters

source IQueryable<TSource>

The source query.

setPropertyCalls Expression<Func<SetPropertyCalls<TSource>, SetPropertyCalls<TSource>>>

A collection of set property statements specifying properties to update.

cancellationToken CancellationToken

A CancellationToken to observe while waiting for the task to complete.

Returns

Task<int>

The total number of rows updated in the database.

Type Parameters

TSource

Remarks

This operation executes immediately against the database, rather than being deferred until Microsoft.EntityFrameworkCore.DbContext.SaveChanges is called. It also does not interact with the EF change tracker in any way: entity instances which happen to be tracked when this operation is invoked aren't taken into account, and aren't updated to reflect the changes.

See Executing bulk operations with EF Core for more information and examples.

ExecuteUpdate<TSource>(IQueryable<TSource>, Expression<Func<SetPropertyCalls<TSource>, SetPropertyCalls<TSource>>>)

Updates all database rows for the entity instances which match the LINQ query from the database.

public static int ExecuteUpdate<TSource>(this IQueryable<TSource> source, Expression<Func<SetPropertyCalls<TSource>, SetPropertyCalls<TSource>>> setPropertyCalls)

Parameters

source IQueryable<TSource>

The source query.

setPropertyCalls Expression<Func<SetPropertyCalls<TSource>, SetPropertyCalls<TSource>>>

A collection of set property statements specifying properties to update.

Returns

int

The total number of rows updated in the database.

Type Parameters

TSource

Remarks

This operation executes immediately against the database, rather than being deferred until Microsoft.EntityFrameworkCore.DbContext.SaveChanges is called. It also does not interact with the EF change tracker in any way: entity instances which happen to be tracked when this operation is invoked aren't taken into account, and aren't updated to reflect the changes.

See Executing bulk operations with EF Core for more information and examples.

FromSqlInterpolated<TEntity>(DbSet<TEntity>, FormattableString)

Creates a LINQ query based on an interpolated string representing a SQL query.

public static IQueryable<TEntity> FromSqlInterpolated<TEntity>(this DbSet<TEntity> source, FormattableString sql) where TEntity : class

Parameters

source DbSet<TEntity>

An IQueryable<T> to use as the base of the interpolated string SQL query (typically a Microsoft.EntityFrameworkCore.DbSet<>).

sql FormattableString

The interpolated string representing a SQL query with parameters.

Returns

IQueryable<TEntity>

An IQueryable<T> representing the interpolated string SQL query.

Type Parameters

TEntity

The type of the elements of source.

Remarks

If the database provider supports composing on the supplied SQL, you can compose on top of the raw SQL query using LINQ operators.

As with any API that accepts SQL it is important to parameterize any user input to protect against a SQL injection attack. You can include interpolated parameter place holders in the SQL query string. Any interpolated parameter values you supply will automatically be converted to a DbParameter.

See Executing raw SQL commands with EF Core for more information and examples.

FromSqlRaw<TEntity>(DbSet<TEntity>, string, params object[])

Creates a LINQ query based on a raw SQL query.

public static IQueryable<TEntity> FromSqlRaw<TEntity>(this DbSet<TEntity> source, string sql, params object[] parameters) where TEntity : class

Parameters

source DbSet<TEntity>

An IQueryable<T> to use as the base of the raw SQL query (typically a Microsoft.EntityFrameworkCore.DbSet<>).

sql string

The raw SQL query.

parameters object[]

The values to be assigned to parameters.

Returns

IQueryable<TEntity>

An IQueryable<T> representing the raw SQL query.

Type Parameters

TEntity

The type of the elements of source.

Remarks

If the database provider supports composing on the supplied SQL, you can compose on top of the raw SQL query using LINQ operators: context.Blogs.FromSqlRaw("SELECT * FROM Blogs").OrderBy(b => b.Name).

As with any API that accepts SQL it is important to parameterize any user input to protect against a SQL injection attack. You can include parameter place holders in the SQL query string and then supply parameter values as additional arguments. Any parameter values you supply will automatically be converted to a DbParameter.

However, never pass a concatenated or interpolated string ($"") with non-validated user-provided values into this method. Doing so may expose your application to SQL injection attacks. To use the interpolated string syntax, consider using FromSql<TEntity>(DbSet<TEntity>, FormattableString) to create parameters.

This overload also accepts DbParameter instances as parameter values. In addition to using positional placeholders as above ({0}), you can also use named placeholders directly in the SQL query string.

See Executing raw SQL commands with EF Core for more information and examples.

FromSql<TEntity>(DbSet<TEntity>, FormattableString)

Creates a LINQ query based on an interpolated string representing a SQL query.

public static IQueryable<TEntity> FromSql<TEntity>(this DbSet<TEntity> source, FormattableString sql) where TEntity : class

Parameters

source DbSet<TEntity>

An IQueryable<T> to use as the base of the interpolated string SQL query (typically a Microsoft.EntityFrameworkCore.DbSet<>).

sql FormattableString

The interpolated string representing a SQL query with parameters.

Returns

IQueryable<TEntity>

An IQueryable<T> representing the interpolated string SQL query.

Type Parameters

TEntity

The type of the elements of source.

Remarks

If the database provider supports composing on the supplied SQL, you can compose on top of the raw SQL query using LINQ operators.

As with any API that accepts SQL it is important to parameterize any user input to protect against a SQL injection attack. You can include interpolated parameter place holders in the SQL query string. Any interpolated parameter values you supply will automatically be converted to a DbParameter.

See Executing raw SQL commands with EF Core for more information and examples.