view release on metacpan or  search on metacpan

lib/Data/TagDB/Tutorial.pod  view on Meta::CPAN

=head2 Tags

A tag (in universal tags) represents any kind of subject. Most tags fall into one of two categories:
I<abstract> and I<specific>.

I<Abstract> tags are generally concepts like "tree" or "colour".
I<Specific> tags represent instances of those. For example the planet Earth, the tree in front of the building, or the file containing yesterday's work.

Tags itself do not hold any data. All data is stored in I<links>.

See also
L<Data::TagDB::Tutorial::Conventions>,
L<Data::TagDB::Tutorial::WellKnown>.

=head2 Links

I<Links> store the data in database. There are two types of links: I<relations> and I<metadata>.

=head3 Relations

I<Relations> provide a relation between two tags. An example would be "The colour of the house is blue.".
In this case the relation consists of three parts:
The I<tag> they are applied to ("the house"),
the I<relation> that connects both tags ("the colour is"),
and the I<related> tag that is applied ("blue").

B<Note:>
Each I<link> (and therefore also each I<relation>) as a property I<tag> and I<relation>.
This double use of terms can cause confusion.

B<Note:>
All parts of a relation are tags. Non of it's properties are special.

In addition each relation also includes a I<context> and I<filter>.

The I<context> is used to provide a scope in which the link is valid. For example a context could be "English", or "the 90s".
If the I<context> is C<undef> the link is valid without any restrictions.

The I<filter> provides a way to limit the scope to which a relation is applied to. This is only used by special relations.
Therefore the I<filter> property is virtually always C<undef>.

=head3 Metadata

I<Metadata> are considered degenerated I<relations>. They provide additional information about a tag like I<relations>, however
they do not point to a I<related> tag but to raw data.

The I<related> property is replaced by three new properties: I<type>, I<encoding>, and I<data>.

I<data> provides a raw bit string while I<type> and I<encoding> define how the bit string is to be understood.
I<type> defines the type of data that is stored. For example "string" or "integer".
I<encoding> defines the way the value of the given type is stored. For example "ASCII digits" or "32 bit unsigned integer".

B<Note:>
Both I<type> and I<encoding> are often C<undef>.
If they are C<undef> the default values are used. A I<relation> can define a default type,
and a I<type> can define a default encoding.

B<Note:>
L<Data::TagDB> and L<Data::TagDB::Metadata> use the property C<data_raw> for the raw bitstring that is stored in the relation.
The virtual member I<data> is added that contains a decoded copy of C<data_raw>.

Beside I<type>, I<encoding>, and I<data> metadata has the same I<tag>, I<relation>, and I<context> properties as relations.
I<filter> is always C<undef> for I<metadata> and skipped in the API.

=head2 Identifiers

To allow tags to be recalled L</Metadata> is set on them containing I<identifiers>.
This is done using the standard tag C<also-shares-identifier> as I<relation>.
The I<type> is set to the corresponding type of the identifier.

B<Note:>
L<Data::TagDB> implements helper functions. It is generally not needed to interact with identifiers on the
link level. However it is critical to have some basic understanding.

Identifiers may or may not be globally unique (the identifier is not never reused, not even in other databases).
An example for globally unique identifiers are UUIDs. An example for non-unique identifiers are tag names.

Any locally unique (never reused in the same database, but may be used in other databases) identifier
must have I<context> set to the context to which they are unique.
Examples of such locally unique identifiers are are classic numeric primary keys as common in SQL based databases.

B<Note:>
Locally unique identifiers are dissuaded for reasons of their added complexity. They are also prone to incorrect implementations.

B<Note:>
Non-unique identifiers may have I<context> set. This can for example be used to define tag names in multiple languages.

B<Recommendation:>
It is strongly recommended to use a new random UUID for new tags as a globally unique identifier.
(Tags generated using a generator have an UUID already set. See L<Data::TagDB::Factory> for details.)
While L<Data::TagDB> does not require a UUID to be set other software may.
It is also recommended to set a tag name.
If the name of the tag is subject to translation it is recommended to set it with the I<context> set
to C<default-context>.

=head1 Database connection

=head2 Database creation

To use a database it must be opened first. If it does not yet exist it needs to be created.
Creating a database also opens it. To do this you need the migrations module:

    use Data::TagDB::Migration;
    my Data::TagDB $db = Data::TagDB::Migration->create(...);

For example:

    my Data::TagDB $db = Data::TagDB::Migration->create('dbi:SQLite:dbname=MyDB.sqlite3');

After you initially created a database it is good to import some basic data.
This is used to provide structure to the database. The easiest way to do is using the migration module again like this:

    $db->migration->include(qw(Data::TagDB::WellKnown ...));

L<Data::TagDB::Migration/include> allows importing data known by other modules. See it's documentation for what it can include.
It is however recommended to at least include from L<Data::TagDB::WellKnown> as this enables all features supported by L<Data::TagDB>.

After the database is set up the handle can be used normally.

=head2 Opening and closing a database