NAME

       stag-db - persistent storage and retrieval for stag data (xml, sxpr, itext)

SYNOPSIS

         stag-db -r person -k social_security_no -i ./person-idx myrecords.xml
         stag-db -i ./person-idx -q 999-9999-9999 -q 888-8888-8888

DESCRIPTION

       Builds a simple file-based database for persistent storage and retrieval of nodes from a
       stag compatible document.

       Imagine you have a very large file of data, in a stag compatible format such as XML. You
       want to index all the elements of type person; each person can be uniquely identified by
       social_security_no, which is a direct subnode of person

       The first thing to do is to build an index file, which will be stored in your current
       directory:

         stag-db -r person -k social_security_no -i ./person-idx myrecords.xml

       You can then use the index "person-idx" to retrieve person nodes by their social security
       number

         stag-db -i ./person-idx -q 999-9999-9999 > some-person.xml

       You can export using different stag formats

         stag-db -i ./person-idx -q 999-9999-9999 -w sxpr > some-person.xml

       You can retrieve multiple nodes (although these need to be rooted to make a valid file)

         stag-db -i ./person-idx -q 999-9999-9999 -q 888-8888-8888 -top personset

       Or you can use a list of IDs from a file (newline delimited)

         stag-db -i ./person-idx -qf my_ss_nmbrs.txt -top personset

   ARGUMENTS
       -i INDEXFILE

       This file will be used as the persistent index for storage/retrieval

       -r RELATION-NAME

       This is the name of the stag node (XML element) that will be stored in the index; for
       example, with the XML below you may want to use the node name person and the unique key id

         <person_set>
           <person>
             <id>...</id>
           </person>
           <person>
             <id>...</id>
           </person>
           ...
         </person_set>

       This flag should only be used when you want to store data

       -k UNIQUE-KEY

       This node will be used as the unique/primary key for the data

       This node should be nested directly below the node that is being stored in the index - if
       it is more that one below, specify a path

       This flag should only be used when you want to store data

       -u UNIQUE-KEY

       Synonym for -k

       -p PARSER

       This can be the name of a stag supported format (xml, sxpr, itext) - XML is assumed by
       default

       It can also be a module name - this module is used to parse the input file into a stag
       stream; see Data::Stag::BaseGenerator for details on writing your own parsers/event
       generators

       This flag should only be used when you want to store data

       -q QUERY-ID

       Fetches the relation/node with unique key value equal to query-id

       Multiple arguments can be passed by specifying -q multple times

       This flag should only be used when you want to query data

       -top NODE-NAME

       If this is specified in conjunction with -q or -qf then all the query result nodes will be
       nested inside a node with this name (ie this provides a root for the resulting document
       tree)

       -qf QUERY-FILE

       This is a file of newline-seperated IDs; this is useful for querying the index in batch

       -keys

       This will write a list of all primary keys in the index

       -w WRITER

       This format will be used to write the data; can be any stag format (xml, sxpr, itext) -
       default XML.

       Can also be a module that catches the incoming stag event stream and does something with
       it (for example, this could be a module you write yourself that transforms the stag events
       into HTML)

SEE ALSO

       Data::Stag

       For more complex stag to database mapping, see DBIx::DBStag and the scripts

       stag-storenode

       selectall_xml