Expose filter_join_indices in Java

[bdice]

Description

Adds a Java/JNI binding for cudf::filter_join_indices, including Java join-kind selection and ownership-preserving conversion between GatherMap inputs and outputs. This lets Java callers compose reusable HashJoin equality gather maps with AST predicate filtering for inner, left, and full joins.

The API documents matching-kind input maps, row correspondence, sentinel/null/empty behavior, and independent output ownership. Java tests cover reusable hash joins, duplicate and nullable candidates, empty inputs, and input/output lifetimes.

Closes #24096.

Native fix dependency

The libcudf FULL filtering bug is tracked in #24145 and fixed separately by #24146, targeting release/26.10. This PR contains only Java/JNI changes. Its FULL regression tests require that native fix to be present on main before this PR merges.

Validation

Java/JNI built successfully with the native fix applied in a CUDA 13.3 conda devcontainer. All 13 filter tests passed; the full TableTest class had 351 passes and 2 existing Arrow-related skips. These results validate the Java changes with the native dependency; the standalone native fix is no longer included in this PR.

Checklist

• I am familiar with the Contributing Guidelines.
• New or existing tests cover these changes.
• The documentation is up to date with these changes.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 3d5e1cf6-7751-4273-bf8b-7de6cb8cf29b

📥 Commits

Reviewing files that changed from the base of the PR and between e06741d and a067943.

📒 Files selected for processing (10)

• cpp/include/cudf/join/join.hpp
• cpp/src/join/filter_join_indices/filter_join_indices.cu
• cpp/src/join/filter_join_indices/filter_join_indices_jit.cu
• cpp/src/join/filter_join_indices/filter_join_indices_output_size_kernel.cuh
• cpp/src/join/filter_join_indices/full_join.hpp
• cpp/tests/join/mixed_join_tests.cu
• cpp/tests/streams/join_test.cpp
• java/src/main/java/ai/rapids/cudf/JoinKind.java
• java/src/main/java/ai/rapids/cudf/Table.java
• java/src/test/java/ai/rapids/cudf/TableTest.java

🚧 Files skipped from review as they are similar to previous changes (2)

• java/src/main/java/ai/rapids/cudf/JoinKind.java
• java/src/main/java/ai/rapids/cudf/Table.java

Included review availability: Your plan provides up to 12 included reviews per hour; 10 remain after this review.

---

📝 Summary

Summary by CodeRabbit

• New Features

  • Added support for filtering join results with compiled conditional expressions.
  • Added inner, left, and full join semantics for filtered join mappings.
  • Added an API that returns filtered left and right mappings for further table processing.
  • Full joins now retain passing pairs and include unmatched rows from both sides.
  • Added validation for compatible mapping sizes and required inputs.

• Tests

  • Added coverage for duplicates, null values, empty inputs, unmatched rows, reused mappings, many-to-many matches, and conditional full joins.

Walkthrough

Adds Java and JNI support for filtering join gather maps with compiled conditions. Reworks native FULL_JOIN filtering to preserve passing pairs and emit unmatched rows. Adds coverage for reusable maps, nulls, duplicates, empty inputs, ownership, output sizing, and JIT paths.

Changes

Filter join gather maps

Layer / File(s)	Summary
Java API contract and JNI entry point java/src/main/java/ai/rapids/cudf/JoinKind.java, java/src/main/java/ai/rapids/cudf/Table.java, java/src/main/native/src/TableJni.cpp	Adds INNER, LEFT, and FULL join modes. Adds the Java method and JNI entry point. Validates map lengths, pointers, handles, and native inputs before calling cudf::filter_join_indices.
FULL_JOIN native filtering and output sizing cpp/src/join/filter_join_indices/*	Adds filter_full_join_indices. It records matched rows, preserves passing pairs, and appends unmatched rows. FULL_JOIN output sizing now tracks left and right row contributions for standard and JIT filtering.
Join filtering contract and regression coverage cpp/include/cudf/join/join.hpp, cpp/tests/join/mixed_join_tests.cu, cpp/tests/streams/join_test.cpp, java/src/test/java/ai/rapids/cudf/TableTest.java	Documents revised FULL_JOIN behavior. Tests cover conditional filtering, JIT and AST paths, nullable values, duplicates, empty inputs, post-filters, output sizing, input-map ownership, and mismatched maps.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~60 minutes

Change: Feature

Suggested reviewers: mythrocks

Merge Risk: ⚪ Minimal · up to c230c

The Java/JNI contract and full-join behavior have broad targeted coverage, with no concrete issue requiring correction before merge.

🚥 Pre-merge checks | ✅ 6 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 6.45% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 31 functions across 9 files. (2 skipped: 1…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (6 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The description references issue #24096, and the stated objectives align with exposing filter_join_indices through Java/JNI.
Out of Scope Changes check	✅ Passed	The full-join implementation fixes, documentation, and tests support the stated Java/JNI binding objectives and full-join behavior.
Linked Issues check	✅ Passed	The changes satisfy the coding requirements in #24096. Java adds JoinKind and Table.filterJoinGatherMaps with inner, left, and full support. The JNI binding passes the two gather maps, predicate t…
Out of Scope Changes check	✅ Passed	The changes remain connected to #24096. The full-join native correction, API documentation, and regression tests support the exposed filter operation and its advertised full-join behavior. The changes…
Title check	✅ Passed	The title clearly identifies the main change: exposing filter_join_indices through Java.
Description check	✅ Passed	The description directly explains the Java/JNI binding, supported join kinds, ownership behavior, tests, documentation, and native dependency.

Full details: Docstring Coverage

Explanation

Docstring coverage is 6.45% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 31 functions across 9 files. (2 skipped: 1 unsupported, 1 too large.)

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.