docs: def join(table1, table2, on=None, how='inner', name=None):
      """
      Join two tables and return the resulting Table object.
  
      Fields in the resulting table have their names prefixed with their
      corresponding table name. For example, when joining `item` and
      `parse` tables, the `i-input` field of the `item` table will be
      named `item:i-input` in the resulting Table. Pivot fields (those
      in *on*) are only stored once without the prefix.
  
      Both inner and left joins are possible by setting the *how*
      parameter to `inner` and `left`, respectively.
  
      .. warning::
  
         Both *table2* and the resulting joined table will exist in
         memory for this operation, so it is not recommended for very
         large tables on low-memory systems.
  
      Args:
          table1 (:class:`Table`): the left table to join
          table2 (:class:`Table`): the right table to join
          on (str): the shared key to use for joining; if `None`, find
              shared keys using the schemata of the tables
          how (str): the method used for joining (`"inner"` or `"left"`)
          name (str): the name assigned to the resulting table
      """
      if how not in ('inner', 'left'):
          ItsdbError('Only \'inner\' and \'left\' join methods are allowed.')
      # validate and normalize the pivot
      on = _join_pivot(on, table1, table2)
      # the fields of the joined table
      fields = _RelationJoin(table1.fields, table2.fields, on=on)
      # get key mappings to the right side (useful for inner and left joins)
      get_key = lambda rec: tuple(rec.get(k) for k in on)
      key_indices = set(table2.fields.index(k) for k in on)
      right = defaultdict(list)
      for rec in table2:
          right[get_key(rec)].append([c for i, c in enumerate(rec)
                                      if i not in key_indices])
      # build joined table
      rfill = [f.default_value() for f in table2.fields if f.name not in on]
      joined = []
      for lrec in table1:
          k = get_key(lrec)
          if how == 'left' or k in right:
              joined.extend(lrec + rrec for rrec in right.get(k, [rfill]))
  
      return Table(fields, joined)