Deterministic operators

Matching

Select a deterministic one-to-one matching between two Spaces.

Matching selects a one-to-one set of eligible X-to-Y relationships.

Worked example

Matching(
    name="match-invoices-to-payments",
    input_spaces=("invoices", "payments"),
    output_space="reconciled-payments",
    primary_key="reference",
    evidence=("amount",),
    fn=lambda invoice, payment: (
        invoice["reference"] == payment["reference"]
        and invoice["amount"] == payment["amount"]
    ),
    perfect=False,
)

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
`perfect`	operator default	Require a complete matching when the available data permits the declared side.

Output

A one-to-one set of matched X and Y values.

Design guidance

Use Join when either side may legitimately have several matches. Set perfect only when unmatched values should make the requested result infeasible.