Batch API

RelationalBatch is the tensor contract every backend consumes. The Relational Batches page documents each field, shape, and convention with examples.

RelationalBatch

class relational_transformers.RelationalBatch(node_idxs, f2p_nbr_idxs, col_name_idxs, table_name_idxs, is_padding, sem_types, is_targets, number_values, datetime_values, boolean_values, text_values, col_name_values)

A padded batch of relational cells.

This is the shared boundary used by PyTorch, Triton, ONNX, and RelativeDB. Integer tensors describe topology; value tensors contain already encoded model inputs. Boolean masks use True for padding/targets.

Parameters:

• node_idxs (Tensor)

• f2p_nbr_idxs (Tensor)

• col_name_idxs (Tensor)

• table_name_idxs (Tensor)

• is_padding (Tensor)

• sem_types (Tensor)

• is_targets (Tensor)

• number_values (Tensor)

• datetime_values (Tensor)

• boolean_values (Tensor)

• text_values (Tensor)

• col_name_values (Tensor)

validate()

Check shapes, semantic type range, target placement, and finiteness.

Runs automatically on construction. Raises ValueError with the offending field name on the first violation.

Return type:

RelationalBatch

to(device, dtype=None)

Return a copy on device, optionally casting floating-point channels.

Parameters:

• device (str | device)

• dtype (dtype | None)

Return type:

RelationalBatch

as_dict()

Return the canonical fields as a name-to-tensor dictionary.

The keys match BATCH_FIELDS and round-trip through from_mapping().

Return type:

dict[str, Tensor]

numpy()

Return every canonical field as a CPU numpy array.

Return type:

dict[str, ndarray]

classmethod from_mapping(values)

Build a batch from a dictionary of arrays or tensors.

Accepts numpy arrays, torch tensors, or nested lists for every field. Integer index fields are cast to int64, is_padding and is_targets to bool (uint8 inputs work), and value channels to floating point. Short RelativeDB aliases such as f2p, col_idxs, table_idxs, is_target, number_v, and text_v normalize to their canonical names. Raises ValueError when a canonical field is missing.

Parameters:

values (Mapping[str, Any])

Return type:

RelationalBatch

classmethod from_text_cells(cells, *, target, node_idxs=None, parents=None, table_idxs=None)

Build one batch row from [column_embedding, value_embedding] cells.

cells has shape [S, 2*d_text]. This convenience path is useful for all-text examples; typed production callers should construct the full batch so scalar and datetime channels retain their semantics.

Parameters:

• cells (ndarray | Tensor)

• target (int | Sequence[int])

• node_idxs (Sequence[int] | None)

• parents (Mapping[int, Sequence[int]] | None)

• table_idxs (Sequence[int] | None)

Return type:

RelationalBatch

ablate(cells)

Return a new batch with the same cell positions padded out.

Positions remain stable, so node and parent indices require no remap. Target cells may not be ablated.

Parameters:

cells (Sequence[int])

Return type:

RelationalBatch