The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

REST::Neo4p::Query - Execute Neo4j Cypher queries

SYNOPSIS

 REST::Neo4p->connect('http:/127.0.0.1:7474');
 $query = REST::Neo4p::Query->new('START n=node(0) RETURN n');
 $query->execute;
 $node = $query->fetch->[0];
 $node->relate_to($other_node, 'link');

DESCRIPTION

REST::Neo4p::Query encapsulates Neo4j Cypher language queries, executing them via REST::Neo4p::Agent and returning an iterator over the rows, in the spirit of DBI.

Streaming

execute() captures the Neo4j query response in a temp file. fetch() iterates over the JSON in the response using JSON::Streaming::Reader. So go ahead and make those 100 meg queries. The tempfile is unlinked after the iterator runs out of rows, or upon object destruction, which ever comes first.

Paths

If your query returns a path, fetch() returns a REST::Neo4p::Path object from which you can obtain the Nodes and Relationships.

Transactions

See "Transaction Support (Neo4p Server Version 2 only)" in REST::Neo4p.

NOTE: Rows returned from the Neo4j transaction endpoint are not completely specified database objects (see http://docs.neo4j.org/chunked/2.0.0-RC1/rest-api-transactional.html). Fetches on transactional queries will return an array of simple Perl structures (hashes and arrays) that correspond to the row as returned in JSON by the server, rather than as REST::Neo4p objects. This is regardless of the setting of the ResponseAsObjects attribute.

METHODS

new()
 $stmt = 'START n=node({node_id}) RETURN n';
 $query = REST::Neo4p::Query->new($stmt,{node_id => 1});

Create a new query object. First argument is the Cypher query (required). Second argument is a hashref of parameters (optional).

execute()
 $numrows = $query->execute;
 $numrows = $query->execute( param1 => 'value1', param2 => 'value2');
 $numrows = $query->execute( $param_hashref );

Execute the query on the server. Not supported in batch mode.

fetch()
fetchrow_arrayref()
 $query = REST::Neo4p::Query->new('START n=node(0) RETURN n, n.name');
 $query->execute;
 while ($row = $query->fetch) { 
   print 'It works!' if ($row->[0]->get_property('name') == $row->[1]);
 }

Fetch the next row of returned data (as an arrayref). Nodes are returned as REST::Neo4p::Node objects, relationships are returned as REST::Neo4p::Relationship objects, scalars are returned as-is.

err(), errstr()
  $query->execute;
  if ($query->err) {
    printf "status code: %d\n", $query->err;
    printf "error message: %s\n", $query->errstr;
  }

Returns the HTTP error code and Neo4j server error message if an error was encountered on execution.

err_list()
finish()
  while (my $row = $q->fetch) {
    if ($row->[0] eq 'What I needed') {
      $q->finish();
      last;
    }
  }

Call finish() to unlink the tempfile before all items have been fetched.

ATTRIBUTES

RaiseError
 $q->{RaiseError} = 1;

Set $query->{RaiseError} to die immediately (e.g., to catch the exception in an eval block).

ResponseAsObjects
 $q->{ResponseAsObjects} = 0;
 $row_as_plain_perl = $q->fetch;

If set to true (the default), query reponses are returned as REST::Neo4p objects. If false, nodes, relationships and paths are returned as simple perl structures. See "as_simple()" in REST::Neo4p::Node, "as_simple()" in REST::Neo4p::Relationship, "as_simple()" in REST::Neo4p::Path for details.

SEE ALSO

REST::Neo4p, REST::Neo4p::Path, REST::Neo4p::Agent.

AUTHOR

   Mark A. Jensen
   CPAN ID: MAJENSEN
   majensen -at- cpan -dot- org

LICENSE

Copyright (c) 2012-2014 Mark A. Jensen. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.