Synthetic record orphan policy (#3271)

Add support for `orphanPolicy` when loading synthetic records. This is
necessary for the ability to scrub indexes with synthetic records as
dangling index entries, by definition, have no records to back them up.
As part of this PR we've also disabled the repair of synthetic records
as part of the scrubbing until we test this feature more thoroughly.
Also of note: Implementors of the `EXPERIMENTAL` `SyntheticRecordType`
interface will see a change that requires the implementation of another
method (or add the new parameter to the existing one).
As far as the "breaking change" label: The scrubbing for dangling index
entries now uses a `RETURN` policy (default was `ERROR`) which means
that previous requests that used to fail now pass (if the record was
missing). Also, any request to scrub synthetic record with repair `on`
will now fail.

Author: ohadzeliger

fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/metadata/JoinedRecordType.java

@@ -29,6 +29,7 @@
 import com.apple.foundationdb.record.provider.foundationdb.FDBRecordStore;
 import com.apple.foundationdb.record.provider.foundationdb.FDBStoredRecord;
 import com.apple.foundationdb.record.provider.foundationdb.FDBSyntheticRecord;
+import com.apple.foundationdb.record.provider.foundationdb.IndexOrphanBehavior;
 import com.apple.foundationdb.record.provider.foundationdb.RecordDoesNotExistException;
 import com.apple.foundationdb.tuple.Tuple;
 import com.google.protobuf.Descriptors;
@@ -39,9 +40,33 @@
 import java.util.Map;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.atomic.AtomicBoolean;
 
 /**
  * A <i>synthetic</i> record type representing the indexable result of <em>joining</em> stored records.
+ * <p>
+ * Joined record represents a collection of <i>joined constituents</i>, each represented by another record in the database.
+ * The constituents are joined together by a <i>join condition</i>: in this case, a set of fields that are tested for
+ * equality across all constituents.
+ * The joined record primary key is represented by a Tuple as follows:
+ * <pre>
+ *     [{record type}, {elements of constituent 1 PK}, ... {elements of constituent n PK}]
+ * </pre>
+ * When loading a joined record, the joined record primary key is used to iterate and load each constituent, eventually
+ * combining the collection of constituents into the completed record.
+ * <p>
+ * There is nothing special needed to be done to save a joined record. Once the constituent records are saved
+ * a joined record instance is implicitly assumed to exist. A subsequent {@link #loadByPrimaryKeyAsync(FDBRecordStore, Tuple, IndexOrphanBehavior)}
+ * or a query for the record or a scan of a joined index will create the joined record. similarly, a deletion
+ * of any or all of the constituents will implicitly render the joined record type deleted.
+ * <p>
+ * When loading a joined record (and similarly when scanning an index) an {@link IndexOrphanBehavior} can be used
+ * to determine the behavior in case one or more of the constituents are missing:
+ * <ul>
+ *     <li>{@link IndexOrphanBehavior#ERROR} (the default) will throw an exception</li>
+ *     <li>{@link IndexOrphanBehavior#RETURN} will return an instance of the records with no constituents</li>
+ *     <li>{@link IndexOrphanBehavior#SKIP} will return null</li>
+ * </ul>
  */
 @API(API.Status.EXPERIMENTAL)
 public class JoinedRecordType extends SyntheticRecordType<JoinedRecordType.JoinConstituent> {
@@ -124,10 +149,11 @@ public List<Join> getJoins() {
     @Nonnull
     @Override
     @API(API.Status.INTERNAL)
-    public CompletableFuture<FDBSyntheticRecord> loadByPrimaryKeyAsync(FDBRecordStore store, Tuple primaryKey) {
+    public CompletableFuture<FDBSyntheticRecord> loadByPrimaryKeyAsync(FDBRecordStore store, Tuple primaryKey, IndexOrphanBehavior orphanBehavior) {
         int nconstituents = getConstituents().size();
         final Map<String, FDBStoredRecord<? extends Message>> constituentValues = new ConcurrentHashMap<>(nconstituents);
         final CompletableFuture<?>[] futures = new CompletableFuture<?>[nconstituents];
+        AtomicBoolean isMissingConstituent = new AtomicBoolean(false);
         for (int i = 0; i < nconstituents; i++) {
             final SyntheticRecordType.Constituent constituent = getConstituents().get(i);
             final Tuple constituentKey = primaryKey.getNestedTuple(i + 1);
@@ -136,17 +162,37 @@ public CompletableFuture<FDBSyntheticRecord> loadByPrimaryKeyAsync(FDBRecordStor
             } else {
                 futures[i] = store.loadRecordAsync(constituentKey).thenApply(rec -> {
                     if (rec == null) {
-                        throw new RecordDoesNotExistException("constituent record not found: " + constituent.getName());
+                        if (orphanBehavior.equals(IndexOrphanBehavior.ERROR)) {
+                            throw new RecordDoesNotExistException("constituent record not found: " + constituent.getName());
+                        } else {
+                            // For SKIP and RETURN
+                            isMissingConstituent.set(true);
+                            // ideally, we should be able to stop the iteration to fetch all other constituents
+                            // but because of the async nature of the loop this seems to be not worth it
+                        }
+                    } else {
+                        constituentValues.put(constituent.getName(), rec);
                     }
-                    constituentValues.put(constituent.getName(), rec);
                     return null;
                 });
             }
         }
-        return CompletableFuture.allOf(futures).thenApply(vignore -> FDBSyntheticRecord.of(this, constituentValues));
+        return CompletableFuture.allOf(futures).thenApply(vignore -> {
+            if ( ! isMissingConstituent.get()) {
+                // all constituents have been found
+                return FDBSyntheticRecord.of(this, constituentValues);
+            } else {
+                // some constituents are missing
+                if (orphanBehavior.equals(IndexOrphanBehavior.SKIP)) {
+                    return null;
+                } else {
+                    // This is for RETURN - return the shell of the record with no constituents
+                    return FDBSyntheticRecord.of(this, Map.of());
+                }
+            }
+        });
     }
 
-
     @Nonnull
     public RecordMetaDataProto.JoinedRecordType toProto() {
         RecordMetaDataProto.JoinedRecordType.Builder typeBuilder = RecordMetaDataProto.JoinedRecordType.newBuilder()

fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/metadata/SyntheticRecordType.java

@@ -25,6 +25,7 @@
 import com.apple.foundationdb.record.metadata.expressions.KeyExpression;
 import com.apple.foundationdb.record.provider.foundationdb.FDBRecordStore;
 import com.apple.foundationdb.record.provider.foundationdb.FDBSyntheticRecord;
+import com.apple.foundationdb.record.provider.foundationdb.IndexOrphanBehavior;
 import com.apple.foundationdb.tuple.Tuple;
 import com.google.protobuf.Descriptors;
 
@@ -89,7 +90,13 @@ public boolean isSynthetic() {
 
     @API(API.Status.INTERNAL)
     @Nonnull
-    public abstract CompletableFuture<FDBSyntheticRecord> loadByPrimaryKeyAsync(FDBRecordStore store, Tuple primaryKey);
+    public CompletableFuture<FDBSyntheticRecord> loadByPrimaryKeyAsync(FDBRecordStore store, Tuple primaryKey) {
+        return loadByPrimaryKeyAsync(store, primaryKey, IndexOrphanBehavior.ERROR);
+    }
+
+    @API(API.Status.INTERNAL)
+    @Nonnull
+    public abstract CompletableFuture<FDBSyntheticRecord> loadByPrimaryKeyAsync(FDBRecordStore store, Tuple primaryKey, IndexOrphanBehavior orphanBehavior);
 
     @Override
     public String toString() {

fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/metadata/UnnestedRecordType.java

@@ -30,6 +30,7 @@
 import com.apple.foundationdb.record.provider.foundationdb.FDBRecordStore;
 import com.apple.foundationdb.record.provider.foundationdb.FDBStoredRecord;
 import com.apple.foundationdb.record.provider.foundationdb.FDBSyntheticRecord;
+import com.apple.foundationdb.record.provider.foundationdb.IndexOrphanBehavior;
 import com.apple.foundationdb.record.provider.foundationdb.RecordDoesNotExistException;
 import com.apple.foundationdb.tuple.Tuple;
 import com.google.protobuf.Descriptors;
@@ -262,12 +263,21 @@ public NestedConstituent getParentConstituent() {
     @Override
     @Nonnull
     @API(API.Status.INTERNAL)
-    public CompletableFuture<FDBSyntheticRecord> loadByPrimaryKeyAsync(@Nonnull final FDBRecordStore store, @Nonnull final Tuple primaryKey) {
+    public CompletableFuture<FDBSyntheticRecord> loadByPrimaryKeyAsync(@Nonnull final FDBRecordStore store, @Nonnull final Tuple primaryKey, IndexOrphanBehavior orphanBehavior) {
         Tuple parentPrimaryKey = primaryKey.getNestedTuple(1);
         return store.loadRecordAsync(parentPrimaryKey).thenApply(storedRecord -> {
             if (storedRecord == null) {
-                throw new RecordDoesNotExistException("constituent record not found: " + parentConstituent.getName())
-                        .addLogInfo(LogMessageKeys.PRIMARY_KEY, parentPrimaryKey);
+                switch (orphanBehavior) {
+                    case ERROR:
+                        throw new RecordDoesNotExistException("constituent record not found: " + parentConstituent.getName())
+                                .addLogInfo(LogMessageKeys.PRIMARY_KEY, parentPrimaryKey);
+                    case SKIP:
+                        return null;
+                    case RETURN:
+                        return FDBSyntheticRecord.of(this, Map.of());
+                    default:
+                        throw new IllegalArgumentException("Unknown orphanBehavior value: " + orphanBehavior);
+                }
             }
             Map<String, FDBStoredRecord<?>> constituentValues = new HashMap<>();
             constituentValues.put(getParentConstituent().getName(), storedRecord);
@@ -285,8 +295,18 @@ public CompletableFuture<FDBSyntheticRecord> loadByPrimaryKeyAsync(@Nonnull fina
                         int childConstituentIndex = getConstituents().indexOf(constituent);
                         int childElemIndex = (int) primaryKey.getNestedTuple(childConstituentIndex + 1).getLong(0);
                         if (childElemIndex >= childElems.size()) {
-                            throw new RecordCoreException("child element position is too large")
-                                    .addLogInfo(LogMessageKeys.CHILD_COUNT, childElems.size());
+                            // Constituent not found
+                            switch (orphanBehavior) {
+                                case ERROR:
+                                    throw new RecordCoreException("child element position is too large")
+                                            .addLogInfo(LogMessageKeys.CHILD_COUNT, childElems.size());
+                                case SKIP:
+                                    return null;
+                                case RETURN:
+                                    return FDBSyntheticRecord.of(this, Map.of());
+                                default:
+                                    throw new IllegalArgumentException("Unknown orphanBehavior value: " + orphanBehavior);
+                            }
                         }
                         Key.Evaluated childElem = childElems.get(childElemIndex);
                         Message childMessage = childElem.getObject(0, Message.class);

fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/provider/foundationdb/FDBRecordStore.java

@@ -817,12 +817,12 @@ private CompletableFuture<Void> runSyntheticMaintainers(@Nonnull Map<RecordType,
     @API(API.Status.EXPERIMENTAL)
     @Nonnull
     @Override
-    public CompletableFuture<FDBSyntheticRecord> loadSyntheticRecord(@Nonnull Tuple primaryKey) {
+    public CompletableFuture<FDBSyntheticRecord> loadSyntheticRecord(@Nonnull Tuple primaryKey, final IndexOrphanBehavior orphanBehavior) {
         SyntheticRecordType<?> syntheticRecordType = getRecordMetaData().getSyntheticRecordTypeFromRecordTypeKey(primaryKey.get(0));
         if (syntheticRecordType.getConstituents().size() != primaryKey.size() - 1) {
             throw recordCoreException("Primary key does not have correct number of nested keys: " + primaryKey);
         }
-        return syntheticRecordType.loadByPrimaryKeyAsync(this, primaryKey);
+        return syntheticRecordType.loadByPrimaryKeyAsync(this, primaryKey, orphanBehavior);
     }
 
     @Nonnull

fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/provider/foundationdb/FDBRecordStoreBase.java

@@ -720,7 +720,25 @@ default CompletableFuture<FDBStoredRecord<M>> loadRecordAsync(@Nonnull final Tup
      */
     @Nonnull
     @API(API.Status.EXPERIMENTAL)
-    CompletableFuture<FDBSyntheticRecord> loadSyntheticRecord(@Nonnull Tuple primaryKey);
+    default CompletableFuture<FDBSyntheticRecord> loadSyntheticRecord(@Nonnull Tuple primaryKey) {
+        return loadSyntheticRecord(primaryKey, IndexOrphanBehavior.ERROR);
+    }
+
+    /**
+     * Load a {@link FDBSyntheticRecord synthetic record} by loading its stored constituent records and synthesizing it from them.
+     * In case any of the constituents are missing, the following will be returned:
+     * <ul>
+     * <li>{@link IndexOrphanBehavior#ERROR}: Exception is thrown</li>
+     * <li>{@link IndexOrphanBehavior#SKIP}: Future(null) is returned</li>
+     * <li>{@link IndexOrphanBehavior#RETURN}: Future(Record with no constituents) is returned</li>
+     * </ul>
+     * @param primaryKey the primary key of the synthetic record, which includes the primary keys of the constituents
+     * @param orphanBehavior what to do if any of the record's constituents is missing
+     * @return a future which completes to the synthesized record
+     */
+    @Nonnull
+    @API(API.Status.EXPERIMENTAL)
+    CompletableFuture<FDBSyntheticRecord> loadSyntheticRecord(@Nonnull Tuple primaryKey, IndexOrphanBehavior orphanBehavior);
 
     /**
      * Check if a record exists in the record store with the given primary key.

fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/provider/foundationdb/FDBTypedRecordStore.java

@@ -157,7 +157,7 @@ public CompletableFuture<Void> preloadRecordAsync(@Nonnull Tuple primaryKey) {
 
     @Nonnull
     @Override
-    public CompletableFuture<FDBSyntheticRecord> loadSyntheticRecord(@Nonnull final Tuple primaryKey) {
+    public CompletableFuture<FDBSyntheticRecord> loadSyntheticRecord(@Nonnull final Tuple primaryKey, final IndexOrphanBehavior orphanBehavior) {
         throw new RecordCoreException("api unsupported on typed store");
     }
 

fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/provider/foundationdb/indexes/ValueIndexScrubbingToolsDangling.java

@@ -57,6 +57,9 @@ public class ValueIndexScrubbingToolsDangling implements IndexScrubbingTools<Ind
 
     @Override
     public void presetCommonParams(final Index index, final boolean allowRepair, final boolean isSynthetic, final Collection<RecordType> typesIgnored) {
+        if (isSynthetic && allowRepair) {
+            throw new UnsupportedOperationException("Scrubbing synthetic records with repair is not supported");
+        }
         this.index = index;
         this.allowRepair = allowRepair;
         this.isSynthetic = isSynthetic;
@@ -93,7 +96,7 @@ public CompletableFuture<Issue> handleOneItem(final FDBRecordStore store, final
         }
 
         if (isSynthetic) {
-            return store.loadSyntheticRecord(indexEntry.getPrimaryKey()).thenApply(syntheticRecord -> {
+            return store.loadSyntheticRecord(indexEntry.getPrimaryKey(), IndexOrphanBehavior.RETURN).thenApply(syntheticRecord -> {
                 if (syntheticRecord.getConstituents().isEmpty()) {
                     // None of the constituents of this synthetic type are present, so it must be dangling
                     List<Tuple> primaryKeysForConflict = new ArrayList<>(indexEntry.getPrimaryKey().size() - 1);

fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/provider/foundationdb/indexes/ValueIndexScrubbingToolsMissing.java

@@ -66,6 +66,9 @@ public class ValueIndexScrubbingToolsMissing implements IndexScrubbingTools<FDBS
 
     @Override
     public void presetCommonParams(Index index, boolean allowRepair, boolean isSynthetic, Collection<RecordType> types) {
+        if (isSynthetic && allowRepair) {
+            throw new UnsupportedOperationException("Scrubbing synthetic records with repair is not supported");
+        }
         this.recordTypes = types;
         this.index = index;
         this.allowRepair = allowRepair;