/ 
Metaweb-0.05
River stage zero No dependents
/ Metaweb

NAME

Metaweb - Perl interface to the Metaweb/Freebase API

VERSION

Version 0.05

SYNOPSIS

  use Metaweb;

  my $mw = Metaweb->new({
      username => $username,
      password => $password
  });
  $mw->login();

my $result = $mw->query({
    name => 'my_query',
    query => \%query,
});

DESCRIPTION

This is a Perl interface to the Metaweb database, best known through the application Freebase (http://freebase.com).

If this is your first encounter with Metaweb/Freebase, chances are you're confused about what the two terms mean. In short, Metaweb is the underlying database technology and Freebase is large, well-known application that runs on it. For comparison, consider Mediawiki (software) and Wikipedia (website and data collection).

This means that you can use this Metaweb module to talk to Freebase or - in future - any other website built on the Metaweb platform.

The Metaweb Query Language (MQL) is based on JSON and query-by-example. The MQL and API documentation can be found on the Freebase website in the developers' area. There is also an online Query Editor tool, with many examples of MQL, at http://www.freebase.com/view/queryeditor/

This CPAN module provides you with everything you need to build an application around Freebase or any other Metaweb database. It also provides a command line client ('metaweb') for playing around with MQL.

IMPORTANT NOTES

Alpha release

Freebase is currently in alpha release, with world-readable data but requiring an invitation and login to be able to update/write data.

This module is very much alpha code. It has lots of stuff not implemented and will undergo significant changes. Breakage may occur between versions, so consider yourself warned.

TMTOWTDI

Also note that Hayden Stainsby is working on a different Metaweb module called WWW::Metaweb. There's more than one way to do it. I encourage you to check out both modules and provide feedback/suggestions to both of us, either directly or via the Freebase developers' mailing list.

FUNCTIONS

new()

Instantiate a Metaweb client object. Takes various options including:

username

The username to login with

password

The password to login with

server

The server address

read_path

The URL path of the read service, relative to the server address

write_path

The URL path of the write service, relative to the server address

login_path

The URL path of the login service, relative to the server address

None of these are actually required; the server and path options default to Freebase's, and the username/login are only required for write access. Therefore, if you only want to read from Freebase, all you need is:

my $mw = Metaweb->new();

login()

Perform a login to the Metaweb server and pick up the necessary cookie. Uses the username/password details provided to the constructor method, or via the appropriately named accessor methods (see below).

query()

Perform a MQL query. You must provide a name and a query hash as arguments:

my $result = $mw->query({
    name => 'my_query',
    query => { type => 'person', name => undef } # all people!
});

The query is a a Perl data structure that's converted to JSON using the JSON::XS module's to_json() method. The MQL envelope will automatically be put around the query, using the name you provide.

Currently this method only supports "read" queries. If you want to write/upload, use json_query().

The results of this method are returned as a Perl data structure (or undef on failure); the following attributes are also set for diagnostic purposes.

raw_query

The raw JSON used in the query.

raw_result

The raw JSON returned.

err_code

Error code (only used if an error occurs).

err_message

Error message (only used if an error occurs).

See the accessor methods (below) for how to access all these attributes.

json_query

This method sends and receives raw JSON to the Metaweb API.

Arguments are passed as a hashref and include:

type

May be "read", "write", or "update". Default is "read".

query

The query in JSON format. You are expected to send the full JSON, including the envelope.

The raw JSON is returned. No parsing whatsoever is done.

raw_query and raw_result() are set as a side effect, same as for query(), but err_code() and err_message are *not* set, as we'd need to parse the JSON to get at it and the whole point of this is that it's unparsed.

ACCESSOR METHODS

You probably won't need these much in day-to-day use, but they're here for you if you want them.

username()

Get/set default login username.

password()

Get/set default login password.

server()

Get/set server to login to. Defaults to 'http://www.freebase.com'.

login_path()

Get/set the URL to login to, relative to the server. Defaults to '/api/account/login'.

read_path()

Get/set the URL to perform read queries, relative to the server. Defaults to '/api/service/mqlread'.

write_path()

Get/set the URL to perform write queries, relative to the server. Defaults to '/api/service/mqlwrite'.

raw_query()

The raw JSON of the last query made. This is set by both query() and json_query().

raw_result()

The raw JSON from the response. This is set by both query() and json_query().

err_code()

Set on error by query(). json_query() doesn't set this; you need to parse the JSON yourself.

err_message()

Set on error by query(). json_query() doesn't set this; you need to parse the JSON yourself.

SEE ALSO

JSON, metaweb (command line client), WWW::Metaweb (alternative interface).

AUTHOR

Kirrily Robert, <skud at cpan.org>

BUGS

Please report any bugs or feature requests to bug-metaweb at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Metaweb. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Metaweb

You can also look for information at:

ACKNOWLEDGEMENTS

Thanks to the following people with whom I have discussed Metaweb Perl APIs recently...

Hayden Stainsby (CPAN: HDS)
Kirsten Jones (CPAN: SYNEDRA)

COPYRIGHT & LICENSE

Copyright 2007 Kirrily Robert, all rights reserved.

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