NAME
Data::TagDB - Work with Tag databases
VERSION
version v0.06
SYNOPSIS
use Data::TagDB;
my $db = Data::TagDB->new($dsn, ...);
# or:
my $db = Data::TagDB->new($dbh);
# Create new database:
use Data::TagDB::Migration;
my Data::TagDB $db = Data::TagDB::Migration->create(...);This module implements SQL based universal tag databases. Such databases can be used to store any kind of (semantic) data.
This module and it's submodule implement creation of databases, migration (to most current scheme), adding data and reading data from the database.
For an introduction see Data::TagDB::Tutorial.
The instances of Data::TagDB::Tag repesent any kind of object (may it be file, user account or a real life object like a tree). It provides some convenience functions such as to query objects for their name.
Data::TagDB::Factory (via "factory") is provided for easy creation of new tags.
Note: Correct transaction management can improve performance significantly. Sometimes the improvement can be by a factor of a few thousand. Applications should therefore consider to group requests into transactions. This is also true for ready only requests.
METHODS
new
my $db = Data::TagDB->new($dsn, ...);
# or:
my $db = Data::TagDB->new($dbh);Returns a new object that can be used for lookups. Either an already connected DBI handle can be passed or data source that is then passed to "connect" in DBI internally.
dbh
my $dbh = $db->dbh;Returns the current DBI connection.
disconnect
$db->disconnectThis disconnects from the database backend. It also renders this object useless.
tag_by_id
my Data::TagDB::Tag $tag = $db->tag_by_id($type => $id);
# or:
my Data::TagDB::Tag $tag = $db->tag_by_id($hint => $id);
# or:
my Data::Identifier $id = ...;
my Data::TagDB::Tag $tag = $db->tag_by_id($id);
# e.g:
my Data::TagDB::Tag $tag = $db->tag_by_id(uuid => 'abc...');Gets a tag by an an identifier of the provided type. The type must be a Data::TagDB::Tag or a a string that is a valid hint.
If only argument is provided the argument must be an instance of Data::Identifier.
relation
my Data::TagDB::Iterator $iter = $db->relation(...);Returns an iterator for relations. The following keys can be used to filter the list. All must be Data::TagDB::Tag or an array ref of them objects: tag, relation, context, filter, and related. Each may be prefixed with no_ for negative filtering.
metadata
my Data::TagDB::Iterator $iter = $db->metadata(...);Returns an iterator for relations. The following keys can be used to filter the list. All must be Data::TagDB::Tag or an array ref of them objects: tag, relation, context, type, and encoding. Each may be prefixed with no_ for negative filtering.
Additionally data_raw can be used to filter for a data value.
link
my Data::TagDB::Iterator $iter = $db->link(...);This combines "relation", and "metadata". An iterator is returned that lists both metadata, and relations (in any order). The common subset of filters can be used. Namely: tag, relation, and context.
wk
my Data::TagDB::WellKnown $tag = $db->wk;
my Data::TagDB::Tag $tag = $wk->...;
# e.g.:
my Data::TagDB::Tag $asi = $db->wk->also_shares_identifier;Returns a dictionary of well known tags.
register_decoder
$db->register_decoder($type, $encoding, sub { ... });Registers a decoder for a given type and encoding. Both $type, and $encoding must be Data::TagDB::Tag.
create_tag
my Data::TagDB::Tag $tag = $db->create_tag([$type => $value, ...], [$type => $value, ...]);
# or:
my Data::Identifier $id = ...;
my Data::Identifier $extra = ...;
my Data::TagDB::Tag $tag = $db->create_tag($id, [ $extra ]);Create a tag (or return it if it already exists). Takes two lists if type-identifier pairs. The first list is the list of identifiers that uniquely identify the tag (e.g. an UUID). The second list contains additional, non unique identifiers (e.g. tagnames) and is optional.
If the tag does not exist it is created. Once it exists all identifiers added (for already existing tags missing identifiers are added).
Each list can be replaced by a single instance of Data::Identifier.
create_metadata
my Data::TagDB::Metadata $metadata = $db->create_metadata(
tag => $tag, # required
relation => $relation, # required
context => $context,
type => $type,
encoding => $encoding,
data_raw => $raw, # required
);Create a metadata entry if it does not yet exist. Returns it once created.
create_relation
my Data::TagDB::Relation $relation = $db->create_relation(
tag => $tag, # required
relation => $relation, # required
related => $related, # required
context => $context,
filter => $filter,
);Creates a relation (if it does not yet exist) and returns it.
create_cache
my Data::TagDB::Cache $cache = $db->create_cache;Create a new cache object every time this is called. Cache objects can be used to speed up processing. See Data::TagDB::Cache for details.
migration
$db->migration->upgrade;Get a migration object. This is mostly used for upgrading the database schema to the current one. It is recommended to perform upgrades for long running processes. For short running processes this can increase the startup time.
See also Data::TagDB::Migration.
factory
my Data::TagDB::Factory $factory = $db->factory;Get a factory object used to create tags. See also Data::TagDB::Factory for details.
exporter
my Data::TagDB::Exporter $exporter = $db->exporter($target, %opts);Create a new exporter. $target must be a open file handle (that supports seeking) or a filename.
The following options (all optional) are defined:
format-
The format to use. This can be Data::TagDB::Tag, a Data::Identfier, or a raw ISE string.
The default is tagpool-source-format (
e5da6a39-46d5-48a9-b174-5c26008e208e).
begin_work, commit, rollback
my $rc = $db->begin_work;
# ...
my $rc = $db->commit;
# or:
my $rc = $db->rollback;Those methods are provided as proxy to DBI's. The correct use of transactions can improve the speed (both for reading and writing) significantly. Specifically tag databases are subject to many improvements of correct transaction mangement.
For details see also: "begin_work" in DBI, "commit" in DBI, "rollback" in DBI.
tag_by_hint
my Data::TagDB::Tag $tag = $db->tag_by_hint($hint);Get a tag by hint. What hints are supported depends on what is stored in the database's hint table.
AUTHOR
Löwenfelsen UG (haftungsbeschränkt) <support@loewenfelsen.net>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2024 by Löwenfelsen UG (haftungsbeschränkt) <support@loewenfelsen.net>.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)