STAG-IR(1p)

💖 STAG-IR(1p) — bestie, it's the stag-ir.pl page 💖

okay so this is the manual for stag-ir.pl, a User Contributed Perl Documentation situation, and it's literally information retrieval with a simple relational index. no cap. grab a snack, we're doing database things ✨

✨ SYNOPSIS ✨

stag-ir.pl -r person -k social_security_no -d Pg:mydb myrecords.xml
stag-ir.pl -d Pg:mydb -q 999-9999-9999 -q 888-8888-8888

🌸 DESCRIPTION 🌸

So the whole vibe is: it indexes stag nodes (that's XML Elements, iykyk) inside a simple relational db structure — keyed by ID with an XML Blob as a value. simple as that. iconic.

Now imagine you have a very large file of data, in a stag compatible format like 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. chef's kiss setup.

Step one, bestie: build the index file. It gets stored in the database mydb.

stag-ir.pl -r person -k social_security_no -d Pg:mydb myrecords.xml

Then you can use the index "person-idx" to retrieve person nodes by their social security number 🎀

stag-ir.pl -d Pg:mydb -q 999-9999-9999 > some-person.xml

You can export using different stag formats too, so versatile 💅

stag-ir.pl -d Pg:mydb -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 — keep that in mind bestie, it's giving "why is my XML invalid")

stag-ir.pl -d Pg:mydb -q 999-9999-9999 -q 888-8888-8888 -top personset

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

stag-ir.pl -d Pg:mydb -qf my_ss_nmbrs.txt -top personset

---

🦋 ARGUMENTS 🦋

• -d DB_NAME — this database will be used for storing the stag nodes 💾
  • the name can be a logical name, or a DBI locator, or DBStag shorthand — go peek at DBIx::DBStag for that
  • 🚨 the database must already exist. it will not manifest itself for you, bestie.
• -clear — deletes all data from the relation type (the one you specified with -r) before loading 🧹
• -insertonly — does not check if the ID in the file exists in the db. it will always attempt an INSERT (and will fail if the ID already exists 😭)
  • this is the fastest way to load data (only one SQL operation per node rather than two) but it is only safe if there is no existing data
  • (Default is clobber mode — existing data with same ID will be replaced)
• -newonly — if there is already data in the specified relation in the db, and the XML being loaded specifies an ID that is already in the db, then this node will be ignored 🙈
  • (Default is clobber mode — existing data with same ID will be replaced)
• -transaction_size — a commit will be performed every n UPDATEs/COMMITs (and at the end)
  • Default is autocommit
  • > ⚠️ note that if you are using -insertonly, and you are using transactions, and the input file contains an ID already in the database, then the transaction will fail because this script will try and insert a duplicate ID. that's the drama.
• -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 than one below, specify a path
  • this flag should only be used when you want to store data
• -u UNIQUE-KEY — synonym for -k 🫶
• -create — if specified, this will create a table for the relation name specified below; you should use this the first time you index a relation 🏗️
• -idtype TYPE — (optional) 🎀
  • this is the SQL datatype for the unique key; it defaults to VARCHAR(255)
  • if you know that your id is an integer, you can specify INTEGER here
  • if your id is always a 8-character field you can do this:

-idtype 'CHAR(8)'

• this option only makes sense when combined with the -c option

• -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 — that 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 multiple 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 ⭐

---

💜 SEE ALSO 💜

• Data::Stag
• for more complex stag to database mapping, see DBIx::DBStag and the scripts
• stag-db.pl use file DBM indexes
• stag-storenode.pl is for storing fully normalised stag trees
• selectall_xml

---

and that's the whole page, bestie 🫶 no notes, ate and left no crumbs. this little manual is from perl v5.36.0, dated 2022-10-14, and the page title is STAG-IR(1p) — main character energy forever 💅✨