Cohesive.Relations 0.1.0-alpha.126

Cohesive.Relations

Cohesive.Relations lets applications describe relationships, projections, filters, and queries in typed C# while leaving storage placement and execution strategy to compilers and adapters.

Portable relation drafts support explicit nested fields, statically keyed object construction, explicit coalesce defaults, bounded code-conditionals, key-based collection join and collection select with shape-aware acceptance. Selectors preserve item scope and each target child's contract; source collections must be present and non-null. Explicit single requires exactly one selected item, and explicit parseInt32/parseInt64 convert in-range integer text. parseDecimal converts invariant text without rounding. Named enum literals are checked in their owning graph. Implicit element traversal and undeclared conversions remain unsupported.

Install

dotnet add package Cohesive.Relations

Author a relation

A complete Load -> LoadDto relation needs no hand-authored node IDs, binding names, source placement, or adapter configuration:

var author = RelationQuery.Expression();
var loads = author.Source<Load>();

var loadDtos = author.Project(
    loads,
    (Load load) => new LoadDto
    {
        Id = load.Id,
        Status = load.Status
    });

var relation = loadDtos.BuildRelation(dto => dto.Id);

The authoring session derives the logical nodes, bindings, shapes, field assignments, relation identity, display name, and provenance. relation contains the canonical definition and structured validation diagnostics.

Add a relationship when the result needs another fact:

var author = RelationQuery.Expression();
var loads = author.Source<Load>();

var customers = author.Traverse<Load, Customer>(
    loads,
    load => load.CustomerId);

var searchDocuments = author.Project(
    customers,
    (Load load, Customer customer) => new LoadSearchDto
    {
        Id = load.Id,
        CustomerName = customer.Name
    });

var loadSearch = searchDocuments.BuildRelation(dto => dto.Id);

The same traversal may become an in-memory lookup, a PostgreSQL join, bounded source reads followed by local correlation, or another capability-compatible realization. The relation itself does not change.

Use it for

• DTO mapping and enrichment.
• Independently invoked row and aggregation queries.
• Application read models, API results, integration payloads, and reports.
• Field-demand, dependency, lineage, and missing-input analysis.
• Relation-derived materialized views and targeted rebuild planning.
• Portable execution across supplied objects and registered physical sources.

How execution stays honest

The canonical relation/query document is the semantic authority. An invocation selects results and parameters; compilation derives the exact fields and operations it needs. A target must prove those requirements against its capabilities and operating boundaries. Unsupported semantics and incomplete source evidence produce structured diagnostics rather than a weakened query or a misleading empty result.

The expression API is the normal application surface. Structural authoring and direct IR construction remain available for importers, generators, persistence tooling, and compiler tests.

Continue

• Getting started builds, evaluates, and enriches a relation.
• Execution and adapters covers supplied facts, acquisition, placement, and native compilation.
• Diagnostics explains incomplete evidence and requirement gaps.
• Capability reference is generated from the implemented target profiles.
• Migration covers the retired relation-query stack.
• Internals retains the complete semantic model, compiler architecture, use cases, and design rationale.

Adapter-specific guides are available for Cohesive.Adapters.Postgres, Cohesive.Adapters.Cosmos, and Cohesive.Adapters.Elastic.