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.

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. The Alias property and AddToDbContext method are excluded.

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

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

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, HotChocolate generates FilterInputType<TEntity> and SortInputType<TEntity> based on all public properties of the entity. 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.

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