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
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
Initialization Flow
Static Constructor Sequence
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
nullfalls through to the default. One that returns""is used as given.
Table name
Schema name
The database resolves an unqualified name itself; see schema qualification.
Column 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.
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:
[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 = ...)]orSchemaNameResolversays. 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
Generated Expression Tree
// 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
NULL Handling
NULL Resolution Flow
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
Performance Characteristics
Initialization Cost (One-Time per Type)
Typical Cost:
- Entity with 10 properties: ~1-5ms
- Entity with 50 properties: ~5-15ms
Query Execution Cost (Per-Query)
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
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
Example:
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
Error Message Examples
┌─────────────────────────────────────────────────────────────────┐
│ 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 |