File Coverage

blib/lib/Neo4j/Bolt/ResultStream.pm

Criterion	Covered	Total	%
statement	5	21	23.8
branch	0	2	0.0
condition			n/a
subroutine	1	11	9.0
pod	10	10	100.0
total	16	44	36.3

package Neo4j::Bolt::ResultStream;
# use Neo4j::Client;

BEGIN {
  our $VERSION = "0.4203";
  require Neo4j::Bolt::Cxn;
  require Neo4j::Bolt::CResultStream;
  require XSLoader;
  XSLoader::load();
}

sub fetch_next { shift->fetch_next_ }
sub nfields { shift->nfields_ }
sub field_names { shift->fieldnames_ }
sub success { shift->success_ }
sub failure { shift->failure_ }
sub client_errnum { shift-> client_errnum_ }
sub client_errmsg { shift-> client_errmsg_ }
sub server_errmsg { shift-> server_errmsg_ }
sub server_errcode { shift-> server_errcode_ }

sub update_counts {
  my $self = shift;
  my %uc;
  my @tags = qw/nodes_created nodes_deleted
		relationships_created relationships_deleted
		properties_set
		labels_added labels_removed
		indexes_added indexes_removed
		constraints_added constraints_removed/;
  my @vals = $self->update_counts_;
  return unless @vals;
  @uc{@tags} = @vals;
  return \%uc;
}

=head1 NAME

Neo4j::Bolt::ResultStream - Iterator on Neo4j Bolt query response

=head1 SYNOPSIS

 use Neo4j::Bolt;
 $cxn = Neo4j::Bolt->connect("bolt://localhost:7687");

 $stream = $cxn->run_query(
   "MATCH (a) RETURN labels(a) as lbls, count(a) as ct"
 );
 while ( my @row = $stream->fetch_next ) {
   print "For label set [".join(',',@{$row[0]})."] there are $row[1] nodes.\n";
 }
 # check that the stream emptied cleanly...
 unless ( $stream->success ) {
   print STDERR "Uh oh: ".($stream->client_errmsg || $stream->server_errmsg);
 }

=head1 DESCRIPTION

L objects are created by a successful query
performed on a L. They are iterated to obtain the rows
of the response as Perl arrays (not arrayrefs).

=head1 METHODS

=over

=item fetch_next()

Obtain the next row of results as an array. Returns false when done.

=item update_counts()

If a write query is successful, returns a hashref containing the
numbers of items created or removed in the query. The keys indicate
the items, as follows:

 nodes_created
 nodes_deleted
 relationships_created
 relationships_deleted
 properties_set
 labels_added
 labels_removed
 indexes_added
 indexes_removed
 constraints_added
 constraints_removed

If query is unsuccessful, or the stream is not completely fetched yet,
returns undef (check L).

=item field_names()

Obtain the column names of the response as an array (not arrayref).

=item nfields()

Obtain the number of fields in the response row as an integer.

=item success(), failure()

Use these to check whether fetch_next() succeeded. They indicate the
current error state of the result stream. If

  $stream->success == $stream->failure == -1

then the stream has been exhausted.

=item client_errnum()

=item client_errmsg()

=item server_errcode()

=item server_errmsg()

If C<$stream-Esuccess> is false, these will indicate what happened.

If the error occurred within the C code,
C will provide the C and C
the associated error message. This is a probably a good time to file a
bug report.

If the error occurred at the server, C and
C will contain information sent by the server. In
particular, Cypher syntax errors will appear here.

=item result_count_()

=item available_after()

=item consumed_after()

These are performance numbers that the server provides after the
stream has been fetched out. result_count_() is the number of rows
returned, available_after() is the time in ms it took the server to
provide the stream, and consumed_after() is the time it took the
client (you) to pull them all.

=back

=head1 LIMITATIONS

The results of Cypher C or C queries are
currently unsupported. If you need to access such results,
consider using L or the interactive
L
instead of this module.

=head1 SEE ALSO

L, L.

=head1 AUTHOR

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

=head1 LICENSE

This software is Copyright (c) 2019-2021 by Mark A. Jensen.

This is free software, licensed under:

  The Apache License, Version 2.0, January 2004

=cut

1;