NAME

recs-join

recs-join --help-all

 Help from: --help-basic:
 Usage: recs-join <args> <inputkey> <dbkey> <dbfile> [<files>]
    Records of input (or records from <files>) are joined against records in <dbfile>, using field <inputkey> from input and field
    <dbkey> from <dbfile>. Each record from input may match 0, 1, or more records from <dbfile>. Each pair of matches will be
    combined to form a larger record, with fields from the dbfile overwriting fields from the input stream. If the join is a left
    join or inner join, any inputs that do not match a dbfile record are discarded. If the join is a right join or inner join, any
    db records that do not match an input record are discarded.
 
    dbkey and inputkey may be key specs, see '--help-keyspecs' for more information
 
 Arguments:
    --left                       Do a left join
    --right                      Do a right join
    --inner                      Do an inner join (This is the default)
    --outer                      Do an outer join
    --operation                  An perl expression to evaluate for merging two records together, in place of the default behavior
                                 of db fields overwriting input fields. See "Operation" below.
    --accumulate-right           Accumulate all input records with the same key onto each db record matching that key. See
                                 "Accumulate Right" below.
    --filename-key|fk <keyspec>  Add a key with the source filename (if no filename is applicable will put NONE)
 
   Help Options:
       --help-all       Output all help for this script
       --help           This help screen
       --help-full      Help on join types and accumulate-right
       --help-keyspecs  Help on keyspecs, a way to index deeply and with regexes
       --help-snippet   Help on code snippets
 
 Operation:
    The expression provided is evaluated for every pair of db record and input record that have matching keys, in place of the
    default operation to overwrite input fields with db fields. The variable $d is set to a App::RecordStream::Record object for the
    db record, and $i is set to a App::RecordStream::Record object for the input record. The $d record is used for the result. Thus,
    if you provide an empty operation, the result will contain only fields from the db record.
 
 Examples:
    Join type from STDIN and typeName from dbfile
       cat recs | recs-join type typeName dbfile
 
    Join host name from a mapping file to machines to get IPs
       recs-join host host hostIpMapping machines
 
 Help from: --help-full:
 Join Types
    For instance, if you did:
    recs-join type typeName dbfile fromfile
 
    with a db file like:
    { 'typeName': 'foo', 'hasSetting': 1 }
    { 'typeName': 'bar', 'hasSetting': 0 }
 
    and joined that with
    { 'name': 'something', 'type': 'foo'}
    { 'name': 'blarg', 'type': 'hip'}
 
    for an inner (default) join, you would get
    { 'name': 'something', 'type': 'foo', 'typeName': 'foo', 'hasSetting': 1}
 
    for an outer join, you would get
    { 'name': 'something', 'type': 'foo', 'typeName': 'foo', 'hasSetting': 1}
    { 'name': 'blarg', 'type': 'hip'}
    { 'typeName': 'bar', 'hasSetting': 0 }
 
    for a left join, you would get
    { 'name': 'something', 'type': 'foo', 'typeName': 'foo', 'hasSetting': 1}
    { 'typeName': 'bar', 'hasSetting': 0 }
 
    for a right join, you would get
    { 'name': 'something', 'type': 'foo', 'typeName': 'foo', 'hasSetting': 1}
    { 'name': 'blarg', 'type': 'hip'}
 
 Accumulate Right:
    Accumulate all input records with the same key onto each db record matching
    that key. This means that a db record can have multiple input records merged
    into it. If no operation is provided, any fields in second or later records
    will be lost due to them being discarded. This option is most useful with a
    user defined operation to handle collisions. For example, one could provide
    an operation to add fields together:
 
    recs-join --left --operation '
      foreach $k (keys %$i) {
        if (exists($d->{$k})) {
          if ($k =~ /^value/) {$d->{$k} = $d->{$k} + $i->{$k};}
        } else {
          $d->{$k} = $i->{$k};
        }
      }' --accumulate-right name name dbfile inputfile
 
 Help from: --help-keyspecs:
   KEY SPECS
    A key spec is short way of specifying a field with prefixes or regular expressions, it may also be nested into hashes and
    arrays. Use a '/' to nest into a hash and a '#NUM' to index into an array (i.e. #2)
 
    An example is in order, take a record like this:
 
      {"biz":["a","b","c"],"foo":{"bar 1":1},"zap":"blah1"}
      {"biz":["a","b","c"],"foo":{"bar 1":2},"zap":"blah2"}
      {"biz":["a","b","c"],"foo":{"bar 1":3},"zap":"blah3"}
 
    In this case a key spec of 'foo/bar 1' would have the values 1,2, and 3 in the respective records.
 
    Similarly, 'biz/#0' would have the value of 'a' for all 3 records
 
    You can also prefix key specs with '@' to engage the fuzzy matching logic
 
    Fuzzy matching works like this in order, first key to match wins
      1. Exact match ( eq )
      2. Prefix match ( m/^/ )
      3. Match anywehre in the key (m//)
 
    So, in the above example '@b/#2', the 'b' portion would expand to 'biz' and 2 would be the index into the array, so all records
    would have the value of 'c'
 
    Simiarly, @f/b would have values 1, 2, and 3
 
    You can escape / with a \. For example, if you have a record:
    {"foo/bar":2}
 
    You can address that key with foo\/bar
 
 Help from: --help-snippet:
    CODE SNIPPETS:
     Recs code snippets are perl code, with one exception. There a couple of variables predefined for you, and one piece of special
     syntax to assist in modifying hashes.
 
 Special Variables:
     $r - the current record object. This may be used exactly like a hash, or you can use some of the special record functions, see
     App::RecordStream::Record for more information
 
     $line - This is the number of records run through the code snippet, starting at 1. For most scripts this corresponds to the
     line number of the input to the script.
 
     $filename - The filename of the originating record. Note: This is only useful if you're passing filenames directly to the recs
     script, piping from other recs scripts or from cat, for instance, will not have a useful filename.
 
 Special Syntax
     Use {{search_string}} to look for a string in the keys of a record, use / to nest keys. You can nest into arrays by using an
     index. If you are vivifying arrays (if the array doesn't exist, prefix your key with # so that an array rather than a hash will
     be created to put a / in your key, escape it twice, i.e. \/
 
     This is exactly the same as a key spec that is always prefaced with a @, see 'man recs' for more info on key specs
 
     For example: A record that looks like:
     { "foo" : { "bar 1" : 1 }, "zoo" : 2}
     Could be accessed like this:
 
     # value of zoo  # value of $r->{foo}->{bar 1}: (comma separate nested keys)
     {{zoo}}         {{foo/ar 1}}
 
     # Even assign to values (set the foo key to the value 1)
     {{foo}} = 1
 
     # And auto, vivify
     {{new_key/array_key/#0}} = 3 # creates an array within a hash within a hash
 
     # Index into an array
     {{array_key/#3}} # The value of index 3 of the array ref under the
     'array_key' hash key.
 
     This matching is a fuzzy keyspec matching, see --help-keyspecs for more details.
 

See Also

RecordStream(3) - Overview of the scripts and the system

recs-examples(3) - A set of simple recs examples

recs-story(3) - A humorous introduction to RecordStream

SCRIPT --help - every script has a --help option, like the output above