feat: containing/containedIn/intersecting joiners #2022

triceo · 2026-01-16T09:57:32Z

Before

    Constraint speakerUnavailableTimeslot(ConstraintFactory factory) {
        return factory.forEach(Talk.class)
                .join(Speaker.class,
                        filtering((talk, speaker) -> talk.hasSpeaker(speaker)
                                && speaker.getUnavailableTimeslots().contains(talk.getTimeslot())))
                .penalize(...)
                .asConstraint(...);
    }

After (bigO order of magnitude more scalable)

    Constraint speakerUnavailableTimeslot(ConstraintFactory factory) {
        return factory.forEach(Talk.class)
                .join(Speaker.class,
                        containing(Talk::getSpeakers, speaker -> speaker),
                        containedIn(Talk::getTimeslot, Speaker::getUnavailableTimeslots))
                .penalize(...)
                .asConstraint(...);
    }

This is mostly a work of @ge0ffrey, I just rebased it and smoothened some rough edges.
Replaces #1999.

--- Co-authored-by: Geoffrey De Smet <gds.geoffrey.de.smet@gmail.com>

Copilot

Pull request overview

This pull request introduces three new collection-based joiners (containing, containedIn, and intersecting) to provide significant performance improvements through efficient indexing. The PR also includes several internal refactorings: renaming getElement() to element(), isEmpty() to isRemovable(), and KeyRetriever to KeyUnpacker.

Changes:

Added new joiner types: containing, containedIn, and intersecting with comprehensive API support across all joiner arities
Implemented specialized indexers (ContainingIndexer, ContainedInIndexer, IntersectingIndexer) for efficient query performance
Refactored internal APIs for better consistency and clarity

Reviewed changes

Copilot reviewed 44 out of 44 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
docs/src/modules/ROOT/pages/constraints-and-score/score-calculation.adoc	Documents new joiner types
core/src/main/java/ai/timefold/solver/core/api/score/stream/Joiners.java	Adds public API for containing, containedIn, and intersecting joiners across all arities
core/src/main/java/ai/timefold/solver/core/impl/bavet/common/joiner/JoinerType.java	Adds CONTAINING, CONTAINED_IN, INTERSECTING enum values with flip logic
core/src/main/java/ai/timefold/solver/core/impl/bavet/common/index/ContainingIndexer.java	New indexer implementation for containing joiner
core/src/main/java/ai/timefold/solver/core/impl/bavet/common/index/ContainedInIndexer.java	New indexer implementation for containedIn joiner
core/src/main/java/ai/timefold/solver/core/impl/bavet/common/index/IntersectingIndexer.java	New indexer implementation for intersecting joiner
core/src/main/java/ai/timefold/solver/core/impl/bavet/common/index/IndexerFactory.java	Updated to create new indexer types
core/src/main/java/ai/timefold/solver/core/impl/util/CompositeListEntry.java	New record for storing tuples in multiple downstream indexers
core/src/main/java/ai/timefold/solver/core/impl/util/ListEntry.java	Simplified interface (removed isRemoved, renamed getElement to element)
core/src/main/java/ai/timefold/solver/core/impl/bavet/common/index/KeyUnpacker.java	Renamed from KeyRetriever
Test files	Updated tests for new joiners and refactored naming

Comments suppressed due to low confidence (2)

core/src/main/java/ai/timefold/solver/core/impl/bavet/common/index/EqualIndexer.java:112

This method overrides Indexer.get; it is advisable to add an Override annotation.
core/src/main/java/ai/timefold/solver/core/impl/bavet/common/index/EqualIndexer.java:103
This method overrides Indexer.iterator; it is advisable to add an Override annotation.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

docs/src/modules/ROOT/pages/constraints-and-score/score-calculation.adoc

core/src/main/java/ai/timefold/solver/core/impl/bavet/common/joiner/JoinerType.java

core/src/main/java/ai/timefold/solver/core/impl/bavet/common/index/IntersectingIndexer.java

core/src/main/java/ai/timefold/solver/core/impl/util/CompositeListEntry.java

core/src/main/java/ai/timefold/solver/core/impl/util/ElementAwareLinkedList.java

TomCools

Docs look good to me

Christopher-Chianelli

I would have at least 1 test that go through the ScoreDirector that uses these Joiners. Additionally, I do not think these Joiners will work if the backing collection changes (such as a InverseShadowVariable) given the same size assertions in the code (IIRC, everything is updated only when calculateScore is called, and not at before/after variable change, so the indexer will encounter a different sized collection if a shadow variable changes).

Christopher-Chianelli · 2026-01-16T14:48:51Z

core/src/main/java/ai/timefold/solver/core/impl/bavet/common/index/ContainedInIndexer.java

+    /**
+     * See {@link EqualIndexer} for explanation of the parameters.
+     */
+    private final Map<Key_, Indexer<T>> downstreamIndexerMap = new HashMap<>(16, 0.5f);


These HashMap parameters were found after testing IIRC. Might be better to have them in CollectionUtils so they don't need to be copied and pasted everywhere.

Christopher-Chianelli · 2026-01-16T14:55:48Z

core/src/main/java/ai/timefold/solver/core/impl/bavet/common/index/ContainingIndexer.java

+        this.modifyKeyUnpacker = Objects.requireNonNull((KeyUnpacker<KeyCollection_>) keyUnpacker);
+        this.queryKeyUnpacker = Objects.requireNonNull(keyUnpacker);


These two fields always point to the same thing (but with different generics)?

Christopher-Chianelli · 2026-01-16T15:03:00Z

core/src/main/java/ai/timefold/solver/core/impl/bavet/common/index/ContainingIndexer.java

+            throw new IllegalStateException("""
+                    Impossible state: the tuple (%s) with composite key (%s) has a different number of children (%d) \
+                    than the index key collection size (%d)."""
+                    .formatted(entry, modifyCompositeKey, children.size(), indexKeyCollection.size()));


You might want to add to the Javadoc using variable collection properties such as PlanningListVariable or InverseShadowVariable is not allowed (since those will trigger this exception as they change size).

core/src/main/java/ai/timefold/solver/core/impl/bavet/common/index/IndexerFactory.java

Christopher-Chianelli · 2026-01-16T15:14:18Z

core/src/main/java/ai/timefold/solver/core/impl/bavet/common/index/ContainingAnyOfIndexer.java

+        this.modifyKeyUnpacker = Objects.requireNonNull((KeyUnpacker<KeyCollection_>) keyUnpacker);
+        this.queryKeyUnpacker = Objects.requireNonNull((KeyUnpacker<KeyCollection_>) keyUnpacker);


These two fields will always have the exact same value (with the exact same generics)

core/src/main/java/ai/timefold/solver/core/impl/bavet/common/index/IntersectingIndexer.java

triceo · 2026-01-17T06:36:04Z

Moving back to draft, as there are score corruptions.

Copilot

Pull request overview

Copilot reviewed 44 out of 44 changed files in this pull request and generated 4 comments.

Comments suppressed due to low confidence (2)

core/src/main/java/ai/timefold/solver/core/impl/bavet/common/index/EqualIndexer.java:112

This method overrides Indexer.get; it is advisable to add an Override annotation.
core/src/main/java/ai/timefold/solver/core/impl/bavet/common/index/EqualIndexer.java:103
This method overrides Indexer.iterator; it is advisable to add an Override annotation.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

core/src/main/java/ai/timefold/solver/core/impl/bavet/common/index/ContainingAnyOfIndexer.java

docs/src/modules/ROOT/pages/constraints-and-score/score-calculation.adoc

core/src/main/java/ai/timefold/solver/core/impl/bavet/common/index/KeyUnpacker.java

core/src/main/java/ai/timefold/solver/core/impl/bavet/common/index/IndexerFactory.java

triceo

After a conversation with Geoff, we'll do the following:

The joiners are removed from public API, therefore they can not be used.
They are also removed from the documentation. There is no public trace of them existing.
But they are being merged; Geoffrey will eventually get to finishing this work, but we want to avoid further merge conflicts until he does.

This entire piece of work will be re-reviewed as a whole, once the fixes for the score corruptions have been made. I'm leaving all the remaining comments here open, so that during the next round of review, we know what's left to resolve.

Copilot

Pull request overview

Copilot reviewed 45 out of 45 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (2)

core/src/main/java/ai/timefold/solver/core/impl/bavet/common/index/EqualIndexer.java:112

This method overrides Indexer.get; it is advisable to add an Override annotation.
core/src/main/java/ai/timefold/solver/core/impl/bavet/common/index/EqualIndexer.java:103
This method overrides Indexer.iterator; it is advisable to add an Override annotation.

sonarqubecloud · 2026-01-23T07:37:02Z

Quality Gate failed

Failed conditions
10.1% Duplication on New Code (required ≤ 5%)

See analysis details on SonarQube Cloud

triceo and others added 6 commits January 16, 2026 07:56

Geoff's changes

7a5d9df

--- Co-authored-by: Geoffrey De Smet <gds.geoffrey.de.smet@gmail.com>

Complete the rebase

c47ea0a

Clean up

c1bdf28

Javadocs and naming

d0b6cb6

Copilot

5421b08

Docs

1e34f6f

Copilot AI review requested due to automatic review settings January 16, 2026 09:57

triceo requested a review from TomCools as a code owner January 16, 2026 09:57

triceo temporarily deployed to internal January 16, 2026 09:57 — with GitHub Actions Inactive

triceo deployed to documentation (preview) January 16, 2026 09:57 — with GitHub Actions View deployment

Copilot started reviewing on behalf of triceo January 16, 2026 09:58 View session

triceo requested a review from Christopher-Chianelli January 16, 2026 10:03

triceo assigned ge0ffrey Jan 16, 2026

triceo added this to the v1.31.0 milestone Jan 16, 2026

triceo linked an issue Jan 16, 2026 that may be closed by this pull request

New joiners: contain(), containedIn(), intersect(), disjoint(), containAll() #8

Open

Copilot AI reviewed Jan 16, 2026

View reviewed changes

feat: containing/containedIn/intersecting joiners

d6f1215

triceo force-pushed the contains branch from 1b22592 to d6f1215 Compare January 16, 2026 10:50

triceo temporarily deployed to internal January 16, 2026 10:51 — with GitHub Actions Inactive

triceo deployed to documentation (preview) January 16, 2026 10:51 — with GitHub Actions View deployment

triceo removed this from the v1.31.0 milestone Jan 16, 2026

triceo unassigned ge0ffrey Jan 16, 2026

TomCools approved these changes Jan 16, 2026

View reviewed changes

Christopher-Chianelli requested changes Jan 16, 2026

View reviewed changes

Address some review comments

1f2daca

Copilot AI review requested due to automatic review settings January 17, 2026 06:35

triceo temporarily deployed to internal January 17, 2026 06:35 — with GitHub Actions Inactive

triceo deployed to documentation (preview) January 17, 2026 06:35 — with GitHub Actions View deployment

Copilot started reviewing on behalf of triceo January 17, 2026 06:36 View session

triceo marked this pull request as draft January 17, 2026 06:36

Copilot AI reviewed Jan 17, 2026

View reviewed changes

Mask the joiners out

bf9c5c8

triceo temporarily deployed to internal January 23, 2026 07:08 — with GitHub Actions Inactive

triceo deployed to documentation (preview) January 23, 2026 07:08 — with GitHub Actions View deployment

Review

91d3ad2

triceo temporarily deployed to internal January 23, 2026 07:18 — with GitHub Actions Inactive

triceo deployed to documentation (preview) January 23, 2026 07:18 — with GitHub Actions View deployment

triceo commented Jan 23, 2026

View reviewed changes

triceo marked this pull request as ready for review January 23, 2026 07:21

Copilot AI review requested due to automatic review settings January 23, 2026 07:21

Copilot started reviewing on behalf of triceo January 23, 2026 07:21 View session

triceo removed a link to an issue Jan 23, 2026

New joiners: contain(), containedIn(), intersect(), disjoint(), containAll() #8

Open

triceo linked an issue Jan 23, 2026 that may be closed by this pull request

Unit test for IndexerFactory: IndexerFactoryTest #1989

Closed

Copilot AI reviewed Jan 23, 2026

View reviewed changes

triceo merged commit f3fe406 into TimefoldAI:main Jan 23, 2026
37 of 40 checks passed

triceo deleted the contains branch January 23, 2026 07:39

		this.modifyKeyUnpacker = Objects.requireNonNull((KeyUnpacker<KeyCollection_>) keyUnpacker);
		this.queryKeyUnpacker = Objects.requireNonNull(keyUnpacker);

feat: containing/containedIn/intersecting joiners #2022

feat: containing/containedIn/intersecting joiners #2022

Conversation

triceo commented Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

TomCools left a comment

Choose a reason for hiding this comment

Uh oh!

Christopher-Chianelli left a comment

Choose a reason for hiding this comment

Uh oh!

Christopher-Chianelli Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

Christopher-Chianelli Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

Christopher-Chianelli Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Christopher-Chianelli Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

triceo commented Jan 17, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

triceo 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!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

sonarqubecloud bot commented Jan 23, 2026

Quality Gate failed

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

triceo commented Jan 16, 2026 •

edited

Loading

triceo left a comment •

edited

Loading