##### Joins

filter_out = object() # tells Join to filter out rows that match the join

    def __init__(self, table, mapping, type_=None):

        '''

        @param mapping dict(right_table_col=left_table_col, ...)

        @param type_ None (for plain join)|str (e.g. 'LEFT')|filter_out

            * filter_out: equivalent to 'LEFT' with the query filtered by

              `table_pkey IS NULL` (indicating no match)

            # Note that right_table_col is on the left in the comparison

            # Parse special values

            cond = as_ValueCond(left_table_col, left_table)

            return cond.to_str(db, as_Col(right_table_col, self.table))

        type_ = self.type_

        joins = self.mapping

        if type_ is not filter_out and reduce(operator.and_,

            # all cols w/ USING, so can use simpler USING syntax

            cols = (as_Col(v).to_str(db) for v in joins.iterkeys())

            join_cond = 'USING ('+(', '.join(cols))+')'

    in_tables0 = in_tables.pop(0) # first table is separate

    in_pkey = pkey(db, in_tables0, recover=True)

    in_pkey_col = sql_gen.as_Col(in_pkey, in_tables0)

        for v in in_tables]

    out_pkey = pkey(db, out_table, recover=True)

                db.log_debug('Joining together output and input pkeys')

                run_query_into_pkeys(*mk_select(db, [in_pkeys_ref[0],

                    sql_gen.Join(out_pkeys_ref[0],

            db.log_debug("Setting missing rows' pkeys to NULL")

            missing_rows_joins = input_joins+[sql_gen.Join(pkeys_ref[0],