Query Models

Query models expose EF Core entities directly as GraphQL queries with automatic cursor pagination, filtering, sorting, and projection. Unlike [TraxQuery] which wraps a train (business logic), [TraxQueryModel] maps a database table to a GraphQL field with zero boilerplate.

Quick Start

1. Mark your entity with [TraxQueryModel]:

[TraxQueryModel(Description = "Player profiles")]
public class PlayerRecord
{
    public long Id { get; set; }
    public string PlayerId { get; set; } = "";
    public string DisplayName { get; set; } = "";
    public int Rating { get; set; }
}

2. Add the entity to a DbSet<T> on a DbContext:

public class GameDbContext(DbContextOptions<GameDbContext> options) : DbContext(options)
{
    public DbSet<PlayerRecord> Players { get; set; } = null!;
}

3. Register the DbContext and enable model discovery:

builder.Services.AddDbContextFactory<GameDbContext>(options =>
    options.UseNpgsql(connectionString));
 
builder.Services.AddTraxGraphQL(graphql =>
    graphql.AddDbContext<GameDbContext>());

This generates a playerRecords query field under discover:

query {
  discover {
    playerRecords(first: 10, where: { rating: { gte: 1500 } }, order: { rating: DESC }) {
      nodes {
        playerId
        displayName
        rating
      }
      pageInfo {
        hasNextPage
        endCursor
      }
      totalCount
    }
  }
}

TraxQueryModel Attribute

[AttributeUsage(AttributeTargets.Class, AllowMultiple = false, Inherited = true)]
public class TraxQueryModelAttribute : Attribute
{
    public string? Name { get; init; }
    public string? Description { get; init; }
    public string? DeprecationReason { get; init; }
    public string? Namespace { get; init; }
    public bool Paging { get; init; } = true;
    public bool Filtering { get; init; } = true;
    public bool Sorting { get; init; } = true;
    public bool Projection { get; init; } = true;
    public FieldBindingBehavior BindFields { get; init; } = FieldBindingBehavior.Implicit;
    public Type? ExposeAs { get; init; }
}

Properties

Feature Configuration

Each feature can be independently disabled per model. All default to true.

// Full-featured (default)
[TraxQueryModel]
public class Player { ... }
 
// Pagination and filtering only, no sorting or projection
[TraxQueryModel(Sorting = false, Projection = false)]
public class AuditLog { ... }
 
// Simple list query, no middleware at all
[TraxQueryModel(Paging = false, Filtering = false, Sorting = false, Projection = false)]
public class StatusCode { ... }

When Paging = false, the field returns a plain list ([Entity!]!) instead of a Connection type.

Projection and hand-written resolvers

Projection narrows the SELECT to the columns the caller's selection set names. A query for { players { nodes { displayName } } } reads one column, not the whole row.

That has a consequence for any field you add to a query model with [ExtendObjectType]. Such a resolver reads its [Parent] in C#, where projection cannot see what it touches, so a property nobody selected arrives as 0 or null and the resolver silently returns an empty or zero answer.

Trax closes the common case: for every field on a query model that is not backed by an entity property, it adds the entity's key to the projection. A resolver that batches on the parent's key needs no annotation.

[ExtendObjectType(typeof(Player))]
public sealed class PlayerAchievements
{
    // player.Id arrives whether or not the caller selected `id`.
    public Task<IReadOnlyList<Achievement>> GetAchievements(
        [Parent] Player player,
        AchievementLoader loader,
        CancellationToken ct
    ) => loader.LoadAsync(player.Id, ct);
}

A resolver that reads something other than the key declares it, and HotChocolate merges that with the key Trax already requires:

[ExtendObjectType(typeof(Player))]
public sealed class PlayerTeam
{
    public Task<Team?> GetTeam(
        [Parent(requires: nameof(Player.TeamId))] Player player,
        TeamLoader loader,
        CancellationToken ct
    ) => loader.LoadAsync(player.TeamId, ct);
}

The requirement is per field and only applies when the field is selected, so a query that does not ask for team still projects exactly the columns it named.

The key is read from the entity class: a [Key] property (all of them, for a composite key), otherwise Id, otherwise {TypeName}Id. A key configured only through the fluent API's HasKey is not visible there, so resolvers on such an entity declare what they read with [Parent(requires: ...)].

Such a field also declares its authorization posture

A field added this way to a [TraxAllowAnonymous] entity inherits no gate, because there is no @authorize on the parent type to inherit, and the host refuses to start until the field says what it is. Put [TraxAuthorize] or [TraxAllowAnonymous] on the resolver method; both apply to a method and Trax emits the matching directive. HotChocolate's [Authorize] and [AllowAnonymous] are refused in their place. A field on a [TraxAuthorize] entity inherits that gate and needs nothing. See Fields Added by a Type Extension.

ExtensionResolversDeclareParentRequirements in Trax.Api.GraphQL.Testing fails the build when a resolver reads an undeclared property. See architecture guards.

Field Binding

By default, HotChocolate exposes all public properties on an entity as GraphQL fields. When your entity has [NotMapped] aliases, DataLoader methods, or infrastructure methods that should not appear in the schema, use explicit binding:

[TraxQueryModel(BindFields = FieldBindingBehavior.Explicit)]
[Table("players", Schema = "game")]
public class Player
{
    [Column("id")]
    public long Id { get; set; }
 
    [Column("display_name")]
    public string DisplayName { get; set; } = "";
 
    [NotMapped]
    public string Alias => $"Player-{Id}";      // excluded from schema
 
    public void AddToDbContext(GameDb db) { }    // excluded from schema
}

With BindFields = FieldBindingBehavior.Explicit, only Id and DisplayName appear in the GraphQL schema, on the object type and in the where and order inputs alike. The Alias property and AddToDbContext method are excluded. The same narrowed inputs are used wherever another model filters or sorts through a navigation to Player.

FK fields added via ObjectTypeExtension (from custom TypeModules registered with AddTypeModule<T>()) still work when using explicit binding, since extensions are separate from the base type's field set.

ExposeAs

When an entity is shared across DbContexts (typical pattern: a "reference" projection of a cross-schema entity), the entity class carries every column required by every owning context, but consumers reading it through a non-owning context cannot navigate the relationships. ExposeAs constrains the GraphQL schema to a separately-declared interface so the schema reflects what the consumer can actually query, rather than auto-binding every public property on the entity.

public interface IBookReference
{
    int Id { get; }
    string Title { get; }
    string Author { get; }
    int Rating { get; }
}
 
[TraxQueryModel(ExposeAs = typeof(IBookReference))]
public class Book : IBookReference
{
    public int Id { get; set; }
    public string Title { get; set; } = "";
    public string Author { get; set; } = "";
    public int Rating { get; set; }
 
    // Owned only by the authoring context; not on IBookReference, so
    // it is hidden from the GraphQL schema produced here.
    public ICollection<Review>? Reviews { get; set; }
}

The generated schema contains only the four interface fields. reviews does not appear on the object type, in the FilterInput, or in the SortInput. Queries referencing it fail at schema validation, not at LINQ-translation time.

Validation

The configuration is validated at Build() time. Each failure mode throws InvalidOperationException with a message that names both the entity and the interface.

Mutations

ExposeAs only applies to [TraxQueryModel] (the query surface). Mutations are trains, not query models, and are not affected.

Authorization

A [TraxQueryModel] entity is exposed via GraphQL, so it must declare its authorization posture explicitly: [TraxAuthorize] to gate it or [TraxAllowAnonymous] to open it. An entity with neither fails at TraxGraphQLBuilder.Build() (unless the endpoint is gated with RequireAuthorization(), which covers it). See Authorization guide - Required Exposure Posture.

Apply [TraxAuthorize] to a [TraxQueryModel] entity to gate access. The directive attaches at GraphQL type level and at the entry field, so the gate enforces uniformly:

• the top-level field under discover (including Connection-shaped scalars like totalCount and pageInfo),
• any other field elsewhere in the schema whose return type is this entity (e.g. a navigation property on an ungated parent),
• a where or order on another model that filters or sorts through a navigation to this entity.

[TraxQueryModel(Namespace = "library")]
[TraxAuthorize(Roles = "Subscriber")]
public class Article { ... }

Combinator semantics, role normalization, and inheritance behavior match the per-train [TraxAuthorize] surface. Policy names referenced by a [TraxQueryModel] entity must be registered with services.AddAuthorization(...); a QueryModelAuthorizationValidator hosted service throws at host start if any policy is missing.

The inverse opt-in, [TraxAllowAnonymous], opens an entity to unauthenticated reads. It is mutually exclusive with [TraxAuthorize] and does not cascade through navigation properties to gated children. See Authorization guide - Anonymous Access via TraxAllowAnonymous.

An entity a query model reaches through a navigation, that is not itself a [TraxQueryModel], declares its posture the same way, with [TraxAuthorize] or [TraxAllowAnonymous] on its class; the host refuses to start naming the navigation when it does not, unless the endpoint is gated with RequireAuthorization(). A class EF Core maps as owned is part of its owner and needs no marker. See Authorization guide - Entities a Query Model Reaches.

See the Authorization guide - Per-Model Authorization for the full semantics table and limitations (no field-level gating, no row-level filtering).

Name Derivation

When Name is null, the field name is derived automatically:

1. Pluralize the class name (naive English rules: Player → Players, Match → Matches, Category → Categories)
2. camelCase the result (Players → players)

Override with Name for cases where the automatic pluralization is incorrect:

[TraxQueryModel(Name = "people")]
public class Person { ... }

Custom Filter and Sort Types

By default, Trax generates the filter and sort inputs from the entity's exposed field set: every public property, or the narrower set BindFields = Explicit or ExposeAs declares. When you need to hide properties, rename filter fields, or customize the generated input types, register custom overrides via the builder:

builder.Services.AddTraxGraphQL(graphql => graphql
    .AddDbContext<GameDbContext>()
    .AddFilterType<Player, PlayerFilterInputType>()
    .AddSortType<Player, PlayerSortInputType>());

Create the custom types by extending FilterInputType<TEntity> or SortInputType<TEntity>:

public class PlayerFilterInputType : FilterInputType<Player>
{
    protected override void Configure(IFilterInputTypeDescriptor<Player> descriptor)
    {
        // Hide internal properties from the schema
        descriptor.Field(x => x.InternalMappedId).Ignore();
 
        // Rename a property for the public API
        descriptor.Field(x => x.MappedId).Name("playerId");
    }
}
 
public class PlayerSortInputType : SortInputType<Player>
{
    protected override void Configure(ISortInputTypeDescriptor<Player> descriptor)
    {
        descriptor.Field(x => x.InternalMappedId).Ignore();
        descriptor.Field(x => x.MappedId).Name("playerId");
    }
}

When an override is registered, it replaces the default for that entity only. Entities without overrides continue to use the auto-generated types.

Case-Insensitive Filtering

The auto-generated string filters (contains, eq, startsWith, ...) are case-sensitive, since they map to plain LIKE / = on a deterministic collation. To add case-insensitive operators, opt in with ConfigureFiltering:

builder.Services.AddTraxGraphQL(graphql => graphql
    .AddDbContext<GameDbContext>()
    .ConfigureFiltering(filter => filter.AddCaseInsensitiveStringOperations()));

This adds icontains (case-insensitive substring) and ieq (case-insensitive equality) to every string filter input, including ExposeAs-projected and custom filter types. The existing case-sensitive operators are unchanged; a client opts in per query by choosing the operator. See ConfigureFiltering for the translation, indexing, and extension details.

Scalar Collections (PostgreSQL Arrays)

A property typed as a collection of scalars (Badge[], string[], List<int>) maps to a PostgreSQL array column and is filtered with array containment. This fits a small bounded set of values that carries no data of its own, such as roles or feature flags on a row. If the membership itself needs fields (GrantedAt, GrantedBy), use a junction table instead and expose that as its own query model.

public enum Badge { Founder, Veteran, Champion }
 
[TraxQueryModel(Namespace = "players")]
[Table("player_records", Schema = "game")]
public class PlayerRecord
{
    [Key]
    [Column("id")]
    public long Id { get; set; }
 
    [Column("badges")]
    public Badge[] Badges { get; set; } = [];
}

The DbContext maps the enum and declares the index. Both matter, for different reasons (see The GIN index declaration changes the SQL):

protected override void OnConfiguring(DbContextOptionsBuilder options) =>
    options.UseNpgsql(connectionString, npgsql => npgsql.MapEnum<Badge>("badge", "game"));
 
protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.HasPostgresEnum<Badge>(schema: "game");
    modelBuilder.Entity<PlayerRecord>().HasIndex(x => x.Badges).HasMethod("gin");
}

The column and its index are created by a migration, like any other table.

Generated filter surface

The schema exposes the enum by name and the collection as a list filter:

enum Badge { FOUNDER, VETERAN, CHAMPION }
 
input ListBadgeElementFilterInput {
  all: BadgeElementFilterInput
  none: BadgeElementFilterInput
  some: BadgeElementFilterInput
  any: Boolean
}
 
input BadgeElementFilterInput {
  eq: Badge
  in: [Badge!]
  nin: [Badge!]
}

A collection of a nullable scalar (int?[]) is the exception: HotChocolate's comparable filter input is constrained to non-nullable value types, so those keep the stock input, neq included.

Set membership is expressed with the standard list operators, and each one reaches PostgreSQL as an array operator a GIN index can serve:

Those first three cover "contains", "contains any" and "contains all" respectively. There is no separate contains operator, because some: { eq: } already compiles to exactly the containment operator a hand-written one would emit.

query PlayersHoldingBothBadges {
  discover {
    players {
      playerRecords(
        where: {
          and: [
            { badges: { some: { eq: CHAMPION } } }
            { badges: { some: { eq: VETERAN } } }
          ]
        }
      ) {
        totalCount
        nodes { id badges }
      }
    }
  }
}

The GIN index declaration changes the SQL

HasIndex(...).HasMethod("gin") does more than describe the database. Npgsql reads it when it compiles a single-value membership filter and picks a different operator:

Both return identical rows, and the GraphQL schema, the query and the response are the same either way. Only the plan differs, so the omission stays invisible until the table grows. Trax logs a warning at startup for any filterable scalar collection with no GIN index declared in the EF model, naming the property and the fix. The multi-value operators (some: { in: }, all: { in: }) compile to && and <@ either way and are unaffected, so a collection filtered only those ways does not need the declaration.

The collection type is not what decides this. Badge[] and List<Badge> both map to the same array column and behave identically; only the index declaration matters.

neq is not available inside a collection

The element filter offers eq, in and nin but not neq. Inside a collection, neq lowers to Any(x => x != value) over a primitive collection, which no EF Core provider can translate, so it would pass GraphQL validation and then fail at execution. Trax removes it from the element input so the query is rejected up front instead.

Scalar properties are unaffected and keep neq:

# Rejected: `neq` does not exist on the element input.
where: { badges: { some: { neq: CHAMPION } } }
 
# Fine: `tier` is a scalar enum property, not a collection.
where: { tier: { neq: CHAMPION } }

The one filter this costs is all: { neq: X }, which did translate. none: { eq: X } is exactly equivalent and still available.

AddDbContext

Register one or more DbContext types whose DbSet<T> properties contain attributed entities:

builder.Services.AddTraxGraphQL(graphql => graphql
    .AddDbContext<GameDbContext>()
    .AddDbContext<InventoryDbContext>());

Only DbSet<T> properties where T has [TraxQueryModel] are exposed. Other DbSet properties on the same DbContext are ignored.

The DbContext must be registered in DI separately (via AddDbContext, AddDbContextFactory, or AddPooledDbContextFactory).

vs TraxQuery

Both appear under the discover namespace in the GraphQL schema.

SDK Reference

AddTraxGraphQL | ConfigureFiltering | Cross-schema data loaders | Architecture guards