Design Decisions

​

1. The Problem UOM Solves

1. Schema translation — a SQL table with foreign keys does not map one-to-one onto a MongoDB document (which prefers embedding related data) or a Neo4j graph (which prefers relationships between nodes).
2. Query translation — a LINQ/SQL/HQL query must be rewritten into an equivalent MongoDB or Cypher query that returns the same data, not just code that compiles.

​

2. Why These Frameworks and These Translation Pairs

​

2.1 Source frameworks (.NET / relational)

​

2.2 Target frameworks (Java / NoSQL)

​

2.3 Current direction: one-way .NET → Java Spring Data

1. EF Core → Spring Data MongoDB
2. EF Core → Spring Data Neo4j
3. Dapper → Spring Data MongoDB
4. NHibernate → Spring Data MongoDB

​

2.4 Newest framework versions, pinned exactly

​

3. Template APIs vs. Repository Patterns

• Spring Data MongoDB → MongoTemplate with the Criteria / Query API.
• Spring Data Neo4j → Neo4jTemplate with the programmatic Cypher-DSL Statement builders.

​

3.1 Why not MongoRepository / Neo4jRepository?

1. They need a booted Spring container. Repositories are runtime proxies created by classpath scanning, annotation processing, and ApplicationContext bootstrapping. Spinning up a full Spring context inside a throwaway validation sandbox is slow, memory-heavy, and fragile.
2. Derived-query methods hide logic in method names. findByPickingCompletedWhenBetween(...) encodes the query in a string parsed at runtime. The compiler cannot verify it; a typo surfaces only when the app runs against a live database. That defeats the entire point of compile-time validation.
3. They are hard to introspect. UOM needs to extract the concrete query object (the Mongo filter document / the Cypher statement) to run it and compare results. A repository proxy gives you results, not an inspectable query plan.

​

3.2 What a generated MongoDB query looks like

class OrderLineQuery {
   private final MongoTemplate mongoTemplate;

   OrderLineQuery(MongoTemplate mongoTemplate) {
      this.mongoTemplate = mongoTemplate;
   }

   List<OrderLine> query1() {
      Date from = new Date(2014, 12, 20);
      Date to = new Date(2014, 12, 31);
      Query query = Query.query(Criteria.where("pickingCompletedWhen").gte(from).lte(to));
      return mongoTemplate.find(query, OrderLine.class);
   }
}

​

3.3 Cypher-DSL for Spring Data Neo4j

var person = Cypher.node("Person").named("p");
var sortProperty = person.property(sortByField);
Statement statement = Cypher.match(person)
         .returning(person)
         .orderBy(ascending ? sortProperty.ascending() : sortProperty.descending())
         .limit(Cypher.literalOf(1))
         .build();

​

3.4 The payoff: everything is compile-checkable and runnable

1. Compiled in a lightweight sandbox (mvn compile / dotnet build) — see Validators & Equivalence.
2. Executed against the real database to produce a result sample.
3. Compared field-by-field against the source query’s result via DeepDiff.

​

4. Why a Validation Harness Is Generated Alongside the Query

• translated_query_code — the clean, production query you actually want.
• *_validation_harness_code — a self-contained runnable program (with a declared entry-point class/method) that executes the query, captures count / firstSample / lastSample, and writes them as JSON.

​

5. NHibernate Mapping-by-Code

public class CustomerMap : ClassMapping<Customer> {
    public CustomerMap() {
        Table("Customers"); Schema("Sales");
        Id(x => x.CustomerID, m => m.Generator(Generators.Identity));
        Property(x => x.CustomerName);
        Bag(x => x.CustomerTransactions, map => {
            map.Key(k => k.Column("CustomerID"));
            map.Inverse(true);
        }, rel => rel.OneToMany());
    }
}

• Self-contained in one C# file — no external XML to parse, generate, or keep in sync, which keeps both code generation and compilation simple.
• Compile-checked — mapping mistakes surface from dotnet build, not as silent runtime configuration failures.
• First-party — ClassMapping<T> ships with NHibernate itself, so no extra dependency (unlike Fluent NHibernate).

​

6. Determinism by Design

• Explicit validation gates: compile → execute → DeepDiff → LLM judge. A translation cannot be returned unless it passes the gates appropriate to its type.
• Bounded retries: at most MAX_TRANSLATION_LOOPS = 3 correction loops before handing off to a human, so the pipeline never spins forever.
• Temperature 0 on every generation/evaluation model, so the same input yields the same output.

​

7. Why You Can Trust the Translation

​

8. Acknowledgements & Lineage

• ORMorpher thesis: Framework-Agnostic Query Adaptation
• ORMorpher source: github.com/milan252525/orm-convertor