jaunty Architecture › Metadata System Specification

Metadata System Specification

Version: 2026.02.19
Status: Active

The metadata system is the foundation of Jaunty's performance. It builds and caches entity metadata once per type, eliminating reflection at query execution time.


Overview

Usage Phase (Per-query)

GetSetters(reader)

Match columns to properties

Return PropertySetter[]

Execute setters (zero reflection)

Cache Phase (One-time)

MetadataCache static ctor

Create PropertyContext

Compile expression trees

Build ColumnToIndex map

Build Phase (One-time)

MetadataBuilder.Build()

Extract attributes
[Table], [Column], [Key]

Apply JauntyConfig
resolvers

Build EntityMetadata

Key Characteristics:

  • Build Phase: Runs once per type, uses reflection
  • Cache Phase: Compiles delegates, stores in static fields
  • Usage Phase: Zero reflection, O(1) lookups

Component Architecture

System Component Diagram

uses

contains

contains

creates

checks first

«static»

MetadataCache_T

+EntityMetadata Metadata

-Properties PropertyContext[]

-ColumnToIndex Dictionary/FrozenDictionary

+GetSetters(reader, mode) : PropertySetter[]

+CreateSetter(property) : Action

«static»

MetadataBuilder

+Build() : EntityMetadata

-ResolveColumn(property) : string

EntityMetadata

+TableName string

+SchemaName string

+Columns ColumnMetadata[]

+KeyProperty ColumnMetadata

+NonKeyProperties ColumnMetadata[]

ColumnMetadata

+Property PropertyInfo

+ColumnName string

+IsKey bool

+IsIdentity bool

PropertyContext_T

+Property PropertyInfo

+Setter Action

+PropertyName string

+ColumnName string

+IsNonNullable bool

PropertySetter_T

+Set(target, record) : void

«static»

MappedCache_T

+Mapper Func


Initialization Flow

Static Constructor Sequence

ExpressionTreesMetadataBuilderMetadataCacheFirstQueryCLRExpressionTreesMetadataBuilderMetadataCacheFirstQueryCLRloop[For each column]All subsequent queriesuse cached metadata (no reflection)Access MetadataCache<T>Run static constructorBuild<T>()Get [Table] attributeGet [Column] attributesApply JauntyConfig resolversEntityMetadataExtract columnsCreateSetter(property)Build expression treeCompile()Action<T, IDataRecord, int>Create PropertyContext<T>Add to ColumnToIndexCreate FrozenDictionary (net8.0)Initialization completeReturn cached metadata

Metadata Resolution

Name Resolution Order

Every table, schema and column name is resolved in one order, by one function (NameResolution in src/Extrode.Jaunty/Internals/Entity/). Reflection mapping (MetadataBuilder) and source-generated mapping (GeneratedNameCache) both call it, so an entity gets the same names whichever path maps it.

Name 1st: attribute, if its name is non-empty 2nd: resolver, if set and it returns non-null 3rd: default
Table [Table(name)]: Jaunty's if present, otherwise DataAnnotations' JauntyConfig.TableNameResolver(type) C# type name
Schema the schema of that same [Table] (constructor argument or Schema =) JauntyConfig.SchemaNameResolver(type) none: the name is emitted unqualified
Column Jaunty [Column(name)], otherwise DataAnnotations [Column(name)] JauntyConfig.ColumnNameResolver(propertyName) C# property name

Three rules:

  • An empty attribute name, such as [Table("")] or [Column("")], names nothing, so resolution falls through to the resolver.
  • A resolver is called only when no attribute name applies.
  • A resolver that returns null falls through to the default. One that returns "" is used as given.

Table name

Yes

No

Yes

No

Yes

No

Yes

No

No

Yes

Yes

No

Entity type 'OrderLine'

Jaunty [Table]
present?

Its name
non-empty?

DataAnnotations [Table]
present?

Its name
non-empty?

TableNameResolver
set?

Use the attribute name

Use the type name
'OrderLine'

Call it with the type

Returned
null?

Use the result
e.g. 'order_lines'

Schema name

Yes

No

No

Yes

Yes

No

Entity type 'OrderLine'

The chosen [Table]
has a non-empty schema?

Use the attribute schema

SchemaNameResolver
set?

No schema:
the table name is emitted unqualified

Call it with the type

Returned
null?

Use the result
e.g. 'sales'

The database resolves an unqualified name itself; see schema qualification.

Column name

Yes

No

Yes

No

No

Yes

Yes

No

Property 'ProductName'

Jaunty [Column] with
a non-empty name?

Use the attribute name
e.g. 'prod_name'

DataAnnotations [Column]
with a non-empty name?

ColumnNameResolver
set?

Use the property name
'ProductName'

Call it with 'ProductName'

Returned
null?

Use the result
e.g. 'product_name'

When the names are resolved

Reflection mapping resolves names when it builds an entity's metadata. Source-generated mapping resolves them at runtime too, not at build time. The generator bakes in only the attribute names, and leaves the rest to GeneratedNameCache, which keeps one set of resolved names per configuration generation. JauntyConfig.Configure setting a resolver starts a new generation, so the next query on either path picks up the new names.

CRUD / Fluent SQL cachesNameResolutionGeneratedNameCacheGenerated entity codeJauntyConfigApplicationCRUD / Fluent SQL cachesNameResolutionGeneratedNameCacheGenerated entity codeJauntyConfigApplicationalt[changed]The SQL, the bound parameter names, the reader'scolumn lookups and the generated Jaunty members each readthe names current when they runConfigure(c => c.ColumnNameResolver = ToSnakeCase)bump configuration generationconnection.Insert(widget)IEntityMetadataSource.TableName / ColumnsCurrentgeneration changed?Table / Schema / Column for each nameresolved namesbuild columns, parameter map, metadatanames for this generationmetadata with resolved namesBindInsert(command, widget)Current (read again)parameters '@display_name', ...

With no resolver change, a read costs one generation compare, and every step of an operation sees the same names. A resolver set while an operation is between building its SQL and binding or reading can pair the old SQL with the new names and fail; set resolvers at startup, before commands run (see JauntyConfig thread safety).

A resolver that maps two properties of one entity to the same column (compared case-insensitively) is rejected with an ArgumentException on both paths. Entities compiled against a package older than this order keep their build-time names until rebuilt.

Example:

C#
[Table("")]                      // empty: names nothing, the resolver applies
public partial class OrderLine
{
    [Key]
    public int OrderLineId { get; set; }

    [Column("prod_name")]        // attribute wins over the resolver
    public string ProductName { get; set; } = "";

    public decimal UnitPrice { get; set; }
}

JauntyConfig.Configure(c =>
{
    c.TableNameResolver = type => ToSnakeCase(type.Name) + "s";   // your own helper
    c.ColumnNameResolver = ToSnakeCase;
});
Member Name, reflection or source-generated
table order_lines (resolver)
OrderLineId order_line_id (resolver)
ProductName prod_name ([Column])
UnitPrice unit_price (resolver)

With no resolvers set, the same entity maps to table OrderLine with columns OrderLineId, prod_name and UnitPrice.

FlatFiles uses the same order for tables and columns, with two differences:

  • The last resort for a table is the lowercased class name (orderline), not the class name. DuckDB matches unquoted names without regard to case, and PostgreSQL folds unquoted names to lowercase, so the default has stayed lowercase.
  • No schema is applied. File views are registered in DuckDB's default schema, and an import writes to the unqualified table name, whatever [Table(..., Schema = ...)] or SchemaNameResolver says. Schema support is listed in feature candidates.

A column resolver also renames the columns FlatFiles looks for in a file. With the resolvers above, a CSV for OrderLine needs the headers order_line_id, prod_name and unit_price. A file header and the database column always share one name; a [Column] name fixes it for both.


Expression Tree Compilation

CreateSetter Process

Yes

No

CreateSetter(property)

Create parameters

target: Parameter(typeof(T))

record: Parameter(typeof(IDataRecord))

index: Parameter(typeof(int))

Call record.GetValue(index)

Get property type

Nullable type?

Convert.ChangeType
to underlying type

Convert.ChangeType
to property type

Wrap in Nullable

Expression.Assign
target.Property = value

Expression.Lambda>

Compile()

Return compiled delegate

Generated Expression Tree

C#
// For property: public int Id { get; set; }

// Generated lambda:
(T target, IDataRecord record, int index) =>
{
    target.Id = (int)Convert.ChangeType(
        record.GetValue(index),
        typeof(int)
    );
};

// Compiled to IL (no reflection at runtime):
IL_0000: ldarg.0  // target
IL_0001: ldarg.1  // record
IL_0002: ldarg.2  // index
IL_0003: callvirt IDataRecord.GetValue
IL_0008: ldclass typeof(int)
IL_000d: call Convert.ChangeType
IL_0012: unbox.any int
IL_0017: stfld Product.Id

Getter/Setter Resolution

GetSetters Flow

Found

Not Found

Yes

No

Yes

No

Yes

No

Yes

No

Yes

No

No

Yes

GetSetters(reader, mode)

reader.FieldCount

new PropertySetter[fieldCount]

Span matchedProperties

For i = 0 to fieldCount-1

reader.GetName(i)

ColumnToIndex.
TryGetValue(name)

Already
matched?

mode ==
Strict?

mode ==
Strict?

Create PropertySetter

Throw InvalidOperationException
'Property mapped more than once'

More columns?

Throw InvalidOperationException
'Column has no mapping'

matchedProperties[index] = true

mode == Strict?

All properties
matched?

Return PropertySetter[]

Throw InvalidOperationException
'Property missing from result'


NULL Handling

NULL Resolution Flow

No

Yes

Yes

No

PropertySetter.Set(target, record)

record.
IsDBNull(ordinal)?

context.Setter(target, record, ordinal)

IsNonNullable
type?

Throw InvalidOperationException
'Cannot assign NULL to
non-nullable property'

Skip (keeps default value)

Property set

Property = default

Exception thrown

Type Handling:

Type NULL Behavior
string Becomes null
int? Becomes null
DateTime? Becomes null
int Throws InvalidOperationException
DateTime Throws InvalidOperationException
bool Throws InvalidOperationException

Configuration Interaction

Static Caching Behavior

MetadataCacheJauntyConfigAppMetadataCacheJauntyConfigAppApplication StartupFirst Query (triggers caching)Configuration Change (INEFFECTIVE)Second Query (uses cached metadata)Configuration changes after firstuse have NO EFFECT on cached typesColumnNameResolver = ToSnakeCaseTableNameResolver = SnakeCasePluralQuery<Product>(sql)Static constructor runsRead resolversCache with snake_case namesColumnNameResolver = nullQuery<Product>(sql)Use CACHED metadataStill uses snake_case

Performance Characteristics

Initialization Cost (One-Time per Type)

000ms000ms000ms000ms000ms000ms000msMetadataBuilder.Build<T> Extract attributes Apply resolvers Create PropertyContext Build expression trees Compile delegates Build ColumnToIndex Ready for queries BuildCacheCompleteMetadataCache Initialization Timeline

Typical Cost:

  • Entity with 10 properties: ~1-5ms
  • Entity with 50 properties: ~5-15ms

Query Execution Cost (Per-Query)

Per-Query Overhead by Entity SizeMetadata lookupColumnToIndex lookupProperty setters5102050100Properties109876543210Time per row (μs)

Typical Cost:

  • Metadata lookup: O(1) - ~10ns
  • Column-to-index lookup: O(1) - ~50ns (FrozenDictionary)
  • Property setter invocation: O(1) - ~100ns per property

Thread Safety

Static Initialization Guarantee

Thread3Thread2Thread1CLRThread3Thread2Thread1CLRAll threads now havelock-free read accessAccess MetadataCache<T>Check if initializedRun static constructorAccess MetadataCache<T>Wait (constructor in progress)Access MetadataCache<T>Wait (constructor in progress)Build metadataCompile delegatesConstructor completeReturn initialized cacheReturn initialized cache

Guarantees:

  • Static constructors are thread-safe by CLR guarantee
  • Only one thread runs the constructor
  • Other threads wait until initialization completes
  • After initialization: lock-free reads (all fields are readonly)

Extension Points

IMapped Override

Yes

No

User implements IMapped

Define static Map method

MappedCache.Mapper set

DrDispatcher.Resolve()

MappedCache.Mapper
not null?

Use custom Map method

Use MetadataCache

Skip metadata reflection
Skip expression compilation

Normal metadata path

Example:

C#
public class Product : IMapped<Product>
{
    public int Id { get; set; }
    public string Name { get; set; }
    public decimal Price { get; set; }
    
    // Custom mapping - bypasses MetadataCache
    public static void Map(ref Product target, IDataReader reader, int columnIndex)
    {
        target.Id = reader.GetInt32(columnIndex);
        target.Name = reader.GetString(columnIndex + 1);
        target.Price = reader.GetDecimal(columnIndex + 2);
    }
}

Error Handling

Error Scenarios

Yes

No

GetSetters execution

Error type?

Empty result set

Duplicate column mapping

Column has no property mapping

Property missing from result

NULL for non-nullable property

Return empty array

mode == Strict?

Throw InvalidOperationException

Throw InvalidOperationException
with detailed message

Ignore (partial mode)

Error Message Examples

text
┌─────────────────────────────────────────────────────────────────┐
│ Strict mapping failed: property 'Price' (mapped to column      │
│ 'price') was missing from the result set.                       │
│                                                                 │
│ Type: MyApp.Product                                             │
│ SQL columns: [id, name, category_id]                           │
│ Missing properties: [Price]                                     │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│ Strict mapping failed: Property 'Name' was mapped more than    │
│ once from the result set.                                       │
│                                                                 │
│ Type: MyApp.Product                                             │
│ Duplicate column: 'name' appears at positions 1 and 3          │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│ Cannot assign NULL to non-nullable property 'Id' on type       │
│ 'Product'.                                                      │
│                                                                 │
│ Column: 'id' (ordinal: 0)                                       │
│ Value: DBNull                                                   │
└─────────────────────────────────────────────────────────────────┘

See Also

Document Purpose
architecture-specification.md Full architecture
parameter-binding-spec.md Parameter binding
performance-spec.md Performance optimization
../../01-api-reference/attributes.md Mapping attributes
../../01-api-reference/configuration.md JauntyConfig