(in)consistent use of "entity key" and "entity id"

[Marcel Lanz]

The use of the terms Entity Key and Entity Id seem not to be consistently used or their relationship is not explicitly described in the documentation.

While the Cloudstate protocol uses entity_id, that also surfaces to the API on different points, most of the documentation describes the thing that is used to identify instances of an entity as entity keys. Nonetheless, someone reading the documentation and code finds the term entity id which might be confusing.

Also, it can be, that both might be valid terms with their context, where entity key is a frontend related term and entity id a backend or implementation-specific, but entity ids still can be found for the user through generated code of protobufs to the API.

Following, uses of both terms are listed:

Use of "Entity Key"

The documentation with its glossary of terms introduces entities and the entity key by:

A key used to identify instances of an Entity.

The cloudstate documentation describes how to specify the entity key and states that:

The entity key is used by Cloudstate to know which instance of an entity a command is for.

The cloudstate.com documentation describes the key as:

One instance of the entity should be differentated from any other by means of a unique "key".

Use of "Entity Id"

The projects main README.md states:

It also contains the payload of that gRPC call, along with an extracted entity id, that identifies which entity the call is for. Entity ids are declared through the use of a Protobuf field extension

The Terminology section in the eventsourced documentation states:

The persistence id is an identifier that is prepended to each entity id when persisted

and JVM based user support libraries held an @EntityId annotation to get the "The ID of the entity" injected.

Regarding the Cloudstate Protocol, Commands have entity ids:
https://github.com/cloudstateio/cloudstate/blob/v0.5.1/protocols/protocol/cloudstate/entity.proto#L82

and both CRDT and Eventsourced types have them:
https://github.com/cloudstateio/cloudstate/blob/v0.5.1/protocols/protocol/cloudstate/crdt.proto#L307
https://github.com/cloudstateio/cloudstate/blob/v0.5.1/protocols/protocol/cloudstate/event_sourced.proto#L36

[Viktor Klang (√)]

@marcellanz The way I've been thinking about it is that (1..N) entity_keys make up an Entity ID. Since you can have multiple keys annotated.

[Adriano Santos]

@viktorklang Can we have several keys annotated for the same entity? This is new to me. How does the proxy handle this?

[Viktor Klang (√)]

@sleipnir Yes! https://cloudstate.io/docs/core/current/user/features/index.html#entity-key It definitely needs to be better explained, but the different fields annotated with entity_key are concatenated to form a single identifier. Clearly documentation regardin this should be improved.

[Adriano Santos]

Thanks @viktorklang I had not been aware of this detail. And as we don't have examples like that, I ended up not realizing the possibility.

[Viktor Klang (√)]

@sleipnir Indeed, I created an Issue to elaborate on that in the documentation. :)

[Marcel Lanz]

This Issue seems not to be accurate as an entity id can be composed of more than one entity key. #400 was openend to address the documentation of the relation of both terms and I suggest to close this issue then.