Metadata is data about data. That is, it provides additional information about a document that isn't really part of that document. For example, documents added to the components.dbxml container were given a name. Each name represents metadata about each individual document. Other common metadata might include the time a document was modified or the name of the person who modified it. In addition, there are cases when modifying the actual document is not possible and additional data is required to track desired information about the document. As an example, you may be required to keep track of what user last altered a document within a container, and you may need to do this in a way that does not modify the document itself. For this reason, BDB XML stores metadata separately from the document, while still allowing you to perform indexed searches against the metadata as if it were actually part of the document.

To add custom metadata to a document, use the setMetaData command.

dbxml> openContainer components.dbxml

dbxml> setMetaData component1 '' modifyuser string john

MetaData item 'modifyuser' added to document component1

dbxml> setMetaData component2 '' modifyuser string mary

MetaData item 'modifyuser' added to document component2

In BDB XML metadata names are of the form:

URI:name

where the URI. is some unique name that can be common to multiple metadata items, and the name is a name associated with the metadata. The combination of the URI and the name must represent a unique identifier for your container.

In the example, above, a URI is not used because a URI is optional so long as the name uniquely identifies the metadata within the container. If you wanted to use modifyuser for more than one type of metadata, then you would be required to provide a unique URI for both types of metadata.

Note that all metadata defined by BDB XML uses the dbxml URI. So, for example, all documents have metadata which identifies the document name. This metadata is defined by BDB XML, and it has the identifier: dbxml:name.

To query metadata, use the built-in extension function dbxml:metadata. For example:

dbxml> query '
collection("components.dbxml")/component[
dbxml:metadata("modifyuser")="john"]'

1 objects returned for eager expression '
collection("components.dbxml")/component[
dbxml:metadata("modifyuser")="john"]'

dbxml> print
<component number="1">
<uses-part>89</uses-part>
<uses-part>150</uses-part>
<uses-part>899</uses-part>
</component>

Notice how the metadata doesn't actually appear in the result document. The metadata is not part of the document; it exists only within the container and with respect to a particular document. If you retrieve the document from BDB XML and transfer it to another system, the metadata will not be included. This is useful when you need to preserve the original state of a document, but also want to track some additional information while it's stored within BDB XML.