[1/4] Multi-hop query: Mutation + multi-get query by zipdoki · Pull Request #226 · kakao/actionbase

zipdoki · 2026-03-26T06:18:26Z

Part of #214

Summary

Introduces EdgeCache, a wide row structure that stores multiple edges per source in a single HBase row. Adds mutation support (CREATE/DELETE/UPDATE) and a seek API for range queries via ColumnRangeFilter.

Data Model

[EdgeCache - Wide Row]
Row: hash | directed source | tableCode | EDGE_CACHE | direction | cacheCode
Qualifier: cacheValues (indexField + order) | directed target
Value: version + properties

Unlike EdgeIndex (narrow row: one row per edge), EdgeCache stores multiple edges as qualifiers within a single row. Supports range queries via ColumnRangeFilter.

Test Plan

Test	Coverage
`EdgeCacheRecordMapperTest`	Cache record encode/decode round-trip (key, qualifier, value)
`EdgeMutationBuilderTest`	Cache record generation in mutation pipeline (CREATE/DELETE/UPDATE)
`V2BackedTableBindingTest`	EdgeCache Put/Delete HBase mutation conversion
`EdgeCacheQueryE2ETest`	Seek API end-to-end: OUT/IN direction, cursor-based pagination, MultiEdge support

Run: ./gradlew test

Introduces a wide row structure that stores multiple edges per source in a single HBase row, enabling efficient multi-get queries via ColumnRangeFilter. - EdgeCacheRecord with encoder/decoder - Mutation pipeline support (CREATE/DELETE/UPDATE) - Seek API with cursor-based pagination

zipdoki · 2026-03-26T06:18:54Z

engine/src/main/kotlin/com/kakao/actionbase/v2/engine/v3/V3QueryService.kt

+            offset?.let {
+                val decoded = CryptoUtils.decodeAndDecryptUrlSafe(it)
+                decoded + 0x00.toByte()
+            }


@em3s
Used qualifier + 0x00 to express "start after" instead of ColumnRangeFilter's minColumnInclusive=false.

// current: byte-append trick val offsetNext = decoded + 0x00.toByte() ColumnRangeFilter(min, minColumnInclusive = true, max, maxColumnInclusive = false) // alternative: use native exclusive flag val offsetNext = decoded ColumnRangeFilter(min, minColumnInclusive = false, max, maxColumnInclusive = false)

The byte-append keeps hbaseGetWideRow simpler (no inclusive params), but the native flag avoids byte-level assumptions. Open to either approach.

+1 for exclusive flag.

@em3s
Done. Switched to native exclusive flag and removed the byte-append trick.

zipdoki · 2026-03-26T06:19:28Z

engine/src/main/kotlin/com/kakao/actionbase/v2/engine/v3/V3QueryService.kt

+                val nextOffset =
+                    if (hasNext) {
+                        results.lastOrNull()?.qualifier?.let {
+                            CryptoUtils.encryptAndEncodeUrlSafe(it)


@em3s
Reusing v2's CryptoUtils for offset encoding, same as the existing scan path. This will need updating once #221 lands.

OK, use CryptoUtils and will address in a separate task.

zipdoki · 2026-03-26T06:24:14Z

@em3s
Aware this is a large diff — sorry about that. Keeping it as one PR for now to make the overall design easier to review. Plan to split into two when merging:

Core + Mutation — data model, codec, mutation pipeline, metadata
Seek API — query endpoint, controller, E2E tests

Happy to split sooner if preferred.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

em3s · 2026-03-27T06:05:06Z

engine/src/main/kotlin/com/kakao/actionbase/v2/engine/v3/V3QueryService.kt

+                val nextOffset =
+                    if (hasNext) {
+                        results.lastOrNull()?.qualifier?.let {
+                            CryptoUtils.encryptAndEncodeUrlSafe(it)


OK, use CryptoUtils and will address in a separate task.

em3s · 2026-03-27T06:19:34Z

core/src/main/kotlin/com/kakao/actionbase/core/edge/mapper/EdgeCacheRecordMapper.kt

+
+            while (buffer.hasRemaining()) {
+                val propertyHashKey: Int = buffer.getValue()
+                val propertyValue: Any? = buffer.getValueOrNull()


decodeValue in EdgeIndexRecordMapper uses buffer.getValue() — why the different approach here?

@em3s
Nullable properties end up as null in HBase (specialStateValueToNull() converts __UNSET__ → null before write).

e.g. schema has receivedFrom (nullable=true), mutation omits it → stored as null in EdgeIndex value.

V2 decoder handles this fine (ValueUtils.deserialize() returns null), but V3 EdgeIndexRecordMapper.decodeValue() uses getValue() which throws. Should use getValueOrNull() like EdgeCacheRecordMapper.

em3s · 2026-03-27T06:20:51Z

core/src/test/kotlin/com/kakao/actionbase/core/edge/mapper/EdgeCacheRecordMapperTest.kt

+import org.junit.jupiter.api.Test
+
+/**
+ * EdgeCache (Wide Row) HBase layout:


just EdgeCache (Wide Row) layout:

@em3s
Done.

em3s · 2026-03-27T06:28:24Z

@zipdoki

Large changes OK. This PR is not production-facing, so I suggest we merge first and iterate.
Just resolve the above reviews please.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Null properties are stored as "__UNSET__", not raw null. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

This reverts commit 3c8edce.

Replace qualifier + 0x00 byte trick with ColumnRangeFilter's minColumnInclusive=false for "start after" semantics. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

zipdoki · 2026-04-01T07:00:04Z

@em3s
Thanks for the review! I've addressed the requested changes in the latest commits. Please take another look when you have a chance.

resolved.

em3s

@zipdoki

LGTM 👍 — let's merge and iterate.

zipdoki requested a review from em3s March 26, 2026 06:18

dosubot bot added size:XXL This PR changes 1000+ lines, ignoring generated files. enhancement New feature or request labels Mar 26, 2026

zipdoki commented Mar 26, 2026

View reviewed changes

zipdoki mentioned this pull request Mar 26, 2026

Multi-hop query support #214

Open

5 tasks

merge: resolve conflict with main branch

6dd969f

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

em3s previously requested changes Mar 27, 2026

View reviewed changes

zipdoki and others added 5 commits March 30, 2026 13:55

docs: remove HBase reference from EdgeCacheRecordMapper test comment

dac1f8a

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

revert: restore getValue() in EdgeCacheRecordMapper.decodeValue

3c8edce

Null properties are stored as "__UNSET__", not raw null. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docs: add 'layout' back to EdgeCache test comment

cd3756f

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Revert "revert: restore getValue() in EdgeCacheRecordMapper.decodeValue"

5f4751f

This reverts commit 3c8edce.

refactor: use native exclusive flag for offset pagination

b0e3a70

Replace qualifier + 0x00 byte trick with ColumnRangeFilter's minColumnInclusive=false for "start after" semantics. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

zipdoki self-assigned this Apr 1, 2026

em3s requested review from em3s and removed request for em3s April 1, 2026 07:02

em3s approved these changes Apr 1, 2026

View reviewed changes

dosubot bot added the lgtm This PR has been approved by a maintainer label Apr 1, 2026

em3s merged commit 5dcdb78 into main Apr 1, 2026
7 checks passed

Conversation

zipdoki commented Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Data Model

Test Plan

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!

zipdoki commented Mar 26, 2026

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!

em3s commented Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

zipdoki commented Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

em3s left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

zipdoki commented Mar 26, 2026 •

edited

Loading

em3s commented Mar 27, 2026 •

edited

Loading

zipdoki commented Apr 1, 2026 •

edited

Loading

em3s left a comment •

edited

Loading