Clarify SqlQuery support for unmapped types and nesting

[ErikEJ]

fixes #5205

[Copilot]

Pull request overview

This PR updates the EF Core raw SQL querying documentation to clarify that Database.SqlQuery<T> can materialize unmapped CLR types, including nested complex types, addressing #5205.

Changes:

• Documented projecting SqlQuery<T> results into arbitrary unmapped CLR types (not limited to scalars).
• Added a new “Querying unmapped types” section with examples, including nested complex type (complex/owned-style) materialization and naming conventions.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[AndriySvyryd]

It was added in EF Core 8.0 as well

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Suppressed comments (3)

entity-framework/core/querying/sql-queries.md:258

• The note says nested complex types in unmapped SqlQuery results were added “in a later release”, but doesn’t specify which EF Core version. Please name the minimum version (e.g. 8.0.x / 9.0 / etc.) so readers know whether their current version supports nesting.

> [!NOTE]
> Returning unmapped types from <xref:Microsoft.EntityFrameworkCore.RelationalDatabaseFacadeExtensions.SqlQuery*> was introduced in EF Core 8.0. Support for unmapped types that contain nested [complex types](xref:core/modeling/complex-types) was added in a later release.

entity-framework/core/querying/sql-queries.md:260

• The text says SqlQuery can project rows into an “arbitrary CLR type”, but in practice the result type (and its properties) must be mappable by the provider (or have conversions). Using “mappable CLR type” here would be more precise and consistent with existing EF Core docs terminology.

<xref:Microsoft.EntityFrameworkCore.RelationalDatabaseFacadeExtensions.SqlQuery*> can be used with any scalar type supported by your database provider. If you'd like to use a type not supported by your database provider, you can use [pre-convention configuration](xref:core/modeling/bulk-configuration#pre-convention-configuration) to define a value conversion for it.

<xref:Microsoft.EntityFrameworkCore.RelationalDatabaseFacadeExtensions.SqlQuery*> isn't limited to scalar types. You can also project each row of the result set into an arbitrary CLR type that isn't part of your EF model, as long as the type has a property for every column in the result set. See [Querying unmapped types](#querying-unmapped-types) below for more details.

entity-framework/core/querying/sql-queries.md:301

• The example introduces Address as a complex type, but complex types aren’t discovered by convention in EF Core; readers may not know how Address is recognized as complex in this unmapped-results scenario. Consider annotating the nested type with [ComplexType] (or otherwise clarifying the required configuration/annotation) to make the example self-contained.

public class Address
{

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Suppressed comments (3)

entity-framework/core/querying/sql-queries.md:258

• The note says nested complex-type support was added "in a later release", but it doesn't say which EF Core version added it. Since this is a versioned feature note, it should name the specific version (or link to the relevant release notes/issue) so readers know whether their EF Core version supports nested complex types in SqlQuery results.

> [!NOTE]
> Returning unmapped types from <xref:Microsoft.EntityFrameworkCore.RelationalDatabaseFacadeExtensions.SqlQuery*> was introduced in EF Core 8.0. Support for unmapped types that contain nested [complex types](xref:core/modeling/complex-types) was added in a later release.

entity-framework/core/querying/sql-queries.md:251

• This sentence says results can be projected into an "arbitrary CLR type", but the type must still be mappable by EF Core (property/constructor types need to be supported by the provider/value converters). Using the same wording as the EF Core 8.0 "what's new" page would avoid implying that any CLR type works.

<xref:Microsoft.EntityFrameworkCore.RelationalDatabaseFacadeExtensions.SqlQuery*> isn't limited to scalar types. You can also project each row of the result set into an arbitrary CLR type that isn't part of your EF model, as long as the type has a property for every column in the result set. See [Querying unmapped types](#querying-unmapped-types) below for more details.

entity-framework/core/querying/sql-queries.md:307

• In this example, [ComplexType] is applied to Customer, but Customer is the root result type; the complex type is Address. The attribute should be applied to Address (or configured via OnModelCreating) to match how complex types are defined elsewhere in the docs.

[ComplexType]
public class Customer
{
    public int Id { get; set; }
    public string Name { get; set; }

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Suppressed comments (2)

entity-framework/core/querying/sql-queries.md:258

• The note says nested complex-type support was "added in a later release", but doesn’t indicate which EF Core version first supports this. Please specify the minimum EF Core version (or link to the release notes/PR) so readers can tell whether their version includes nested complex type support for unmapped SqlQuery results.

> [!NOTE]
> Returning unmapped types from <xref:Microsoft.EntityFrameworkCore.RelationalDatabaseFacadeExtensions.SqlQuery*> was introduced in EF Core 8.0. Support for unmapped types that contain nested [complex types](xref:core/modeling/complex-types) was added in a later release.

entity-framework/core/querying/sql-queries.md:260

• Grammar: the subject is singular ("The type used"), so "do not need" should be "does not need" (or "doesn't need").

In addition to scalar types, <xref:Microsoft.EntityFrameworkCore.RelationalDatabaseFacadeExtensions.SqlQuery*> can populate instances of a mappable CLR type from the result set of a SQL query, without including that type in the EF model. The type used for the query results can contain common mapping constructs supported by EF Core, such as parameterized constructors and mapping attributes. The type used must have a property for every value in the result set, but do not need to match any table in the database. For example, given the following type:

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Suppressed comments (1)

entity-framework/core/querying/sql-queries.md:258

• The note says nested complex-type support was added in “a later release”, but doesn’t specify which EF Core version. Readers won’t know whether they need 8.0.x, 9.0, etc., and this is the kind of version gating that should be explicit (the docs elsewhere sometimes call out minor versions, e.g. “EF Core 8.0.2”). Consider naming the exact minimum version that introduced nested complex types (or linking to the relevant release notes/PR) so users can quickly determine whether their installed version supports this.

> [!NOTE]
> Returning unmapped types from <xref:Microsoft.EntityFrameworkCore.RelationalDatabaseFacadeExtensions.SqlQuery*> was introduced in EF Core 8.0. Support for unmapped types that contain nested [complex types](xref:core/modeling/complex-types) was added in a later release.