fix(upsert): rename mupsert to upsert in full API

Author: wenkokke

README.md

@@ -24,8 +24,7 @@ It has support for:
 - Range lookups, which efficiently retrieve the values for all keys in a
   given range.
 
-- Monoidal upserts (or "mupserts") which combine the stored and new
-  values.
+- Monoidal upserts which combine the stored and new values.
 
 - BLOB storage which assocates a large auxiliary BLOB with a key.
 
@@ -43,9 +42,8 @@ This package exports two modules:
   This module exports a simplified API which picks sensible defaults for
   a number of configuration parameters.
 
-  It does not support mupserts or BLOBs, due to their unintuitive
-  interaction, see [Mupserts and
-  BLOBs](#mupsertsandblobs "#mupsertsandblobs").
+  It does not support upserts or BLOBs, due to their unintuitive
+  interaction, see [Upsert and BLOB](#upsertandblob "#upsertandblob").
 
   If you are looking at this package for the first time, it is strongly
   recommended that you start by reading this module.
@@ -54,13 +52,12 @@ This package exports two modules:
 
   This module exports the full API.
 
-### Mupserts and BLOBs <span id="mupsertsandblobs" class="anchor"></span>
+### Upsert and BLOB <span id="upsertandblob" class="anchor"></span>
 
-The interaction between mupserts and BLOBs is unintuitive. A mupsert
-updates the value associated with the key by combining the old and new
-value with a user-specified function. However, this does not apply to
-any BLOB value associated with the key, which is simply overwritten by
-the new BLOB value.
+The interaction between upserts and BLOBs is unintuitive. A upsert
+updates the value associated with the key by combining the new and old
+values with a user-specified function. However, any BLOB associated with
+the key is simply deleted.
 
 ### Portability <span id="portability" class="anchor"></span>
 

bench/macro/lsm-tree-bench-wp8.hs

@@ -868,8 +868,8 @@ updateToLookupResult :: LSM.Update v b -> LSM.LookupResult v ()
 updateToLookupResult (LSM.Insert v Nothing)  = LSM.Found v
 updateToLookupResult (LSM.Insert v (Just _)) = LSM.FoundWithBlob v ()
 updateToLookupResult  LSM.Delete             = LSM.NotFound
-updateToLookupResult (LSM.Mupsert _)         = error $
-                                               "Unexpected mupsert encountered"
+updateToLookupResult (LSM.Upsert _)         = error $
+                                               "Unexpected upsert encountered"
 
 -- | Return the adjacent batches where there is overlap between one batch's
 -- inserts and the next batch's lookups. Testing the pipelined version needs

bench/micro/Bench/Database/LSMTree.hs

@@ -33,9 +33,9 @@ benchmarks = bgroup "Bench.Database.LSMTree" [
       benchLargeValueVsSmallValueBlob
     , benchCursorScanVsRangeLookupScan
     , benchInsertBatches
-    , benchInsertsVsMupserts
-    , benchLookupsInsertsVsMupserts
-    , benchLookupInsertsVsLookupMupserts
+    , benchInsertsVsUpserts
+    , benchLookupsInsertsVsUpserts
+    , benchLookupInsertsVsLookupUpserts
     ]
 
 {-------------------------------------------------------------------------------
@@ -275,22 +275,22 @@ benchInsertBatches =
           cleanupFiles (tmpDir, hfs, hbio)
 
 {-------------------------------------------------------------------------------
-  Inserts vs. Mupserts
+  Inserts vs. Upserts
 -------------------------------------------------------------------------------}
 
--- | Compare inserts and mupserts. The logical contents of the resulting
+-- | Compare inserts and upserts. The logical contents of the resulting
 -- database are the same.
-benchInsertsVsMupserts :: Benchmark
-benchInsertsVsMupserts =
+benchInsertsVsUpserts :: Benchmark
+benchInsertsVsUpserts =
     env (pure $ snd $ randomEntriesGrouped 800_000 250) $ \ess ->
       env (pure $ V.map mkInserts ess) $ \inss ->
-        bgroup "inserts-vs-mupserts" [
+        bgroup "inserts-vs-upserts" [
           bench "inserts" $
             withEmptyTable $ \(_, _, _, _, t) ->
               V.mapM_ (inserts t) inss
-        , bench "mupserts" $
+        , bench "upserts" $
             withEmptyTable $ \(_, _, _, _, t) ->
-              V.mapM_ (mupserts t) ess
+              V.mapM_ (upserts t) ess
         ]
     where
       withEmptyTable =
@@ -305,18 +305,18 @@ benchInsertsVsMupserts =
             )
 
 {-------------------------------------------------------------------------------
-  Lookups plus Inserts vs. Mupserts
+  Lookups plus Inserts vs. Upserts
 -------------------------------------------------------------------------------}
 
--- | Compare lookups+inserts to mupserts. The former costs 2 LSMT operations,
---  while Mupserts only cost 1 LSMT operation. The number of operations do not
+-- | Compare lookups+inserts to upserts. The former costs 2 LSMT operations,
+--  while Upserts only cost 1 LSMT operation. The number of operations do not
 --  directly translate to the number of I\/O operations, but one can assume that
---  lookup+insert is roughly twice as costly as mupsert.
-benchLookupsInsertsVsMupserts :: Benchmark
-benchLookupsInsertsVsMupserts =
+--  lookup+insert is roughly twice as costly as upsert.
+benchLookupsInsertsVsUpserts :: Benchmark
+benchLookupsInsertsVsUpserts =
     env (pure $ snd $ randomEntriesGrouped 800_000 250) $ \ess ->
       env (pure $ V.map mkInserts ess) $ \inss ->
-        bgroup "lookups-inserts-vs-mupserts" [
+        bgroup "lookups-inserts-vs-upserts" [
           bench "lookups-inserts" $
             withTable inss $ \(_, _, _, _, t) ->
               -- Insert the same keys again, but we sum the existing values in
@@ -327,12 +327,12 @@ benchLookupsInsertsVsMupserts =
                 lrs <- lookups t (V.map fst es)
                 let ins' = V.zipWith f es lrs
                 inserts t ins'
-        , bench "mupserts" $
+        , bench "upserts" $
             withTable inss $ \(_, _, _, _, t) ->
               -- Insert the same keys again, but we sum the existing values in
               -- the table with the values we are going to insert: submit
-              -- mupserts with the insert values.
-              V.forM_ ess $ \es -> mupserts t es
+              -- upserts with the insert values.
+              V.forM_ ess $ \es -> upserts t es
         ]
   where
     f (k, v) = \case
@@ -353,20 +353,20 @@ benchLookupsInsertsVsMupserts =
           )
 
 {-------------------------------------------------------------------------------
-  Lookup Inserts vs. Lookup Mupserts
+  Lookup Inserts vs. Lookup Upserts
 -------------------------------------------------------------------------------}
 
--- | Compare lookups after inserts against lookups after mupserts.
-benchLookupInsertsVsLookupMupserts :: Benchmark
-benchLookupInsertsVsLookupMupserts =
+-- | Compare lookups after inserts against lookups after upserts.
+benchLookupInsertsVsLookupUpserts :: Benchmark
+benchLookupInsertsVsLookupUpserts =
     env (pure $ snd $ randomEntriesGrouped 80_000 250) $ \ess ->
       env (pure $ V.map mkInserts ess) $ \inss ->
-        bgroup "lookup-inserts-vs-lookup-mupserts" [
+        bgroup "lookup-inserts-vs-lookup-upserts" [
           bench "lookup-inserts" $
             withInsertTable inss $ \(_, _, _, _, t) -> do
                 V.forM_ ess $ \es -> lookups t (V.map fst es)
-        , bench "lookup-mupserts" $
-            withMupsertTable ess $ \(_, _, _, _, t) -> do
+        , bench "lookup-upserts" $
+            withUpsertTable ess $ \(_, _, _, _, t) -> do
                 V.forM_ ess $ \es -> lookups t (V.map fst es)
         ]
   where
@@ -387,14 +387,14 @@ benchLookupInsertsVsLookupMupserts =
               cleanupFiles (tmpDir, hfs, hbio)
           )
 
-    withMupsertTable ess =
+    withUpsertTable ess =
         perRunEnvWithCleanup
-          -- Mupsert the same key 10 times. The results in a logical database
+          -- Upsert the same key 10 times. The results in a logical database
           -- containing the original keys with the original value *10.
           (do (tmpDir, hfs, hbio) <- mkFiles
               (s, t) <- mkTable hfs hbio benchConfig
               V.forM_ [1..10] $ \(_::Int) ->
-                V.mapM_ (mupserts t) ess
+                V.mapM_ (upserts t) ess
               pure (tmpDir, hfs, hbio, s, t)
           )
           (\(tmpDir, hfs, hbio, s, t) -> do

doc/format-page.md

@@ -25,7 +25,7 @@ Logically, a page consists of a value of type
 type Page = [(Key, Operation, Maybe BlobRef)]
 ```
 where the operation can be insert (with a value), delete (with no value) or
-mupsert (with a value). The entries are sorted by key.
+upsert (with a value). The entries are sorted by key.
 
 The file is structured in a page-oriented way to support efficient I/O using
 random page-sized reads. By page-oriented we mean that the information is

lsm-tree.cabal

@@ -9,7 +9,7 @@ description:
 
   *   Basic key–value operations, such as lookup, insert, and delete.
   *   Range lookups, which efficiently retrieve the values for all keys in a given range.
-  *   Monoidal upserts (or \"mupserts\") which combine the stored and new values.
+  *   Monoidal upserts which combine the stored and new values.
   *   BLOB storage which assocates a large auxiliary BLOB with a key.
   *   Durable on-disk persistence and rollback via named snapshots.
   *   Cheap table duplication where all duplicates can be independently accessed and modified.
@@ -21,19 +21,19 @@ description:
 
       This module exports a simplified API which picks sensible defaults for a number of configuration parameters.
 
-      It does not support mupserts or BLOBs, due to their unintuitive interaction, see [Mupserts and BLOBs](#mupsertsandblobs).
+      It does not support upserts or BLOBs, due to their unintuitive interaction, see [Upsert and BLOB](#upsertandblob).
 
       If you are looking at this package for the first time, it is strongly recommended that you start by reading this module.
 
   *   "Database.LSMTree"
 
       This module exports the full API.
 
-  == Mupserts and BLOBs #mupsertsandblobs#
+  == Upsert and BLOB #upsertandblob#
 
-  The interaction between mupserts and BLOBs is unintuitive.
-  A mupsert updates the value associated with the key by combining the old and new value with a user-specified function.
-  However, this does not apply to any BLOB value associated with the key, which is simply overwritten by the new BLOB value.
+  The interaction between upserts and BLOBs is unintuitive.
+  A upsert updates the value associated with the key by combining the new and old values with a user-specified function.
+  However, any BLOB associated with the key is simply deleted.
 
   == Portability #portability#
 

src-extras/Database/LSMTree/Extras/Generators.hs

@@ -83,7 +83,7 @@ instance (Arbitrary v, Arbitrary b) => Arbitrary (Full.Update v b) where
 instance Arbitrary2 Full.Update where
   liftArbitrary2 genVal genBlob = frequency
     [ (10, Full.Insert <$> genVal <*> liftArbitrary genBlob)
-    , (5, Full.Mupsert <$> genVal)
+    , (5, Full.Upsert <$> genVal)
     , (1, pure Full.Delete)
     ]
 
@@ -92,7 +92,7 @@ instance Arbitrary2 Full.Update where
         Full.Delete
       : map (uncurry Full.Insert)
             (liftShrink2 shrinkVal (liftShrink shrinkBlob) (v, blob))
-    Full.Mupsert v -> Full.Insert v Nothing : map Full.Mupsert (shrinkVal v)
+    Full.Upsert v -> Full.Insert v Nothing : map Full.Upsert (shrinkVal v)
     Full.Delete -> []
 
 instance (Arbitrary k, Ord k) => Arbitrary (Range k) where

src/Database/LSMTree.hs

@@ -47,8 +47,8 @@ module Database.LSMTree (
   -- ** Table Updates #table_updates#
   insert,
   inserts,
-  mupsert,
-  mupserts,
+  upsert,
+  upserts,
   delete,
   deletes,
   Update (..),
@@ -1061,26 +1061,26 @@ upsert table k v = do
 @
 -}
 {-# SPECIALISE
-  mupsert ::
+  upsert ::
     (SerialiseKey k, ResolveValue v, SerialiseValue b) =>
     Table IO k v b ->
     k ->
     v ->
     IO ()
   #-}
-mupsert ::
+upsert ::
   forall m k v b.
   (IOLike m) =>
   (SerialiseKey k, ResolveValue v, SerialiseValue b) =>
   Table m k v b ->
   k ->
   v ->
   m ()
-mupsert table k v =
-  mupserts table (V.singleton (k, v))
+upsert table k v =
+  upserts table (V.singleton (k, v))
 
 {- |
-Variant of 'mupsert' for batch insertions.
+Variant of 'upsert' for batch insertions.
 
 The worst-case disk I\/O complexity of this operation depends on the merge policy of the table:
 
@@ -1091,24 +1091,24 @@ The variable \(b\) refers to the length of the input vector.
 
 The following property holds in the absence of races:
 
-prop> mupserts table entries = traverse_ (uncurry $ mupsert table) entries
+prop> upserts table entries = traverse_ (uncurry $ upsert table) entries
 -}
 {-# SPECIALISE
-  mupserts ::
+  upserts ::
     (SerialiseKey k, ResolveValue v, SerialiseValue b) =>
     Table IO k v b ->
     Vector (k, v) ->
     IO ()
   #-}
-mupserts ::
+upserts ::
   forall m k v b.
   (IOLike m) =>
   (SerialiseKey k, ResolveValue v, SerialiseValue b) =>
   Table m k v b ->
   Vector (k, v) ->
   m ()
-mupserts table entries =
-  updates table (second Mupsert <$> entries)
+upserts table entries =
+  updates table (second Upsert <$> entries)
 
 {- |
 Delete a key from the table.
@@ -1195,15 +1195,15 @@ type Update :: Type -> Type -> Type
 data Update v b
   = Insert !v !(Maybe b)
   | Delete
-  | Mupsert !v
+  | Upsert !v
   deriving stock (Show, Eq)
 
 instance (NFData v, NFData b) => NFData (Update v b) where
   rnf :: Update v b -> ()
   rnf = \case
     Insert v mb -> rnf v `seq` rnf mb
     Delete -> ()
-    Mupsert v -> rnf v
+    Upsert v -> rnf v
 
 {- |
 Update generalises 'insert', 'delete', and 'upsert'.
@@ -1281,7 +1281,7 @@ updates (Table table :: Table m k v b) entries =
     Insert v (Just b) -> Entry.InsertWithBlob (Internal.serialiseValue v) (Internal.serialiseBlob b)
     Insert v Nothing -> Entry.Insert (Internal.serialiseValue v)
     Delete -> Entry.Delete
-    Mupsert v -> Entry.Mupdate (Internal.serialiseValue v)
+    Upsert v -> Entry.Mupdate (Internal.serialiseValue v)
 
 --------------------------------------------------------------------------------
 -- Duplication

src/Database/LSMTree/Internal/Types.hs

@@ -1,3 +1,5 @@
+{-# OPTIONS_HADDOCK not-home #-}
+
 module Database.LSMTree.Internal.Types (
     Session (..),
     Table (..),
@@ -109,7 +111,7 @@ instance NFData (Cursor m k v b) where
 
 {- |
 An instance of @'ResolveValue' v@ specifies how to merge values when using
-monoidal upserts ('mupsert').
+monoidal upsert.
 
 The class has two functions.
 The function 'resolve' acts on values, whereas the function 'resolveSerialised' acts on serialised values.
@@ -193,7 +195,7 @@ instance (SerialiseValue v, Semigroup v) => ResolveValue (ResolveViaSemigroup v)
   resolve (ResolveViaSemigroup v1) (ResolveViaSemigroup v2) = ResolveViaSemigroup (v1 <> v2)
 
 {- |
-Wrapper that provides an instance of 'ResolveValue' such that 'mupsert' behaves as 'insert'.
+Wrapper that provides an instance of 'ResolveValue' such that 'Database.LSMTree.upsert' behaves as 'Database.LSMTree.insert'.
 
 The name 'ResolveAsFirst' is in reference to the wrapper 'Data.Semigroup.First' from "Data.Semigroup".
 

src/Database/LSMTree/Internal/Unsafe.hs

@@ -1,4 +1,5 @@
 {-# LANGUAGE DataKinds #-}
+{-# OPTIONS_HADDOCK not-home #-}
 
 -- | This module brings together the internal parts to provide an API in terms
 -- of untyped serialised keys, values and blobs.
@@ -841,7 +842,7 @@ rangeLookup resolve range t fromEntry = do
   -> IO () #-}
 -- | See 'Database.LSMTree.updates'.
 --
--- Does not enforce that mupsert and blobs should not occur in the same table.
+-- Does not enforce that upsert and BLOBs should not occur in the same table.
 updates ::
      (MonadMask m, MonadMVar m, MonadST m, MonadSTM m)
   => ResolveSerialisedValue

test/Database/LSMTree/Class.hs

@@ -278,7 +278,7 @@ instance IsTable R.Table where
     updates = R.updates
     inserts = R.inserts
     deletes = R.deletes
-    mupserts = R.mupserts
+    mupserts = R.upserts
 
     rangeLookup = R.rangeLookup
     retrieveBlobs _ = R.retrieveBlobs