NAME

RDF::AllegroGraph::Repository - AllegroGraph repository handle

DESCRIPTION

An AllegroGraph repository corresponds to an RDF model. Into such a model you can park RDF information, either as individual statements or via file bulk loading. Then you can navigate through it on a statement level, or query that model.

INTERFACE

Constructor

The constructor expects the following fields:

CATALOG (mandatory)

This is the handle to the catalog the repository belongs to.

id (mandatory)

This identifier is always of the form /whatever.

Example:

my $repo = new RDF::AllegroGraph::Repository (CATALOG => $cat, id => '/whereever');

Methods

id

This read-only accessor method returns the id of the repository.

disband

$repo->disband

This method removes the repository from the server. The object cannot be used after that, obviously.

size

$nr_triples = $repo->size

Returns the size of the repository in terms of the number of triples.

NOTE: As of time of writing, AllegroGraph counts duplicate triples!

add

$repo->add ('file://....', ...)

$repo->add ('http://....', ...)

$repo->add (' triples in N3 ', ...)

$repo->add ([ $subj_uri, $pred_uri, $obj_uri ], ...)

This method adds triples to the repository. The information can be provided in any of the following ways (also mixed):

file, HTTP, FTP URL

If a string looks like an URL, it will be dereferenced, the contents of the resource consulted and that shipped to the repository on the server. If the resource cannot be read, an exception Could not open will be raised. Any number of these URL can be provided as parameter.

NOTE: Only N3 files are supported, and also only when the URL ends with the extension nt or n3.

N3 triple string

If the string looks like N3 notated triples, that content is shipped to the server.

ARRAY reference

The reference is interpreted as one triple (statement), containing 3 URIs. These will be shipped as-is to the server.

If the server chokes on any of the above, an exception protocol error is raised.

NOTE: There are no precautions for over-large content. Yet.

NOTE: Named graphs (aka contexts) are not handled. Yet.

replace

This method behaves exactly like add, except that any content is wiped before adding anything.

delete

$repo->delete ([ $subj_uri, $pred_uri, $obj_uri ], ...)

This method removes the passed in triples from the repository. In that process, any combination of the subject URI, the predicate or the object URI can be left undef. That is interpreted as wildcard which matches anything.

Example: This deletes anything where the Stephansdom is the subject:

$air->delete ([ '<urn:x-air:stephansdom>', undef, undef ])

match

@stmts = $repo->match ([ $subj_uri, $pred_uri, $obj_uri ], ...)

This method returns a list of all statements which match one of the triples provided as parameter. Any undef as URI within such a triple is interpreted as wildcard, matching any other URI.

sparql

@tuples = $repo->sparql ('SELECT ...')

@tuples = $repo->sparql ('SELECT ...' [, $option => $value ])

This method takes a SPARQL query string and returns a list of tuples which the query produced from the repository.

NOTE: At the moment only SELECT queries are supported.

As additional options are accepted:

RETURN (default: TUPLE_LIST)

The result will be a sequence of (references to) arrays. All naming of the individual columns is currently lost.

Namespace Support

namespaces

%ns = $repo->namespaces

This read-only function returns a hash containing the namespaces: keys are the prefixes, values are the namespace URIs.

NOTE: No environment is honored at the moment.

namespace

$uri = $repo->namespace ($prefix)

$uri = $repo->namespace ($prefix => $uri)

$repo->namespace ($prefix => undef)

This method fetches, sets and deletes prefix/uri namespaces. If only the prefix is given, it will look up the namespace URI. If the URI is provided as second parameter, it will set/overwrite that prefix. If the second parameter is undef, it will delete the namespace associated with it.

NOTE: No environment is honored at the moment.

GeoSpatial Support

geotypes

@geotypes = $repo->geotypes

This method returns a list of existing geotypes (in form of specially crafted URIs). You need these URIs when you want to create locations for them, or when you want to retrieve tuples within a specific area (based on the geotype).

cartesian

$uri = $repo->cartesian ("100x100", $stripWidth);

$uri = $repo->cartesian ("100x100+10+10", $stripWidth);

$uri = $repo->cartesian ($minx, $miny, $maxx, $maxy, $stripWidth);

This method registers one new coordinate system at the server. The returned URI is later used as reference to that system. The extensions of the system is provided either

in the form WxH+X+Y

All numbers being floats. The X,Y offset part can be omitted.

or, alternatively, as minx, miny, maxx, maxy quadruple

Again all numbers being floats.

The last parameter defines the resolution of the stripes, and gives the server optimization hints. (See the general AG description for a deep explanation.)

inBox

@ss = $repo->inBox ($geotype, $predicate, 35, 35, 65, 65, { limit => 10 });

This method tries to find all triples which lie within a certain bounding box.

The geotype is the one you create with cartesian or spheric. The bounding box is given by the bottom/left and the top/right corner coordinates. The optional limit restricts the number of triples you request.

inCircle

@ss = $repo->inCircle ($geotype, $predicate, 35, 35, 10, { limit => 10 });

This method tries to find all triples which lie within a certain bounding circle.

The geotype is the one you create with cartesian or spheric. The bounding circle is given by the center and the radius. The optional limit restricts the number of triples you request.

NOTE: As it seems the circle MUST be within the range you specified for your geotype. Otherwise AG will return 0 tuples.

AUTHOR

Robert Barta, <rho at devc.at>

COPYRIGHT & LICENSE

Copyright 20(09|10) Robert Barta, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

RDF::AllegroGraph