NAME

RDF::AllegroGraph::Repository4 - AllegroGraph repository handle for AGv4

INTERFACE

Same as RDF::AllegroGraph::Repository from which we inherit.

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!

Methods (over those we inherit)

session (since v0.06)

$session = $repo->session

This method forks a session out of the current repository session. Unlike a transaction, all changes are autocommitted into the mother repository. But AG4 needs a separate connection thread for some specific features (SNA, loading Prolog knowledge, etc.)

transaction (since v0.06)

$tx = $repo->transaction

This method forks a transaction out of the current repository session. That transaction is itself a repository session (and a session, for that matter). Whatever you do in the transaction, will stay in the transaction. With calling the rollback method (see RDF::AllegroGraph::Transaction4), you will simply empty the transaction. That is also the default behaviour, if the transaction object goes out of scope.

To manifest any changes you will have to invoke commit on the transaction object.

blanks (since v0.06)

@blanks = $repo->blanks (int_amount)

This method asks the server to create a number of blank nodes in the repository. The ids of these nodes will be returned. By default, one node will be created, but you can ask for more.

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 URLs 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 existing content in the repository 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.

(Since v0.06): The object part can now be a range of values. You simply provide an array reference with the lower and the upper bound as values in the array, such as for example

$repo->match ([ undef, undef, [ '"1"^^my:type', '"10"^^my:type' ] ]);

NOTE: Subject range queries and predicate range queries are not supported as RDF would not allow literals at these places anyway.

(Since v0.06): For AGv4 there is now a way to configure some options when fetching matching triples: Simply provide as first parameter an options hash:

$repo->match ({ limit => 10 }, [ undef, .....]);

These options will apply to all passed in match patterns SEPARATELY, so that with several patterns you might well get more than your limit.

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)

In the case of TUPLE_LIST the result will be a sequence of (references to) arrays. All naming of the individual columns is hereby lost. TUPLE_LIST really only returns the data (and not the names within SELECT clause).

(since v0.08) NAMED_TUPLE_LIST also returns a hash with the names (list reference) and the result sequence (list reference, too).

INFERENCING (default: undef)

[Since v0.08] With this option you can control the degree of inferencing used with this query. By default, no inferencing is used, but if you pass in rdfs++, then the semantics of those properties mentioned in .../doc/agraph-introduction.html#reasoning are honored.

prolog (since v0.06)

See sparql, but this is only supported for AGv4 servers.

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 AllegroGraph environment is honored at the moment.

NOTE: My current understanding is that AG does NOT support namespaces when you load data with add() or replace(), or try to match it with match(). In that case, all URIs must be fully expanded. Namespaces seem to work with SPARQL queries, though.

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

spherical

$coord = $repo->spherical (undef, '5.2 degree');

This method registers a spherical coordinate system on the server.

NOTE: With this version, no region can be specified (so this is always a complete sphere) and only degrees are supported.

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

For cartesian coordinates you provide the bottom/left corner, and then the top/right one.

For spherical coordinates you provide the longitude/latitude of the bottom/left corner, then the longitude/latitude of the top/right one.

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.

For cartesian coordinates you simply provide the X/Y coordinates of the circle center, and the radius (in the unit as provided with the geotype.

For spherical coordinates the center is specified with a longitude/latitude pair. The radius is also interpreted along the provided geotype.

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

inPolygon (since v0.06)

@ss = $repo->inPolygon ($coordtype, $preduri, @points, { %options })

This method tries to identify all statements where the object is within a polygon defined by the points array. Each point is simply an array reference with 2 entries (x,y, of course).

The predicate URI defines which predicates should be considered. Do not leave it undef. The coordinate type is the one you will have generated before with cartesian.

The optional options can only contain limit to restrict the number of tuples to be returned.

For spherical coordinates make sure that you (a) provide longitude/latitude pairs and then that the polygon is built clockwise.

NOTE: This is a somewhat expensive operation in terms of communication round-trips.

valid_indices

This method will return a list of indices which the repository on the server understands. The list contains strings of the form spogi which identify the bias of the index. See "/www.franz.com/agraph/support/documentation/v4/python-tutorial/python-tutorial-40.html#Creating a Repository" in http: for some introduction.

NOTE: These are NOT the indices which are active for that repository. See indices for that.

indices

@idxs = $rep->indices ([ change list ])

This method always returns the current list of applied indices for that repository.

Optionally you can pass in a list of changes you want in terms of indices, changes in terms of indices you want to add, or to remove. To add, say, a spogi index you would prefix it with a '+':

$rep->indices ('+spogi')

You can provide any number of such additions. In the same way you would a prefixed '-' to indicate that you want an index to be deleted.

bulk_loading_mode

$bool = $repo->bulk_loading_mode (1|0)

This method switches on and off the bulk loading capability of the repository. To enable it, pass in 1, to turn it off pass in 0. In any case the current state is returned where undef is returned instead of 0.

commit_mode

$bool = $repo->commit_mode (1|0)

Method to control the commit mode of a repository. Parameters and return values are like those for bulk_loading_mode.

duplicate_suppression_mode

$bool = $repo->duplicate_suppression_mode (1|0)

Method to control the duplicate suppression behavior of a repository. Parameters and return values are like those for bulk_loading_mode.