Catmandu::Plugin::SideCar(3pm)

NAME
Catmandu::Plugin::SideCar - Automatically update a parallel Catmandu::Store with metadata

SYNOPSIS
 # Using the command line

 $ cat catmandu.yml
 ---
 store:
     files:
      package: File::Simple
      options:
          root: /data/test123
          bags:
              index:
                  plugins:
                      - SideCar
                  sidecar:
                          package: ElasticSearch
                          options:
                              client: '1_0::Direct'
                              index_name: catmandu

    ...

 # Add files to the FileStore in bag 1234
 $ catmandu stream /tmp/test.txt to files --bag 1234 --id test.txt

 # Add metadata to the FileStore for bag 1234
 $ cat metadata.yml
 ---
 _id: 1234
 colors:
    - red
    - green
    - blue
 name: test
 ...
 $ catmandu import YAML to files < metadata.yml

 # Export the metadata again from the FileStore
 $ catmandu export files to YAML
 ---
 _id: 1234
 colors:
    - red
    - green
    - blue
 name: test
 ...

 # Or in your Perl program
 my $store = Catmandu->store('File::Simple',
            root => 'data/test123'
            bags => {
                index => {
                    plugins => [qw(SideCar)],
                    sidecar => {
                        package => "ElasticSearch",
                        options => {
                            client => '1_0::Direct',
                            index_name => 'catmandu',
                        }
                    }
               }
            });

 my $index = $store->index;

 $index->add({ _id => '1234' , colors => [qw(red green blue)] , name => 'test'});

 my $files = $index->files('1234');
 $files->upload(IO::File->new('</tmp/test.txt'), 'test.txt');

 my $file = $files->get('text.txt');

 $files->steam(IO::File->new('>/tmp/test.txt'),$file);

DESCRIPTION
The Catmandu::Plugin::SideCar can be used to combine Catmandu::Store-s , Catmandu::FileStore-s (and Catmandu::Store::Multi , Catmandu::Store::File::Multi) as one access point. Every get,add,delete,drop and commit action in the store will be first executed in the original store and re-executed in the SideCar store.

COMBINING A FILESTORE WITH A STORE
To add metadata to a Catmandu::FileStore a SideCar needs to be added to the "index" bag of the FileStore:

    package: File::Simple
    options:
        root: /data/test123
        bags:
            index:
                plugins:
                    - SideCar
                sidecar:
                        package: ElasticSearch
                        options:
                            client: '1_0::Direct'
                            index_name: catmandu
                sidecar_bag: data

COMBINING A STORE WITH A FILESTORE
To add files to a Catmandu::Store a SideCar needs to be added to the bag containing the metadata (by default "data"):

    package: ElasticSearch
    options:
        client: '1_0::Direct'
        index_name: catmandu
        bags:
            data:
                plugins:
                    - SideCar
                sidecar:
                        package: File::Simple
                        options:
                            root: /data/test123
                            uuid: 1
                sidecar_bag: index

Notice that we added for the Catmandu::Store::File::Simple the requires "uuid" options because the Catmandu::Store::ElasticSearch is using UUIDs as default identifiers.

RESTRICTIONS
Some Catmandu::FileStore-s may set restrictions on the "_id"-s that can be used in records.

CONFIGURATION

sidecar STRING
sidecar HASH
sidecar Catmandu::Store | Catmandu::FileStore
    The pointer to a configured Catmandu::Store or Catmandu::FileStore.

sidecar_bag
    The SideCar Catmandu::Bag into which to store the data (default 'bag').

SEE ALSO
Catmandu::Store, Catmandu::Bag, Catmandu::FileStore