/ 
WWW-Metaweb-0.02
River stage zero No dependents
/ WWW::Metaweb

NAME

WWW::Metaweb - An interface to the Metaweb database via MQL

SYNOPSIS

  use strict;
  use WWW::Metaweb;

  my $mh = WWW::Metaweb->connect( username => $u,
				  password => $p, 
				  server => 'www.freebase.com',
				  auth_uri => '/api/account/login',
				  read_uri => '/api/service/mqlread',
				  write_uri => '/api/service/mqlwrite',
				  trans_uri => '/api/trans',
				  pretty_json => 1 );

  my $query = {
	  '/type/object/creator' => undef,
	  cover_appearances => [{
	    type => '/comic_books/comic_book_issue',
	    name => undef,
	    part_of_series => undef
	  }],
	  created_by => [],
	  id => undef,
	  name => 'Nico Minoru',
	  type => '/comic_books/comic_book_character'
  };

The easy way:

my $result = $mh->read($query, 'json');
print $result;

The complicated way:

$mh->add_query('read', $query);
$mh->send_envelope('read')
  or die $WWW::Metaweb::errstr;

my $result = $mh->result('read', 'json');
print $result . "\n";

ABSTRACT

WWW::Metaweb provides an interface to a Metaweb database through it's HTTP API and MQL.

DESCRIPTION

WWW::Metaweb provides an interface to a Metaweb database instance. The best example currently is Freebase (www.freebase.com). Queries to a Metaweb are made through HTTP requests to the Metaweb API.

Qeueries are written in the Metaweb Query Language (MQL), using Javascript Object Notation (JSON). WWW::Metaweb allows you to write the actual JSON string yourself or provide a Perl array ref / hash ref structure to be converted to JSON.

METHODS

Class methods

$version = WWW::Metaweb->version

Returns the version of WWW::Metaweb being used.

Constructors

$mh = WWW::Metaweb->connect( [option_key => 'option_value' ...] )

Returns a new WWW::Metaweb instance, a number of different attributes can be sethere (see below).

If a username and password are supplied then connect() will attempt to authenticate before returning. If this authentication fails then undef will be returned.

Metaweb parameters
auth_uri

The URI used to authenticate for this Metaweb (eg. /api/account/login).

read_uri

The URI used to submit a read MQL query to this Metaweb (eg. /api/service/mqlread).

write_uri

The URI used to submit a write MQL query to this Metaweb (eg. /api/service/mqlwrite).

trans_uri

The URI used to access the translation service for this Metaweb (eg. /api/trans). Please note this this URI does not include the actual translation, at this time these are raw, image_thumb and blurb.

JSON parameters
pretty_json

Determines whether the response to a JSON query is formatted nicely. This is just passed along to the JSON object as JSON::XS-new->pretty($mh->{pretty})>.

json_preprocessor

Can provide a reference to a sub-routine that pre-processes JSON queries, the sub-routine should expect one argument - the JSON query as a string and return the processed JSON query as a scalar.

Authentication

$mh->authenticate($username, $password)

Authenticates to the auth_uri using the supplied username and password. If the authentication is successful then the cookie is retained for future queries.

In the future this method may give the option to accept a cookie instead of username and password.

Easy Querying

@results = $mh->read($read_query [, $read_query2 ...] [, $format]) or $result = $mh->read($read_query [, $format])

The easy way to perform a read query.

Accepts one or more queries which are bundled up in one envelope and sent to the read service. The response is an array containing the results in the same order as the queries were given in.

If only one query is given and assigned to a scaler then the single query will be returned as a scaler instead of in an array.

@result = $mh->write($write_query [, $write_query2 ...] [, $format]) or $result = $mh->write($write_query [, $format])

The easy way to perform a write query.

The syntax and behaviour are exactly the same as read() (above).

Translation Service

$content = $mh->trans($translation, $guid)

Gets the content for a guid in the format specified by $translation. Metaweb currently supports the translations raw, image_thumb and blurb.

$translation is not checked for validity, but an error will most likely be returned by the server.

$guid should be the global identifier of a Metaweb object of type /common/image or /type/content and/or /common/document depending on the translation requested, if not the Metaweb will return an error. The global identifier can be prefixed with either a '#' or the URI escaped version '%23' then followed by the usual string of lower case hex.

$content = $mh->raw($guid)

Convenience method for getting a raw translation of the object with $guid. See trans() for more details.

$content = $mh->image_thumb($guid)

Convenience method for getting a image_thumb translation of the object with $guid. See trans() for more details.

$content = $mh->blurb($guid)

Convenience method for getting a blurb translation of the object with $guid. See trans() for more details.

Complicated Querying

$mh->add_query($method, query_name1 => $query1 [, query_name2 => $query2 [, ...]])

This method adds queries to a query envelope. $method must have a value of either 'read' or 'write'.

Each query must have a unique name, otherwise a new query will overwrite an old one. By the same token, if you wish to change a query in the query envelope, simply specify a new query with the old query name to overwrite the original.

A query may either be specified as a Perl structure, or as a JSON string. The first example below is a query as a Perl structure.

  $query_perl = {
	  name => "Nico Minoru",
	  id => undef,
	  type => [],
	  '/comic_books/comic_book_character/cover_appearances' => [{
		name => null  
	  }]
  };

The same query as a JSON string:

  $query_json = '
  {
	  "name":"Nico Minoru",
	  "id":null,
	  "type":[],
	  "/comic_books/comic_book_character/cover_appearances":[{
		  "name":null
	  }]
  }';

For the same of completeness this JSON query can be submitted the same way as in the query editor, a shortened version formatted like this is below:

  $query_json_ext = '
  {
	  "query":{
		  "name":"Nico Minoru",
		  "type":[]
	  }
  }';

Now we can add all three queries specified above to the envelope with one call.

$mh->add_query( query_perl => $query_perl, query_json => $query_json, query_json_ext => $query_json_ext );
$mh->clear_queries($method)

Clears all the previous queries from the envelope.

$method must be either 'read' or 'write'.

$count = $mh->query_count($method)

Returns the number of queries held in the $method query envelope.

$bool = $mh->check_query_syntax($method, $query)

Returns a boolean value to indicate whether the query provided (either as a Perl structure or a JSON string) follows correct MQL syntax. $method should be either 'read' or 'write' to indicate which syntax to check query against.

Note: This method has not yet been implemented, it will always return TRUE.

$http_was_successful = $mh->send_envelope($method)

Sends the current query envelope and returns whether the HTTP portion was successful. This does not indicate that the query itself was well formed or correct.

$method must be either 'read' or 'write'.

Query Convenience Methods (for complicated queries)

As most of the query and result methods require a $method argument as the first parameter, I've included methods to call them for each method explicitly.

If you know that you will always be using a method call for either a read or a write query/result, then it's safer to user these methods as you'll get a compile time error if you spell read or write incorrectly (eg. a typo), rather than a run time error.

Of course it's probably much easier to just use read() and write() from the "Easy Querying" section above.

$mh->add_read_query(query_name1 => $query1 [, query_name2 => $query2 [, ...]])

Convenience method to add a read query. See add_query() for details.

$mh->add_write_query(query_name1 => $query1 [, query_name2 => $query2 [, ...]])

Convenience method to add a write query. See add_query() for details.

$mh->clear_read_queries

Convenience method to clear the read envelope. See clear_queries() for details.

$mh->clear_write_queries

Convenience method to clear the write envelope. See clear_queries() for details.

$count = $mh->read_query_count

Convenience method, returns the number of queries in the read envelope. See query_count() for details.

$count = $mh->write_query_count

Convenience method, returns the number of queries in the write envelope. See query_count() for details.

$http_was_successful = $mh->send_read_envelope

Convenience method, sends the read envelope. See send_envelope() for details.

$http_was_successful = $mh->send_write_envelope

Convenience method, sends the write envelope. See send_envelope() for details.

Result manipulation (for complicated queries)

$mh->set_result($json)

Sets the result envelope up so that results can be accessed for the latest query. Any previous results are destroyed.

This method is mostly used internally.

$bool = $mh->result_is_ok($query_name)

Returns a boolean result indicating whether the query named $query_name returned a status ok. Returns undef if there is no result for query_name.

$mh->result($query_name [, $format])

Returns the result of query named $query_name in the format $format, which should be either 'perl' for a Perl structure or 'json' for a JSON string.

if $query_name is not defined then the default query name 'netmetawebquery' will be used instead.

If $format is not specified then the result is returned in the format the original query was supplied.

Following the previous example, we have three separate results stored, so let's get each of them out.

$result1 = $mh->result('query_perl');
$result2 = $mh->result('query_json');
$result3 = $mh->result('query_json_ext', 'perl');

The first two results will be returned in the format their matching queries were submitted in - Perl structure and JSON string respectively - the third will be returned as a Perl structure, as it has been explicitly asked for in that format.

Fetching a result does not effect it, so a result fetched in one format can be later fetched using another.

$text = $mh->raw_result

Returns the raw result from the last time an envelope was sent.

After a successful query this will most likely be a JSON structure consisting of the outer envelope with the code and status as well as a result for each query sent in the last batch.

After an unsuccessful query this will contain error messages detailing what went wrong as well as code and status sections to similar effect.

If the transaction itself failed then the returned text will probably be empty, but at the very least this method will always return an empty string, never undef.

Accessors

$ua = $mh->useragent or $mh->useragent($ua)

Gets or sets the LWP::UserAgent object which is used to communicate with the Metaweb. This method can be used to change the user agent settings (eg. $mh-useragent->timeout($seconds)>).

$host = $mh->server or $mh->server($new_host)

Gets or sets the host for this Metaweb (eg. www.freebase.com). No checking is currently done as to the validity of this host.

BUGS AND TODO

Still very much in development. I'm waiting to hear from you.

There is not query syntax checking - the method exists, but doesn't actually do anything.

If authentication fails not much notice is given.

More information needs to be given when a query fails.

I would like to implement transparent cursors in read queries so a single query can fetch as many results as exist (rather than the standard 100 limit).

ACKNOWLEDGEMENTS

While entirely rewritten, I think it's only fair to mention that the basis for the core of this code is the Perl example on Freebase (http://www.freebase.com/view/helptopic?id=%239202a8c04000641f800000000544e139).

Michael Jones has also been a great help - pointing out implementation issues and providing suggested fixes and code.

SEE ALSO

Freebase, Metaweb

AUTHORS

Hayden Stainsby <hds@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2007 by Hayden Stainsby

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