STAG-DB(1)

💖 STAG-DB 💖

okay bestie, welcome to stag-db — the User Contributed Perl Documentation icon that does persistent storage and retrieval for stag data (xml, sxpr, itext). she's literally the group chat's designated archivist 🫶

---

✨ NAME ✨

stag-db — persistent storage and retrieval for stag data (xml, sxpr, itext). no cap, that's the whole vibe.

---

🌸 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

like… two lines, both iconic, both doing completely different jobs 💅

---

🦋 DESCRIPTION 🦋

so it builds a simple file-based database for persistent storage and retrieval of nodes from a stag compatible document. that's it, that's the whole assignment, and she ate.

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. (yes, directly below. we'll get to that, hold on 🎀)

first thing to do is 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

then you can 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

main character energy from a command line tool, honestly 😭💖

---

👑 ARGUMENTS 👑

🍓 -i INDEXFILE

this file will be used as the persistent index for storage/retrieval. she's the memory, she's the whole point, protect her at all costs 🫶

🧚 -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. not when you're querying, bestie, read the room 💅

🌈 -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. (yes, "that" is what the original says. we're keeping it. no edits, fr fr 🙈)

this flag should only be used when you want to store data.

🎀 -u UNIQUE-KEY

synonym for -k. same girl, different name tag ✨

💜 -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. (typo is canon, we don't fix the canon 💀)

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). she's the lil roof over everybody's head 🏠

🦋 -qf QUERY-FILE

this is a file of newline-seperated IDs; this is useful for querying the index in batch. (again: typo canon. we stan 🫶)

💅 -keys

this will write a list of all primary keys in the index. dump them all, queen.

🔥 -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). go off, build your own little transformer, i believe in you 😭💖

---

🌟 SEE ALSO 🌟

• Data::Stag
• for more complex stag to database mapping, see DBIx::DBStag and the scripts
• stag-storenode
• selectall_xml

---

lowkey a whole ecosystem. iykyk 🌈

and that's the page, bestie!! brought to you by perl v5.42.0, dated 2025-07-25 — go build an index, go query it, go be iconic 💅✨💖