view release on metacpan or  search on metacpan

lib/LabKey/Query.pm  view on Meta::CPAN

#!/usr/bin/perl

=head1 NAME

LabKey::Query - For interacting with data in LabKey Server

=head1 SYNOPSIS

	use LabKey::Query;
	my $results = LabKey::Query::selectRows(
		-baseUrl => 'http://labkey.com:8080/labkey/',
		-containerPath => 'myFolder/',
		-schemaName => 'lists',
		-queryName => 'mid_tags',
	);
		
=head1 ABSTRACT

For interacting with data in LabKey Server

=head1 DESCRIPTION

This module is designed to simplify querying and manipulating data in LabKey Server.  It should more or less replicate the javascript APIs of the same names. 

After the module is installed, if you need to login with a specific user you 
will need to create a L<.netrc|https://www.labkey.org/Documentation/wiki-page.view?name=netrc>
file in the home directory of the user running the perl script.

In API versions 0.08 and later, you can specify the param '-loginAsGuest'
which will query the server without any credentials.  The server must permit 
guest to that folder for this to work though.

=cut

package LabKey::Query;

use warnings;
use strict;
use JSON;
use Data::Dumper;
use FileHandle;
use File::Spec;
use File::HomeDir;
use Carp;


# Force all SSL connections to use TLSv1 or greater protocol. This is required for 
# MacOSX and older Windows workstations.
# 
# Credit to @chrisrth on stackoverflow (http://stackoverflow.com/a/20305596)
# See https://www.labkey.org/issues/home/Developer/issues/details.view?issueId=22146
# for more information.
# 
use IO::Socket::SSL;
my $context = new IO::Socket::SSL::SSL_Context(
	SSL_version => 'tlsv1'
);
IO::Socket::SSL::set_default_context($context);

use LWP::UserAgent;
use HTTP::Cookies;
use HTTP::Request::Common;
use URI;


use vars qw($VERSION);

our $VERSION = "1.07";



=head1 FUNCTIONS

=head2 selectRows()

selectRows() can be used to query data from LabKey server

The following are the minimum required params:
		
	my $results = LabKey::Query::selectRows(
		-baseUrl => 'http://labkey.com:8080/labkey/',
		-containerPath => 'myFolder/',
		-schemaName => 'lists',
		-queryName => 'mid_tags',
	);

The following are optional:

	-viewName => 'view1',
	-filterArray => [
		['file_active', 'eq', 1], 
		['species', 'neq', 'zebra']
	], #allows filters to be applied to the query similar to the labkey Javascript API.
	-parameters => [
		['enddate', '2011/01/01'], 
		['totalDays', 15]
	], #allows parameters to be applied to the query similar to the labkey Javascript API.	
	-maxRows => 10	#the max number of rows returned
	-sort => 'ColumnA,ColumnB'	#sort order used for this query
	-offset => 100	#the offset used when running the query
	-columns => 'ColumnA,ColumnB'  #A comma-delimited list of column names to include in the results.
	-containerFilterName => 'currentAndSubfolders'
	-debug => 1,	#will result in a more verbose output
	-loginAsGuest => #will not attempt to lookup credentials in netrc
	-netrcFile => optional. the location of a file to use in place of a .netrc file.  see also the environment variable LABKEY_NETRC.
	-requiredVersion => 9.1 #if 8.3 is selected, it will use LabKey's pre-9.1 format for returning the data.  9.1 is the default.  See documentation of LABKEY.Query.ExtendedSelectRowsResults for more detail here:
		https://www.labkey.org/download/clientapi_docs/javascript-api/symbols/LABKEY.Query.html
	-useragent => an instance of LWP::UserAgent (if not provided, a new instance will be created)
	-timeout => timeout in seconds (used when creating a new LWP::UserAgent)
	
=head3 NOTE

In version 1.0 and later of the perl API, the default result format is 9.1.  This is different from the LabKey JS, which defaults to the earlier format for legacy purposes.

=cut

sub selectRows {
	my %args = @_;