References and Clusters

What is a Reference?

A reference is a numeric value used to logically group records inside a Memory. It is a first-class dimension of the eeCLOUD engine, not a JSON field.

References are commonly used to represent:

• User identifiers
• Tenant identifiers
• Session identifiers
• Device identifiers

await app.WriteData(
    "myApp",
    "orders",
    new { total = 49.90 },
    reference: userId
);

What is a Cluster?

A cluster is a physical partition of a Memory. When clustering is enabled, records are stored in separate tables or partitions based on their reference.

Clusters are designed to:

• Improve performance at scale
• Enable linear growth
• Isolate tenants physically
• Reduce index size

await app.WriteData(
    "myApp",
    "orders",
    new { total = 49.90 },
    reference: userId,
    clusterized: true
);

Reference vs Cluster

References and clusters serve different purposes and can be used independently or together.

• Reference: logical grouping, always available
• Cluster: physical partitioning, optional

In small datasets, a reference alone is often sufficient. In large multi-tenant systems, combining reference and clustering provides optimal performance and isolation.

Design Guidelines

• Use references whenever data belongs to a logical owner
• Enable clustering for high-cardinality references
• Do not encode ownership inside JSON fields
• Prefer engine-level dimensions over application-level filters

Write Model & Data Lifecycle