From 182395ee00665bc8869bd9f3c6b6ebb3b65fbce6 Mon Sep 17 00:00:00 2001
From: Martin Sumner <martin.sumner@adaptip.co.uk>
Date: Wed, 9 Dec 2020 09:18:38 +0000
Subject: [PATCH] Schema clarifications

---
 priv/leveled.schema       | 16 ++++++++++------
 priv/leveled_multi.schema | 22 ++++++++++++++++------
 2 files changed, 26 insertions(+), 12 deletions(-)

diff --git a/priv/leveled.schema b/priv/leveled.schema
index 50875487..4b7c273c 100644
--- a/priv/leveled.schema
+++ b/priv/leveled.schema
@@ -11,7 +11,7 @@
 %% @doc Strategy for flushing data to disk
 %% Can be set to riak_sync, sync (if OTP > 16) or none.  Use none, and the OS
 %% will flush when most efficient.  Use riak_sync or sync to flush after every
-%% PUT (not recommended wihtout some hardware support e.g. flash drives and/or
+%% PUT (not recommended without some hardware support e.g. flash drives and/or
 %% Flash-backed Write Caches) 
 {mapping, "leveled.sync_strategy", "leveled.sync_strategy", [
   {default, none},
@@ -100,9 +100,11 @@
   {datatype, integer}
 ]}.
 
-%% @doc The number of times per day to score an individual file for compaction
+%% @doc The number of times per day to score an individual file for compaction.
+%% The default value will lead to each file, on average, being scored once
+%% every 8 hours
 {mapping, "leveled.compaction_scores_perday", "leveled.compaction_scores_perday", [
-  {default, 1},
+  {default, 3},
   {datatype, integer}
 ]}.
 
@@ -126,7 +128,9 @@
 
 %% @doc Max Journal Files Per Compaction Run
 %% In a single compaction run, what is the maximum number of consecutive files
-%% which may be compacted.
+%% which may be compacted.  If increasing this value, the average number of
+%% files per run may decrease, unless adjustments are also made to the
+%% maxrunlength and singlefile compactionpercentage settings.
 {mapping, "leveled.max_run_length", "leveled.max_run_length", [
   {default, 4},
   {datatype, integer}
@@ -146,10 +150,10 @@
 %% @doc Target Percentage for Single File
 %% What is the target score for a run of a single file, to qualify for 
 %% compaction.  If less than this percentage would be retained after compaction
-%% then it is a candidate (e.g. in default case if 70% of space would be
+%% then it is a candidate (e.g. in default case if 75% of space would be
 %% recovered)
 {mapping, "leveled.singlefile_compactionpercentage", "leveled.singlefile_compactionpercentage", [
-  {default, 30.0},
+  {default, 25.0},
   {datatype, float},
   hidden
 ]}.
diff --git a/priv/leveled_multi.schema b/priv/leveled_multi.schema
index d1cc0d31..faa825db 100644
--- a/priv/leveled_multi.schema
+++ b/priv/leveled_multi.schema
@@ -12,7 +12,7 @@
 %% @doc Strategy for flushing data to disk
 %% Can be set to riak_sync, sync (if OTP > 16) or none.  Use none, and the OS
 %% will flush when most efficient.  Use riak_sync or sync to flush after every
-%% PUT (not recommended wihtout some hardware support e.g. flash drives and/or
+%% PUT (not recommended without some hardware support e.g. flash drives and/or
 %% Flash-backed Write Caches) 
 {mapping, "multi_backend.$name.leveled.sync_strategy", "riak_kv.multi_backend", [
   {default, none},
@@ -91,11 +91,19 @@
 %% The higher the value, the more compaction runs, and the sooner space is 
 %% recovered.  But each run has a cost
 {mapping, "multi_backend.$name.leveled.compaction_runs_perday", "riak_kv.multi_backend", [
-  {default, 16},
+  {default, 24},
   {datatype, integer},
   hidden
 ]}.
 
+%% @doc The number of times per day to score an individual file for compaction
+%% The default value will lead to each file, on average, being scored once
+%% every 8 hours
+{mapping, "multi_backend.$name.leveled.compaction_scores_perday", "riak_kv.multi_backend", [
+  {default, 3},
+  {datatype, integer}
+]}.
+
 %% @doc Compaction Low Hour
 %% The hour of the day in which journal compaction can start.  Use Low hour 
 %% of 0 and High hour of 23 to have no compaction window (i.e. always compact 
@@ -118,9 +126,11 @@
 
 %% @doc Max Journal Files Per Compaction Run
 %% In a single compaction run, what is the maximum number of consecutive files
-%% which may be compacted.
+%% which may be compacted.  If increasing this value, the average number of
+%% files per run may decrease, unless adjustments are also made to the
+%% maxrunlength and singlefile compactionpercentage settings.
 {mapping, "multi_backend.$name.leveled.max_run_length", "riak_kv.multi_backend", [
-  {default, 6},
+  {default, 4},
   {datatype, integer},
   hidden
 ]}.
@@ -139,10 +149,10 @@
 %% @doc Target Percentage for Single File
 %% What is the target score for a run of a single file, to qualify for 
 %% compaction.  If less than this percentage would be retained after compaction
-%% then it is a candidate (e.g. in default case if 50% of space would be
+%% then it is a candidate (e.g. in default case if 25% of space would be
 %% recovered)
 {mapping, "multi_backend.$name.leveled.singlefile_compactionpercentage", "riak_kv.multi_backend", [
-  {default, 50.0},
+  {default, 25.0},
   {datatype, float},
   hidden
 ]}.