NAME

       Catmandu::Fix::lookup_in_store - change the value of a HASH key or ARRAY index by looking
       up its value in a store

SYNOPSIS

          # Lookup in an SQLLite database
          lookup_in_store(foo.bar, DBI, data_source: "dbi:SQLite:path/data.sqlite")

          # Lookup in a MongoDB database
          lookup_in_store(foo.bar, MongoDB, database_name: lookups, bag: mydata)

          # Lookup in a MongoDB database, using the default bag and a default value when nothing found
          lookup_in_store(foo.bar, MongoDB, database_name: lookups, default: 'default value')

          # Lookup in a MongoDB database, using the default bag and delete the foo.bar field when nothing found
          lookup_in_store(foo.bar, MongoDB, database_name: lookups, delete: 1)

          # Or, a much faster option: use a named store in a catmandu.yml file
          #
          # store:
          #  mydbi:
          #    package: DBI
          #    options:
          #      data_source: "dbi:SQLite:path/data.sqlite"
          #  mymongo:
          #    package: MongoDB
          #    options:
          #      database_name: lookups
          lookup_in_store(foo.bar, mydbi)
          lookup_in_store(foo.bar, mymongo, bag: mydata)
          lookup_in_store(foo.bar, mymongo, default: 'default value')
          lookup_in_store(foo.bar, mymongo, delete: 1)

DESCRIPTION

   lookup_in_store(PATH,STORE[,store_param: store_val, ...][,bag:
       bag_name][,delete:1][,default:value])
       Use the lookup_in_store fix to match a field in a record to the "_id" field in a
       Catmandu::Store of choice.  For instance, if a Catmandu::Store contains these records:

           ---
           _id: water
           fr: l'eau
           de: wasser
           en: water
           nl: water
           ---
           _id: tree
           fr: arbre
           de: baum
           en: tree
           nl: boom

       And you data contains these fields:

           ---
           _id: 001
           tag: tree
           ---
           _id: 002
           tag: water

       Then, the fix below will lookup a tag in the Catmandu::Store and replace it with the
       database value:

           lookup_in_store(tag, DBI, data_source: "dbi:SQLite:path/data.sqlite")

       The resulting data will contain:

           ---
           _id: 001
           tag:
             _id: tree
             fr: arbre
             de: baum
             en: tree
             nl: boom
           ---
           _id: 002
           tag:
             _id: water
             fr: l'eau
             de: wasser
             en: water
             nl: water

DATABASE CONNECTIONS

       For every call to a "lookup_in_store" a new database connection is created. It is much
       more effient to used named stores in a "catmandu.yml" file. This file needs to contain all
       the connection parameters to the database. E.g.

           store:
              mystore:
                package: MongoDB
                options:
                   database_name: mydata

       The  "catmandu.yml" file should be available in the same directory as where the "catmandu"
       command is executed. Or, this directory can be set with the "-L" option:

           $ catmandu -L /tmp/path convert ...

SEE ALSO

       Catmandu::Fix, Catmandu::Store , Catmandu::Fix::add_to_store