References and Clusters

What is a Reference?

A reference is a numeric engine-level field used to group records by owner or scope. It is not just another JSON property; it is part of the eeCLOUD access model.

Typical reference meanings:

• Tenant identifier
• User identifier
• Device identifier
• Session identifier

await ee.Memory("orders").WriteAsync(
    new { total = 49.90m, status = "created" },
    reference: 1001
);

Why References Matter in DaaS

eeCLOUD is especially strong when the service can answer questions like:

• Give me the latest order for this tenant
• Return all telemetry for this device in the last hour
• Load the current session state for this user

var latest = await ee.Memory("orders")
    .ReadByReferenceAsync(1001);

var page = await ee.Memory("orders")
    .ReadAllAsync(1001, entries: 100);

This is one of the reasons eeCLOUD works well as a subscription DaaS: teams can start small on Free, then scale the same Application when reference-driven workloads become central to production.

What is Clustering?

Clustering is the optional physical partitioning model behind the service. It is activated on writes with clusterized: true, usually together with a meaningful reference.

await ee.Memory("orders").WriteAsync(
    id: "order-0001",
    data: new { total = 49.90m },
    reference: 1001,
    clusterized: true
);

Reference vs Cluster

You can use references without clustering. Clustering only becomes necessary when the workload or tenant count justifies extra physical partitioning.

How Reads Behave

Consumers keep reading through the same logical Memory API. Once the data has been written with clustering, read resolution remains automatic from the client point of view.

var current = await ee.Memory("orders")
    .ReadByReferenceAsync(1001);

var history = await ee.Memory("orders")
    .ReadAllAsync(1001, DateTime.UtcNow.AddDays(-7), DateTime.UtcNow);

Design Guidelines

• Always think about whether the record has an owner; if yes, model it with reference
• Use clustering for large multi-tenant or high-cardinality datasets, not by default everywhere
• Do not depend only on JSON fields for ownership if the dataset will be queried by owner frequently
• Keep reference stable through the lifecycle of a record whenever possible

Next