NAME
WWW::Metaweb - An interface to the Metaweb database via MQL
SYNOPSIS
use strict;
use WWW::Metaweb;
my $mh = WWW::Metaweb->new( 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 = {
name => 'Nico Minoru',
id => undef,
type => [],
'/comic_books/comic_book_character/cover_appearances' => [{
name => undef,
id => undef,
}]
};
$mh->add_query('read', $query);
$mh->send_envelope('read')
or die $WWW::Metaweb::errstr;
my $result = $mh->result('read', 'json');
print $result . "\n";ABSTRACT
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
Constructors
$mh = WWW::Metaweb->connect(username => $u, password => $p [, option_key => 'option_value'])
While this method no longer requires a username and password, if they are supplied by are incorrect (or Metaweb can't authenticate for any other reason) then undef will be returned.
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.
Query manipulation
$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.
$obj = $mh->perl_query($query)
Forces a query into a Perl structure if it's a JSON string. If given a Perl structure it is left more or less alone.
$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
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.
$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
$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.
Translations
$content = $mh->trans($translation, $guid)
Gets the content for a guid in the format specified by $translation. WWW::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.
Accessors
$ua = $mh->useragent =head3 $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 =head3 $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.
ATTRIBUTES
The following attributes can be set manually by the programmer.
WWW::Metaweb set-up
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.
Formatting
pretty_json
Determines whether the response to a JSON query is formatted nicely. This is just passed along to the JSON object as JSON-new(pretty => $mh->{pretty})>.
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).
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.