# LookupJoin reference

LookupJoin receives the incoming rows and looks up the matches for them from a table, producing the joined rows.

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

Constructs the LookupJoin template. Confesses on any errors. The options are:

    unit

  Scheduling unit object where this template belongs. May be skipped if leftFromLabel is used.

    name

  Name of this LookupJoin object. Will be used as a prefix to create the names of internal objects. The input label will be named name.in and the output label name.out.

    leftRowType

  Type of the rows that will be coming in at the left side of the join, and will be used for lookup. Mutually exclusive with leftFromLabel, one must be present.

    leftFromLabel

  Source of rows for the left side of the join; implies their type and the scheduling unit where this object belongs. Mutually exclusive with leftRowType, one must be present.

    rightTable

  Table object where to do the look-ups.

    rightIdxPath

  Array reference containing the path name of index type in table used for the look-up. The index absolutely must be a Hash (leaf or non-leaf), not of any other kind. Optional. Default: first top-level Hash index type.

    leftFields

  Reference to an array of patterns for the left-side fields to pass through. Syntax as described in

      Triceps::Fields::filter()

  . Optional. If not defined then pass everything.

    rightFields

  Reference to an array of patterns for the right-side fields to pass through. Syntax as described in

      Triceps::Fields::filter()

  . Optional. If not defined then pass everything (which is probably a bad idea since it would include the second copy of the key fields, so better override at least one of the leftFields or rightFields).

    fieldsLeftFirst

  Flag: in the resulting rows put the fields from the left side first, then from right side. If 0, then opposite. Optional. Default: 1.

    fieldsMirrorKey

  Flag: even if the join is an outer join and the row on one side is absent, when generating the result row, the key fields in it will still be present by mirroring them from the other side. Used by JoinTwo. Optional. Default: 0.

    by

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

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

  . The set of right-side fields must match the keys of the index path from the option rightIdxPath, though possibly in a different order. Mutually exclusive with byLeft, one must be present.

    byLeft

  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. The set of right-side fields must match the keys of the index path from the option

      rightIdxPath

  , though possibly in a different order. Mutually exclusive with by, one must be present.

    isLeft

  Flag: 1 for left outer join, 0 for inner join. Optional. Default: 1.

    limitOne

  Flag: 1 to return no more than one row even if multiple rows have been found by the look-up, 0 to return all the found matches. Optional. Default: 0 for the non-leaf right index, 1 for leaf right index. If the right index is leaf, this option will be always automatically set to 1, even if the user specified otherwise, since there is no way to look up more than one matching row in it.

    automatic

  Flag: 1 means that the manual

      lookup()

  method will never be called. This allows to optimize the label handler code and always take the opcode into account when processing the rows. 0 means that

      lookup()

  will be used. Optional. Default: 1.

    oppositeOuter

  Flag: 1 for the right outer join, 0 for inner join. If both options isLeft and oppositeOuter are set to 1, then this is a full outer join. If set to 1, each update that finds a match in the right table, may produce a DELETE-INSERT sequence that keeps the state of the right or full outer join consistent. The full outer or right outer join logic makes sense only if this LookupJoin is one of a pair in a bigger JoinTwo object. Each of these LookupJoins thinks of itself as left and of the other one as right, while JoinTwo presents a consistent whole picture to the user. Used by JoinTwo. May be used only when automatic is 1. Optional. Default: 0.

    groupSizeCode

  Reference to a function that would compute the group size for this side's table. Optional, used only when oppositeOuter is 1.

  The group size together with the opcode is then used to decide if a DELETE-INSERT sequence needs to be produced instead of a plain INSERT or DELETE. It is needed when this side's index (not visible here in LookupJoin but visible in the JoinTwo that envelopes it) is non-leaf, so multiple rows on this side may match each row on the other side. The DELETE-INSERT pair needs to be generated only if the current rowop was a deletion of the last matching row or insertion of the first matching row on this side. If groupSizeCode is not defined, the DELETE-INSERT pair is always generated (which is appropriate if this side's index is leaf, and every row is the last or first one). If groupSizeCode is defined, it should return the group size in the left table by the left index for the input row. If the operation is INSERT, the size of 1 would mean that the DELETE-INSERT pair needs to be generated. If the operation is DELETE, the size of 0 would mean that the DELETE-INSERT pair needs to be generated. Called as:

      &$groupSizeCode($opcode, $leftRow)

  The default undefined groupSizeCode is equivalent to

      sub { &Triceps::isInsert($_[0]); }

  but leaving it undefined is more efficient since allows to hardcode this logic at compile time instead of calling the function for every rowop.

    saveJoinerTo

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

    @rows = $joiner->lookup($leftRow);

Looks up the matches for the

    $leftRow

and return the array of the result rows. If the option isLeft is 0, the array may be empty. If the option limitOne is 1, the array will contain no more than one row, and may be assigned directly to a scalar. May be used only when the option automatic is 0.

    $rt = $joiner->getResultRowType();

Returns the row type of the join result.

    $lb = $joiner->getInputLabel();

Returns the input label of the joiner. The rowops sent there will be processed as coming on the left side of the join. The result will be produced on the output label.

    $lb = $joiner->getOutputLabel();

Returns the output label of the joiner. The results from processing of the input rowops come out here. Note that the results of the

    lookup()

calls do not come out at the output label, they are only returned to the caller.

    $res = $joiner->getUnit();
    $res = $joiner->getName();
    $res = $joiner->getLeftRowType();
    $res = $joiner->getRightTable();
    $res = $joiner->getRightIdxPath();
    $res = $joiner->getLeftFields();
    $res = $joiner->getRightFields();
    $res = $joiner->getFieldsLeftFirst();
    $res = $joiner->getFieldsMirrorKey();
    $res = $joiner->getBy();
    $res = $joiner->getByLeft();
    $res = $joiner->getIsLeft();
    $res = $joiner->getLimitOne();
    $res = $joiner->getAutomatic();
    $res = $joiner->getOppositeOuter();
    $res = $joiner->getGroupSizeCode();

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 leftFromLabel, it is discarded after the LookupJoin is constructed and chained.

LookupJoin