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.

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).

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.

AsSplitQuery<TEntity>(IQueryable<TEntity>)

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

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).

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.

CreateDbCommand(IQueryable)

Creates a DbCommand set up to execute this query.

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.

public static DbCommand CreateDbCommand(this IQueryable source)

Parameters

source IQueryable

The query source.

Returns

DbCommand

The query string for debugging.

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

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

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.FromSqlInterpolated($"SELECT * FROM dbo.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 interpolated parameter place holders in the SQL query string. Any interpolated parameter values you supply will automatically be converted to a DbParameter:

context.Blogs.FromSqlInterpolated($"SELECT * FROM [dbo].[SearchBlogs]({userSuppliedSearchTerm})")

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.

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

Creates a LINQ query based on a raw SQL query.

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 dbo.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:

context.Blogs.FromSqlRaw("SELECT * FROM [dbo].[SearchBlogs]({0})", userSuppliedSearchTerm)

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 FromSqlInterpolated<TEntity>(DbSet<TEntity>, FormattableString) to create parameters.

This overload also accepts DbParameter instances as parameter values. This allows you to use named parameters in the SQL query string:

context.Blogs.FromSqlRaw("SELECT * FROM [dbo].[SearchBlogs]({@searchTerm})", new SqlParameter("@searchTerm", userSuppliedSearchTerm))

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.