NAME

Data::TagDB - Work with Tag databases

VERSION

version v0.08

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.

Note: Future versions of this module will depend on Data::Identifier.

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.

If a open handle is passed, the same restrictions apply as for "dbh".

dbh

my $dbh = $db->dbh;

Returns the current DBI connection.

This connection can be used to call any transaction independent method on the handle. It can for example be used to call "ping" in DBI to keep the connection alive.

If methods are called that depend on the state of the transaction logic (such as performing an SELECT or UPDATE) the state of the transaction must be managed via this module. See </begin_work>.

The same holds true for any open handle passed to "new". When passed the handle must not be in any active transaction and must not be used outside this module to change the transaction state of the handle.

It is also wise to avoid interacting with the tables managed by this module. This may result in the internal states being in a wrong state. It is however generally safe (but for the restrictions given above) to interact with tables outside of the use of this module.

As table names that are in use by this module depend on the version of the schema that is currently active (and may change in future) it is most wise to have any custom tables in a seperate namespace of some kind (the exact ways to do this may depend on the type of database used).

disconnect

$db->disconnect

This 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.

tag_by_specification

my Data::TagDB::Tag $tag = $db->tag_by_specification($specification, style => $style [, %opts ]);

Gets a tag by specification according to a style. This method is mostly useful to parse user input and find the corresponding tag.

Note: This method is experimental. It may change prototype, and behaviour or may be removed in future versions without warning. Role matching depends on "cloudlet" in Data::TagDB::Tag and is subject to its status.

The following styles are supported:

ise

The given specification is an UUID, OID, or URI.

tagpool

The given specification is in tagpool format. Both type@tag and tag! notation is supported (can also be mixed freely).

Parsing interacts with options the same way as tagpool does.

sirtx

The given specification is in SIRTX format. Currently only *local, 'number, logical, and type:id formats are supported. There is very limited support for &port. Bracket-escape is only supported for top level.

Supports the options sirtx_local_ids, and sirtx_ports.

The following (all optional) options are supported:

as_is

If true, this disables special parsing rules. For style tagpool it disables all parsing but the check for UUIDs.

important

Requires the tag to be marked important.

role

A role the tag is required to have.

sirtx_local_ids

An hashref with the local id (without the *) as key and Data::TagDB::Tag as value.

sirtx_ports

An arrayref with an even number of elements (key-value pairs). Elements with an even index are considered the key (port). They are followed by the corresponding (port) value.

All elements must be an instance of Data::TagDB::Tag.

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.

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.

begin_work, commit, rollback

$db->begin_work;
# ...
$db->commit;
# or:
$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.

Note: For each call to begin_work there must be a matching call to commit or rollback. This is important as this API will keep track of transactions internally.

Note: A call to begin_work may or may not fail if another transaction is already in process. This may depend on the type of database used.

Note: The return value of those methods is undefined. On error they will die.

Note: These methods are mutually exclusive with the use of "in_transaction" at this time. However, the use of "in_transaction" is recommended.

For details see also: "begin_work" in DBI, "commit" in DBI, "rollback" in DBI.

in_transaction

$db->in_transaction(ro => sub { ....});
# or:
$db->in_transaction(rw => sub { ....});

Runs a block of code (a subref) inside a transaction.

The passed block is run in a transaction. The transaction is commited after the code finishes.

The type of the transaction can be ro (read only) or rw (read-write). The module may optimise based on this information. If a write operation is performed in a transaction that is marked ro the behaviour is unspecified.

In contrast to "begin_work" and "commit" calls to this method can be stacked freely. For example the following is valid:

$db->in_transaction(ro => sub {
    # do some read...
    $db->in_transaction(rw => sub {
        # do some write...
    });
    # do more reading, writing is invalid here
});

Note: If the code dies the error is ignored. The transaction is still commited. If the code wants to perform rollback in case it fails this function might not be the one to use.

Note: Data written might only be visible to other handles of the same database once all transactions have been finished.

Note: This method is mutually exclusive with the use of "begin_work" at this time.

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 is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)

To install Data::TagDB, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Data::TagDB

CPAN shell

perl -MCPAN -e shell
install Data::TagDB

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)