Add new KeySpacePath.exportAllData #3566

ScottDugas · 2025-09-03T19:25:32Z

This introduces a new KeySpacePath.exportAllData to export all the data stored in the path. This can eventually be used to import into another cluster, or back into the same cluster, after clearing.

Other than the path information, the data exported is raw bytes, with no transformation or indicated semantics.

Resolves: 3572

…hin the path

…Data overrides

… pass

This will be returned by export

Most of the time this will be used with remainders, so make most of the tests cover that

ScottDugas · 2025-09-05T14:20:37Z

...t/java/com/apple/foundationdb/record/provider/foundationdb/keyspace/EnvironmentKeySpace.java

+import javax.annotation.Nonnull;
+import java.util.UUID;
+
+/**


In case you're reviewing this top-to-bottom, this class was extracted from KeySpaceDirectoryTest, but setupSampleData was added.

alecgrieser · 2025-09-09T11:11:36Z

...main/java/com/apple/foundationdb/record/provider/foundationdb/keyspace/KeySpacePathImpl.java

+                                                          @Nullable byte[] continuation,
+                                                          @Nonnull ScanProperties scanProperties) {
+        return new LazyCursor<>(toTupleAsync(context)
+                .thenApply(tuple -> KeyValueCursor.Builder.withSubspace(new Subspace(tuple))


Just to try and head off some potential problems: in #3397, there's a modification being made to the KeyValueCursor continuation to wrap it in a protobuf. This would allow us to avoid returning an empty ByteString as the continuation in case there is a single key range, which may be something that a KeySpacePath could run into. (It would require that the first key in the keyspace path is set, I think.)

There's sort of an open question as to how we migrate all of the uses over from the old format to the new format. It would be nice if we could set the serialization mode on this one to the new format so that we don't have to worry about migrating it later, I think. Though that would introduce a dependency on #3397 being merged first.

That's a good point.
I changed exportAllData on the interface to be EXPERIMENTAL, and added a note that we expect the continuation change without preserving backwards compatibility when that merges. If the rest of the pieces are in place such that this is useful before #3397 gets merged, we can potentially update the javadoc, and make this be backwards compatible.

alecgrieser · 2025-09-09T11:34:05Z

...in/java/com/apple/foundationdb/record/provider/foundationdb/keyspace/DataInKeySpacePath.java

+        this.rawKeyValue = rawKeyValue;
+
+        // Convert the raw key to a Tuple and resolve it starting from the provided path
+        Tuple keyTuple = Tuple.fromBytes(rawKeyValue.getKey());


Do we need to be concerned with keys that are not Tuple parseable? I believe all of the keys that we currently generate are Tuple parseable, though we could adjust that in the future

KeySpacePathImpl always produces tuples, and AFAIK every key we have ever used has been in tuples. I feel like committing to that at this point, is worthwhile. If we find a strong reason to put non-tuple data in a key, we'll have to cross that bridge when we get to it.

alecgrieser · 2025-09-09T11:38:56Z

...in/java/com/apple/foundationdb/record/provider/foundationdb/keyspace/DataInKeySpacePath.java

+        this.resolvedPath = path.toResolvedPathAsync(context).thenCompose(resolvedPath -> {
+            // Now use the resolved path to find the child for the key
+            // We need to figure out how much of the key corresponds to the resolved path
+            Tuple pathTuple = resolvedPath.toTuple();


Should this validate that pathTuple is a prefix of keyTuple? Strictly speaking, I don't think the check is necessary, but it could be a sensible thing to validate

Yeah, I think that's a good double check.

Note: I took advantage of TupleHelpers.isPrefix, which apparently didn't have any unit tests, but I'm adding them in a followup PR. https://github.com/FoundationDB/fdb-record-layer/pull/3578/files#diff-c7f3ee5c693bba884071e40ab98f13c12a86350a819f71f1c6a60eb7b750623c
I'm not sure if it's worth bringing into this PR.

alecgrieser · 2025-09-09T11:42:28Z

...in/java/com/apple/foundationdb/record/provider/foundationdb/keyspace/DataInKeySpacePath.java

+        Tuple keyTuple = Tuple.fromBytes(rawKeyValue.getKey());
+
+        // First resolve the provided path to get its resolved form
+        this.resolvedPath = path.toResolvedPathAsync(context).thenCompose(resolvedPath -> {


It almost seems like the method provided should be a method on the KeySpacePath. I was sort of surprised that we didn't already have it. I can see how we'd have to be clear in the name that we're starting with the full key rather than just the suffix. I suppose we could structure this here to go the other way: we resolve the KeySpacePath first, use it to get a raw byte prefix, and then resolve the Tuple suffix using findChildForKey

Yeah, I was also kind of surprised. I was a bit fixated on getting this working, that I didn't pause to think that I should add it there. I'll move most of this there.

alecgrieser · 2025-09-09T13:19:00Z

...ava/com/apple/foundationdb/record/provider/foundationdb/keyspace/DataInKeySpacePathTest.java

+            // Verify accessor methods
+            KeyValue retrievedKeyValue = dataInPath.getRawKeyValue();
+            assertNotNull(retrievedKeyValue);
+            assertEquals(originalKeyValue.getKey(), retrievedKeyValue.getKey());


I believe that for arrays, the assertion here ends up asserting that the two arrays are pointer equal. Which I guess makes sense given that the original KeyValue is just being wrapped. That may be what you inteded to assert here, but I just wanted to make sure that that's what was going on here.

True, updated, but I'm probably going to make more substantial changes to the api here, namely hiding the key entirely.

alecgrieser · 2025-09-09T13:30:01Z

...ava/com/apple/foundationdb/record/provider/foundationdb/keyspace/DataInKeySpacePathTest.java

+            KeySpacePath companyPath = root.path("company");
+            DataInKeySpacePath dataInPath = new DataInKeySpacePath(companyPath, keyValue, context);


It might be nice to have an assertion somewhere that states that you can choose any path along the way, and all of those will return the same DataInKeySpacePath

Yeah, that was the intent of the parameter. Fixed.

alecgrieser · 2025-09-09T13:39:46Z

...in/java/com/apple/foundationdb/record/provider/foundationdb/keyspace/DataInKeySpacePath.java

+/**
+ * Class representing a {@link KeyValue} pair within in {@link KeySpacePath}.
+ */
+public class DataInKeySpacePath {


Should this implement equals and hashCode?

Yeah, probably, but I'm not entirely sure how to do that with the CompletableFuture for the resolved path.
It can either fall through and say it's equal if the original path, and raw value or equal, or, alternately, I can change it so that the constructor takes the resolved path.

I started doing this path, an discovered that ResolvedKeySpacePath.equals is broken, and I've started working on a fix for that. Its a fair amount of new tests, and a couple other equals/hashcode implementations, so I'm going to pull that out into a separate PR, and come back to this once it is fixed.

Issue: #3594

alecgrieser · 2025-09-09T13:40:47Z

...com/apple/foundationdb/record/provider/foundationdb/keyspace/KeySpacePathDataExportTest.java

+     * @param context the context in which to export
+     * @return a list of the raw {@code KeyValue}s being exported
+     */
+    private static List<KeyValue> exportAllData(final KeySpacePath pathToExport, final FDBRecordContext context) {


Any reason this returns KeyValues instead of DataInKeySpacePaths?

alecgrieser · 2025-09-09T13:43:22Z

...com/apple/foundationdb/record/provider/foundationdb/keyspace/KeySpacePathDataExportTest.java

+        try (FDBRecordContext context = database.openContext()) {
+            KeySpacePath continuationPath = root.path("continuation");
+
+            final ScanProperties scanProperties = ScanProperties.FORWARD_SCAN.with(props -> props.setReturnedRowLimit(limit));


Should we also test reverse scans like this?

alecgrieser · 2025-09-09T13:48:06Z

...com/apple/foundationdb/record/provider/foundationdb/keyspace/KeySpacePathDataExportTest.java

+
+    @ParameterizedTest
+    @ValueSource(ints = {1, 2, 3, 30})
+    void exportAllDataWithContinuation(int limit) {


Another case that is relevant to continuations: scanning a single record key space path. Something like:

Resolving a path to a tuple then

Setting that specific key to some value and

Validating that we get that value back and that the continuation that comes back is sensible (not null and ideally not empty)

I'm not actually sure we'd get that key back (that is, whether the scan is over a strict subspace or not). And if it does return a continuation, I actually think it would return an empty continuation for the first element (because of #3206, see #3397), but it would be nice to know.

ScottDugas

I went through a bunch of the comments, and responded. I've made a bunch of the changes locally, but when I got to implementing DataInKeySpacePath.equals/hashCode, I discovered that ResolvedKeySpacePath does not implement those correctly. I'm going to pause, the work on this PR, to resolve that. I'm submitting my commits in the meantime, for visibility.

ScottDugas · 2025-09-09T20:37:00Z

...main/java/com/apple/foundationdb/record/provider/foundationdb/keyspace/KeySpacePathImpl.java

+                                                          @Nullable byte[] continuation,
+                                                          @Nonnull ScanProperties scanProperties) {
+        return new LazyCursor<>(toTupleAsync(context)
+                .thenApply(tuple -> KeyValueCursor.Builder.withSubspace(new Subspace(tuple))


That's a good point.
I changed exportAllData on the interface to be EXPERIMENTAL, and added a note that we expect the continuation change without preserving backwards compatibility when that merges. If the rest of the pieces are in place such that this is useful before #3397 gets merged, we can potentially update the javadoc, and make this be backwards compatible.

ScottDugas · 2025-09-09T20:38:17Z

...in/java/com/apple/foundationdb/record/provider/foundationdb/keyspace/DataInKeySpacePath.java

+/**
+ * Class representing a {@link KeyValue} pair within in {@link KeySpacePath}.
+ */
+public class DataInKeySpacePath {


Yeah, probably, but I'm not entirely sure how to do that with the CompletableFuture for the resolved path.
It can either fall through and say it's equal if the original path, and raw value or equal, or, alternately, I can change it so that the constructor takes the resolved path.

ScottDugas · 2025-09-09T20:42:02Z

...in/java/com/apple/foundationdb/record/provider/foundationdb/keyspace/DataInKeySpacePath.java

+        this.rawKeyValue = rawKeyValue;
+
+        // Convert the raw key to a Tuple and resolve it starting from the provided path
+        Tuple keyTuple = Tuple.fromBytes(rawKeyValue.getKey());


KeySpacePathImpl always produces tuples, and AFAIK every key we have ever used has been in tuples. I feel like committing to that at this point, is worthwhile. If we find a strong reason to put non-tuple data in a key, we'll have to cross that bridge when we get to it.

ScottDugas · 2025-09-09T20:44:05Z

...src/main/java/com/apple/foundationdb/record/provider/foundationdb/keyspace/KeySpacePath.java

+     */
+    @API(API.Status.UNSTABLE)
+    @Nonnull
+    RecordCursor<DataInKeySpacePath> exportAllData(@Nonnull FDBRecordContext context,


I realized that this is an interface, and while I don't think we intended anyone to extend it, I should probably put a default implementation in.

ScottDugas · 2025-09-09T20:45:43Z

...in/java/com/apple/foundationdb/record/provider/foundationdb/keyspace/DataInKeySpacePath.java

+        Tuple keyTuple = Tuple.fromBytes(rawKeyValue.getKey());
+
+        // First resolve the provided path to get its resolved form
+        this.resolvedPath = path.toResolvedPathAsync(context).thenCompose(resolvedPath -> {


Yeah, I was also kind of surprised. I was a bit fixated on getting this working, that I didn't pause to think that I should add it there. I'll move most of this there.

ScottDugas · 2025-09-10T15:53:30Z

...ava/com/apple/foundationdb/record/provider/foundationdb/keyspace/DataInKeySpacePathTest.java

+            // Verify accessor methods
+            KeyValue retrievedKeyValue = dataInPath.getRawKeyValue();
+            assertNotNull(retrievedKeyValue);
+            assertEquals(originalKeyValue.getKey(), retrievedKeyValue.getKey());


True, updated, but I'm probably going to make more substantial changes to the api here, namely hiding the key entirely.

ScottDugas · 2025-09-10T15:59:43Z

...ava/com/apple/foundationdb/record/provider/foundationdb/keyspace/DataInKeySpacePathTest.java

+            assertEquals("blob_id", resolved.getDirectoryName());
+            byte[] resolvedBytes = (byte[]) resolved.getResolvedValue();
+            assertArrayEquals(blobId, resolvedBytes);


Yeah, but I updated assertNameAndValue to check for byte[] and use assertArrayEquals appropriately.

ScottDugas · 2025-09-10T16:00:33Z

...ava/com/apple/foundationdb/record/provider/foundationdb/keyspace/DataInKeySpacePathTest.java

+    @ValueSource(ints = {0, 1, 2, 3, 4, 5})
+    void resolution() {


It is not, but it was supposed to be used to resolve from a path deeper than the root. Updated the test to actually use it.

ScottDugas · 2025-09-10T16:00:45Z

...ava/com/apple/foundationdb/record/provider/foundationdb/keyspace/DataInKeySpacePathTest.java

+            KeySpacePath companyPath = root.path("company");
+            DataInKeySpacePath dataInPath = new DataInKeySpacePath(companyPath, keyValue, context);


Yeah, that was the intent of the parameter. Fixed.

ScottDugas · 2025-09-12T14:17:14Z

...in/java/com/apple/foundationdb/record/provider/foundationdb/keyspace/DataInKeySpacePath.java

+/**
+ * Class representing a {@link KeyValue} pair within in {@link KeySpacePath}.
+ */
+public class DataInKeySpacePath {


I started doing this path, an discovered that ResolvedKeySpacePath.equals is broken, and I've started working on a fix for that. Its a fair amount of new tests, and a couple other equals/hashcode implementations, so I'm going to pull that out into a separate PR, and come back to this once it is fixed.

Issue: #3594

ScottDugas added 10 commits August 29, 2025 13:13

Add tests for a KeySpacePath export method to export all the data wit…

8f4922e

…hin the path

Add continuation tests

f79e912

Fix checkstyle

80cbad2

Reduce duplication in KeySpacePathDataExportTest and remove exportAll…

1959c73

…Data overrides

Implement KeySpacePath.exportAllData, and update the tests to make it…

9f7c8f2

… pass

Remove usage of asyncToSync in exportAllData

5cadd88

Add initial implementation of a class for resolved path & value

6b975d7

This will be returned by export

Validate remainder in more places

ed9702b

Most of the time this will be used with remainders, so make most of the tests cover that

Cleanup some of the assertions

0820b97

Change exportAllData to return DataInKeySpacePath instead of raw data

0750e00

ScottDugas added the enhancement New feature or request label Sep 3, 2025

ScottDugas added 7 commits September 4, 2025 10:10

Move EnvironmentKeySpace out into its own file, move wrappers into it

a6572f1

Add tests of KeySPacePathWrapper.exportAllData

439ea52

Cleanup style of test

d9b92ab

Fix bug when exporting at the leaf node

cc2420e

Reduce repetitive tests, and repetitive code for assertions

e2da4ea

Dleete some more redundant tests

5a24630

Some minor test cleanup

f1e436a

ScottDugas changed the title ~~Keyspacepath export~~ Add new KeySpacePath.exportAllData Sep 5, 2025

ScottDugas commented Sep 8, 2025

View reviewed changes

ScottDugas marked this pull request as ready for review September 8, 2025 16:56

ScottDugas requested review from alecgrieser and ohadzeliger September 8, 2025 16:56

alecgrieser requested changes Sep 9, 2025

View reviewed changes

ScottDugas commented Sep 12, 2025

View reviewed changes

		KeySpacePath companyPath = root.path("company");
		DataInKeySpacePath dataInPath = new DataInKeySpacePath(companyPath, keyValue, context);

Add new KeySpacePath.exportAllData #3566

Are you sure you want to change the base?

Add new KeySpacePath.exportAllData #3566

Uh oh!

Conversation

ScottDugas commented Sep 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ScottDugas left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ScottDugas commented Sep 3, 2025 •

edited

Loading