STAG-DB(1p)

💖 NAME 💖

okay bestie, welcome to stag-db — it's giving persistent storage and retrieval for stag data (xml, sxpr, itext). yes that's the whole vibe. it's a User Contributed Perl Documentation page, and it's literally about to change your whole file-based-database life. periodt. 🎀

---

✨ 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. that's it. that's the whole interface. iconic. 💅

---

🌸 DESCRIPTION 🌸

So basically stag-db builds a simple file-based database for persistent storage and retrieval of nodes from a stag compatible document. no server, no drama, no cap. 🦋

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

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 — don't forget the root, bestie, it's giving chaos otherwise 😭):

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. she's the main character of this whole operation, fr fr. 👑
• -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. same energy, different letter, we love options. ✨
• -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). the way that this single flag saves your whole output from being invalid… obsessed. 🌈
• -qf QUERY-FILE — This is a file of newline-seperated IDs; this is useful for querying the index in batch. batch era. 💅
• -keys — This will write a list of all primary keys in the index. like a little roll call for your data. 📋
• -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 writer, main character energy fr. 🔥

---

🫶 SEE ALSO 🫶

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

---

little PSA bestie: several of these flags are store-only and several are query-only. mixing them up is giving "why is nothing working" and we do not want that for you. read the flag, respect the flag. 💀

---

okay that's the whole page, and a cute lil sign-off for you: this one's from perl v5.34.0, dated 2022-06-12, and yes she's filed under STAG-DB(1p). slay, bye bestie 💖🎀🦋