From 844aa5084d92455c986cc1f1264c0d1ae018089b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=90=B4=E6=99=9F=20Wu=20Sheng?= <wu.sheng@foxmail.com>
Date: Sun, 5 Jan 2025 11:01:16 +0800
Subject: [PATCH] Add more comments for IndexMode (#12930)

---
 .../core/storage/annotation/BanyanDB.java     | 30 ++++++++++++++++++-
 1 file changed, 29 insertions(+), 1 deletion(-)

diff --git a/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/storage/annotation/BanyanDB.java b/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/storage/annotation/BanyanDB.java
index f907536ec56c..7d0cd6469be1 100644
--- a/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/storage/annotation/BanyanDB.java
+++ b/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/storage/annotation/BanyanDB.java
@@ -24,7 +24,9 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import org.apache.skywalking.oap.server.core.analysis.metrics.Metrics;
 import org.apache.skywalking.oap.server.core.analysis.record.Record;
+import org.apache.skywalking.oap.server.core.storage.StorageID;
 
 /**
  * BanyanDB annotation is a holder including all annotations for BanyanDB storage
@@ -125,7 +127,8 @@ enum IndexType {
     /**
      * MeasureField defines a column as a measure's field.
      * The measure field has a significant difference from no-indexing tag.
-     * The measure fields are stored in another file, but no-indexing tag is stored in the same file with the indexing tags.
+     * The measure fields are stored in another file, but no-indexing tag is stored in the same file with the indexing
+     * tags.
      * <p>
      * Annotated: the column is a measure field.
      * Unannotated: the column is a measure tag.
@@ -211,6 +214,7 @@ enum AnalyzerType {
 
     /**
      * EnableSort is used to indicate the IndexRule supports sorting.
+     *
      * @since 10.2.0
      */
     @Target({ElementType.FIELD})
@@ -220,6 +224,30 @@ enum AnalyzerType {
 
     /**
      * IndexMode is used to indicate the index mode of the metric.
+     * IndexMode metric is a half-time series metric, which means the metric is time relative, and still affected by
+     * metric TTL, but its ID doesn't include time bucket. The entity has a unique name to represent the entity.
+     * <p>
+     * The entity should be a kind of metadata entity, e.g. ServiceTraffic.
+     * The return({@link StorageID} of {@link Metrics#id()} should not include any time relative column.
+     * <pre>
+     * <code>
+     *         return new StorageID().appendMutant(new String[] {
+     *             NAME,
+     *             LAYER
+     *         }, id);
+     * </code>
+     * </pre>
+     * <p>
+     * A metric with complete(not IndexMode) time series data includes the TIME_BUCKET column in the ID.
+     * <pre>
+     * <code>
+     *          return new StorageID()
+     *             .append(TIME_BUCKET, getTimeBucket())
+     *             .append(ENTITY_ID, getEntityId());
+     * </code>
+     * </pre>
+     *
+     * <p>
      * All columns in the metric will be stored in the index exclusively.
      * When an entity column is not used in query condition, only {@link Column#storageOnly()} is allowed.
      * No {@link MeasureField} is allowed for those columns in IndexMode entity.