---
name: "stag-db"
section: "1p"
platform: "linux"
package: "libdata-stag-perl"
version: "0.14-3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/stag-db"
---

# stag-db(1p)

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

## 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