Deterministic operators

Join

Join two Spaces using a deterministic predicate.

Join recovers many-to-many relationships between the first input Space and the remaining input Space or Spaces.

Worked example

Join(
    name="join-clicks-to-news",
    input_spaces=("clicks", "news"),
    output_space="resolved-clicks",
    primary_key="news_id",
    fn=lambda click, article: click["news_id"] == article["news_id"],
    max_matches_per_x=1,
)

Callable contract

fn(x_row, y_row) -> bool.

Rows available to the callable

Each row argument contains the declared primary-key fields and the declared evidence fields available for that input role. If the callable reads a field that is not part of the primary key, declare it as evidence.

One primary-key shape identifies values independently on both sides, so every primary-key column must exist in every input Space. When the two roles use different names for their central values, first use deterministic transforms to copy them to a common alias.

Parameter	Default	Meaning
`input_spaces`	required	The Space or Spaces read by the task.
`output_space`	required	The Space that receives the task output.
`name`	required	A stable task name used in sessions, reviews, and metrics.
`primary_key`	id	The field, or tuple of fields, that identifies one task input. Duplicate primary-key values are evaluated once.
`evidence`	none	Optional fields made available to the callable in addition to the primary key.
`fn`	required	A deterministic callable that completely defines the operation's decision. Use an importable named function from your package, or PythonFunction(name=..., source=...) when authoring through the hosted API or node editor. Pairwise endomorphic functions may declare an exact indexed candidate_gate.
`function_parameters`	registered defaults	Typed values bound to parameters declared by the registered function. Finite candidate sets let reviewed evidence support parameter advice.

Parameter	Default	Meaning
`max_matches_per_x`	unlimited	Validate that each X has at most this many authoritative Y matches.
`max_matches_per_y`	unlimited	Validate that each Y has at most this many authoritative X matches.
`exact_x`	false	Require every X to have exactly its declared maximum.
`exact_y`	false	Require every Y to have exactly its declared maximum.

Output

One row for each X value. It retains the X fields and adds `matches`, a list whose entries are the complete matched Y rows.

Design guidance

Use Join for key equality, range overlap, and other exact relationships. Use SemJoin only when deciding the relationship requires semantic interpretation. Deterministic degree fields validate the complete predicate relation: a violation fails the task; Join never silently chooses among true matches.