view release on metacpan or  search on metacpan

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

A common example is to query the tag for it's I<displayname>.
The I<displayname> is often used when the tag needs to be displayed to a user.

A common call will look like:

    my $displayname = $tag->displayname;

The function always returns a string. (See L<Data::TagDB::Tag/displayname>)

Those basic getters may also cache the result for speed.
They also often employ relative complex rules.
For example the displayname getter will try different values (like title, name) to find the result.
And if none is found it will fall back to some alternatives (such as any identifier).

=head2 Individual queries

To perform individual queries you can all L<Data::TagDB/relation>, L<Data::TagDB/metadata>, or L<Data::TagDB/link>.
These functions are similar to a C<SELECT> on an SQL based database.
They take a list of query parameters to filter the result. An L<Data::TagDB::Iterator> is then returned with the results.

A common call looks like:

    my Data::TagDB::Iterator $iter = $db->relation(tag => $tag, relation => $db->wk->also_list_contains_also);

This will list the content of C<$tag> if C<$tag> is a list.

The list will contain elements of L<Data::TagDB::Relation>. If we want all tags that are contained we find them in the related property.

We can collect them into an array like this:

    my @list = $iter->collect('related');

This however will force all entries to be loaded into memory. It may be better to do:

    $iter->foreach(sub {
        my ($entry) = @_;
        my Data::TagDB::Tag $member_tag = $entry->related;
        # ...
    });

=head1 Performance

There are two main ways to improve performance. Caching and transactions.

=head2 Transactions

Transactions improve the by the database not needing to lock and unlock constantly.
This is mostly noticeable for write operations but is also valid for reading.

To support transactions L<Data::TagDB/begin_work>, L<Data::TagDB/commit>, and L<Data::TagDB/rollback> are provided.
They are proxy methods for L<DBI/begin_work>, L<DBI/commit>, and L<DBI/rollback>.

=head2 Caching

Caches can be used to keep tags instances from being destroyed.
This is done by first creating a new cache:

    my Data::TagDB::Cache $cache = $db->create_cache;

And then adding any tags to keep them alive:

    $cache->add($tag0, $tag1, ...);

You can have any amount of caches. E.g. if the the software uses a single database connection but handles multiple requests one could
have one global cache to cache the most relevant tags, and one per request cache to cache tags relevant to the request.

One the cache is destroyed, the tags will also be released (unless otherwise in use or hold by another cache).

=head1 AUTHOR

Philipp Schafft <lion@cpan.org>

=head1 COPYRIGHT AND LICENSE

This software is Copyright (c) 2024-2025 by Philipp Schafft <lion@cpan.org>.

This is free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)

=cut