# JoinTwo reference

JoinTwo is a template that joins two tables. As the tables are modified, the updates propagate through the join. The join itself keeps no state (other than the state of its input tables), so if it needs to be kept, it has to be saved into another table. There is no requirement of a primary key on either the input tables nor the join result. However if the result is saved into a table, that table would have to have a primary key, so by extension the join would have to produce the result with a primary key, or the table contents will become incorrect. The JoinTwo is internally implemented as a pair of LookupJoins.

    $joiner = Triceps::JoinTwo->new(optionName => optionValue, ...);

Creates the JoinTwo object. Confesses on any errors. The options are:

    name => $name

  Name of this object. Will be used to create the names of internal objects.

    leftTable => $table

  Table object to join, for the left side. Both tables must be of the same unit.

    rightTable => $table

  Table object to join, for the right side. Both tables must be of the same unit.

    leftFromLabel => $label

  The label from which to receive the rows on the left side. Optional. Default: the Output label of leftTable unless it's a self-join; for a self-join the Pre label of leftTable.

  Can be used to introduce a label that would filter out some of the input. THIS IS DANGEROUS! To preserve consistency, always filter by the key field(s) only, and apply the same condition on the left and right.

    rightFromLabel => $label

  The label from which to receive the rows on the right side. Optional. Default: the Output label of rightTable.

  Can be used to introduce a label that would filter out some of the input. THIS IS DANGEROUS! To preserve consistency, always filter by the key field(s) only, and apply the same condition on the left and right.

    leftIdxPath => [ @path ]

  An array reference containing the path name of an index type in the left table used for look-up. The index must absolutely be a Hashed or Ordered one (leaf or not), not of any other kind. The number and order of key fields in the left and right indexes must match, since indexes define the fields used for the join. The types of key fields have to match exactly unless the auto-casting is allowed by the option overrideKeyTypes being set to 1.

    rightIdxPath => [ @path ]

  An array reference containing the path name of an index type in the left table used for look-up. The index must absolutely be a Hashed or Ordered one (leaf or not), not of any other kind. The number and order of key fields in the left and right indexes must match, since indexes define the fields used for the join. The types of key fields have to match exactly unless the auto-casting is allowed by the option overrideKeyTypes being set to 1.

    leftFields => [ @patterns ]

  Reference to an array of patterns for the left-side fields to pass through to the result rows, with the syntax of

      Triceps::Fields::filter()

  . Optional. If not defined then pass everything.

    rightFields => [ @patterns ]

  Reference to an array of patterns for the right-side fields to pass through to the result rows, with the syntax of

      Triceps::Fields::filter()

  . Optional. If not defined then pass everything.

    fieldsLeftFirst => 0/1

  Flag: if 1, in the result rows put the fields from the left side first, then from the right side; if 0, then in the opposite order. Optional. Default: 1.

    fieldsUniqKey => $enum

  Controls the logic that prevents the duplication of the key fields in the result rows (since by definition their originals are present in both the left and right tables). Optional.

  This is done by setting the option fieldsMirrorKey of the underlying LookupJoins to 1 and by manipulating the left/rightFields options: one side is left unchanged, and thus lets the user pass the key fields as usual, while the other side gets

      '!key'

  specs prepended to the front of it for each key field, thus blocking these fields and removing the duplication.

  The enumerated values of this option are one of:

  none
    Do not change either of the left/rightFields, and do not enable the key mirroring at all.
  manual
    Enable the key mirroring; do not change either of the left/rightFields, leaving the full control to the user.
  left
    Enable the key mirroring; do not change leftFields (and thus pass the key fields in there), block the keys from rightFields.
  right
    Enable the key mirroring; do not change rightFields (and thus pass the key fields in there), block the keys from leftFields.
  first
    The default value. Enable the key mirroring; do not change whatever side goes first according to the option fieldsLeftFirst (and thus pass the key in there), block the keys from the other side.

    by => [ @fields ]

  Reference to an array containing pairs of field names used for look-up,

      [leftFld1, rightFld1, leftFld2, rightFld2, ...]

  . Optional. The options by and byLeft are mutually exclusive. If none of them is used, by default the field lists are taken from the index type keys, matched up in the order they appear in the indexes. But if a different order is desired, this option can be used to override it. The fields must still be the same, just the order may change.

    byLeft => [ @patterns ]

  Reference to an array containing the patterns in the syntax of

      Triceps::Fields::filter()

  . It gets applied to the left-side fields, the fields that pass through become the key fields, and their translations are the names of the matching fields on the right side. Optional. The options by and byLeft are mutually exclusive. If none of them is used, by default the field lists are taken from the index type keys, matched up in the order they appear in the indexes. But if a different order is desired, this option can be used to override it. The fields must still be the same, just the order may change.

    type => $enum

  The type of join from the inner/outer classification, one of: inner, left for left outer, right for right outer, outer for full outer. Optional. Default: inner.

    leftSaveJoinerTo => \$code

  Reference to a scalar where to save a copy of the joiner function source code for the left side. Optional.

    rightSaveJoinerTo => \$code

  Reference to a scalar where to save a copy of the joiner function source code for the right side. Optional.

    overrideSimpleMinded => 0/1

  Flag: if 1, do not try to create the correct DELETE-INSERT sequence for the updates, just produce the rows with the same opcode as the incoming ones. The only possible usage of this option might be to simulate the CEP systems that do not support the opcodes and treat averything as an INSERT. The data produced is outright garbage. It can also be used for the entertainment value, to show, why it's garbage. Optional. Default: 0.

    overrideKeyTypes => 0/1

  Flag: if 1, allow the key field types to be not exactly the same. Optional. Default: 0.

    $rt = $joiner->getResultRowType();

Returns the row type of the join result.

    $lb = $joiner->getOutputLabel();

Returns the output label of the joiner. The results from processing of the input rowops come out here. Note that there is no input label, the join is fed by connecting to the tables (with the possible override with the options left/rightFromLabel).

    $fret = $joiner->fnReturn();

Returns an FnReturn object connected to the output of this joiner. The FnReturn contains one label out. The FnReturn is created on the first call of this method and is kept in the joiner object. All the following calls return the same object. See more detail in &xrsp;.

    $res = $joiner->getUnit();
    $res = $joiner->getName();
    $res = $joiner->getLeftTable();
    $res = $joiner->getRightTable();
    $res = $joiner->getLeftIdxPath();
    $res = $joiner->getRightIdxPath();
    $res = $joiner->getLeftFields();
    $res = $joiner->getRightFields();
    $res = $joiner->getFieldsLeftFirst();
    $res = $joiner->getFieldsUniqKey();
    $res = $joiner->getBy();
    $res = $joiner->getByLeft();
    $res = $joiner->getType();
    $res = $joiner->getOverrideSimpleMinded();
    $res = $joiner->getOverrideKeyTypes();

Get back the values of the options use to construct the object. If such an option was not set, returns the default value, or the automatically calculated value. Sometimes an automatically calculated value may even override the user-specified value. There is no way to get back left/rightFromLabel, they are discarded after the JoinTwo is constructed and chained.

JoinTwo