From 4413e4c236a298fda0b87898a1596365454859a2 Mon Sep 17 00:00:00 2001 From: Rod Vagg Date: Tue, 2 Apr 2024 12:06:26 +1100 Subject: [PATCH] docs(ddo,events): clarify indexing field --- documentation/en/actor-events-api.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/documentation/en/actor-events-api.md b/documentation/en/actor-events-api.md index b5b77d71515..9672ed60f1d 100644 --- a/documentation/en/actor-events-api.md +++ b/documentation/en/actor-events-api.md @@ -55,15 +55,13 @@ type EventEntry struct { } ``` -A `flags` field is used to convey metadata or hints about the entry, currently this is used to provide an indication of the suitability of that field for indexing when stored or when used for querying. +A `flags` field is used to convey metadata or hints about the entry, currently this is used to provide an indication of the suitability of that field for indexing. Suitability for indexing is only a hint, and typically relates to the queriability of the content of that field. * A `flag` of `0x00` indicates that neither the key nor value are suitable for indexing. * A `flag` of `0x01` indicates that the key only is suitable for indexing. * A `flag` of `0x02` indicates that the value is suitable for indexing. * A `flag` of `0x03` indicates that both the key and value are suitable for indexing. -Suitability for indexing is a hint, and will typically indicate the uniqueness of the content. For example if a value has an arbitrary number, such as a `piece-size`, it's unlikely to be suitable for building an index for. However, if a field such as a `"provider"` contains an actor ID, it is likely to be suitable for indexing because queries may be made for all events from a particular actor. - Typically events contain entires that use either use `0x01` or `0x03` flags. The structured logging style of composition should be seen in contrast to an alternative representation as a plain map or struct where the keys represent the fields of the event and the values represent the values of those fields. Some entries may duplicate keys, in which case that particular field of the event could be represented as an array. Builtin actor events are sufficiently well defined that translation to such a format is possible, but left up to the user.