NAME
DBD::google - Treat Google as a datasource for DBI
SYNOPSIS
use DBI;
my $dbh = DBI->connect("dbi:google:", $KEY);
my $sth = $dbh->prepare(qq[
SELECT title, URL FROM google WHERE q = "perl"
]);
while (my $r = $sth->fetchrow_hashref) {
...
DESCRIPTION
DBD::google allows you to use Google as a datasource; google can be
queried using SQL *SELECT* statements, and iterated over using standard
DBI conventions.
WARNING: This is still alpha-quality software. It works for me, but that
doesn't really mean anything.
WHY?
For general queries, what better source of information is there than
Google?
BASIC USAGE
For the most part, use "DBD::google" like you use any other DBD, except
instead of going through the trouble of building and installing (or
buying!) database software, and employing a DBA to manage your data, you
can take advantage of Google's ability to do this for you. Think of it
as outsourcing your DBA, if you like.
Connection Information
The connection string should look like: "dbi:google:" (DBI requires the
trailing ":").
Your Google API key should be specified in the username portion (the
password is currently ignored; do whatever you want with it, but be
warned that I might put that field to use some day):
my $dbh = DBI->connect("dbi:google:", "my key", undef, \%opts);
Alternatively, you can specify a filename in the user portion; the first
line of that file will be treated as the key:
my $dbh =DBI->connect("dbi:google:",
File::Spec->catfile($ENV{HOME}, ".googlekey"))
In addition to the standard DBI options, the fourth argument to connect
can also include the following "DBD::google" specific options, the full
details of each of which can be found in the Net::Google manpage:
ie Input Encoding. String, e.g., "utf-8".
oe Output Encoding. String, e.g., "utf-8".
safe Should safe mode be on. Boolean.
filter Should results be filtered. Boolean.
lr Something to do with language. Arrayref.
debug Should "Net::Google" be put into debug mode or not?
Boolean.
Supported SQL Syntax and Random Notes Thereon
The only supported SQL statement type is the *SELECT* statement. Since
there is no real "table" involved, I've created a hypothetical table,
called *google*; this table has one queryable field, *q* (just like the
public web-based interface). The available columns are currently
dictated by the data available from the underlying transport, which is
the Google SOAP API (see http://www.google.com/apis), as implemented by
Aaron Straup Cope's "Net::Google" module.
The basic SQL syntax supported looks like:
SELECT @fields FROM google WHERE q = '$query'
There is also an optional LIMIT clause, the syntax of which is similar
to that of MySQL's LIMIT clause; it takes a pair: offset from 0, number
of results. In practice, Google returns 10 results at a time by default,
so specifying a high LIMIT clause at the beginning might make sense for
many queries.
The list of available fields in the *google* table includes:
title Returns the title of the result, as a string.
URL Returns the URL of the result, as a (non-HTML encoded!)
string.
snippet Returns a snippet of the result.
cachedSize Returns a string indicating the size of the cached
version of the document.
directoryTitle Returns a string.
summary Returns a summary of the result.
hostName Returns the hostname of the result.
directoryCategory
Returns the directory category of the result.
The column specifications can include aliases:
SELECT directoryCategory as DC FROM google WHERE...
Finally, "DBD::google" supports functions:
SELECT title, html_encode(url) FROM google WHERE q = '$stuff'
There are several available functions available by default:
uri_escape This comes from the "URI::Escape" module.
html_escape This wraps around "HTML::Entities::encode_entities".
html_strip This removes HTML from a field. Some fields, such as
title, summary, and snippet, have the query terms
highlighted with <b> tags by Google; this function can
be used to undo that damage.
Finally, "DBD::google" also supports arbitrary functions, specified
using a fully qualified Perl package identifier:
SELECT title, Digest::MD5::md5_hex(title) FROM google WHERE ...
Functions and aliases can be combined:
SELECT html_strip(snippet) as stripped_snippet FROM google...
Unsupported SQL includes ORDER BY clauses (Google does this, and
provides no interface to modify it), HAVING clauses, JOINs of any type
(there's only 1 "table", after all), sub-SELECTS (I can't even imagine
of what use they would be here), and, actually, anything not explicitly
mentioned above.
INSTALLATION
"DBD::google" is pure perl, and has a few module requirements:
Net::Google This is the heart of the module; "DBD::google" is
basically a DBI-compliant wrapper around "Net::Google".
HTML::Entities, URI::Escape
These two modules provide the uri_escape and html_escape
functions.
DBI Duh.
To install:
$ perl Makefile.PL
$ make
$ make test
# make install
$ echo 'I love your module!' | mail darren@cpan.org -s "DBD::google"
The last step is optional; the others are not.
EXAMPLES
Here is a complete script that takes a query from the command line and
formats the results nicely:
#!/usr/bin/perl -w
use strict;
use DBI;
use Text::TabularDisplay;
my $query = "@ARGV" || "perl";
# Set up SQL statement -- note the multiple lines
my $sql = qq~
SELECT
title, URL, hostName
FROM
google
WHERE
q = "$query"
~;
# DBI/DBD options:
my %opts = ( RaiseError => 1, # Standard DBI options
PrintError => 0,
lr => [ 'en' ], # DBD::google options
oe => "utf-8",
ie => "utf-8",
);
# Get API key
my $keyfile = glob "~/.googlekey";
# Get database handle
my $dbh = DBI->connect("dbi:google:", $keyfile, undef, \%opts);
# Create Text::TabularDisplay instance, and set the columns
my $table = Text::TabularDisplay->new;
$table->columns("Title", "URL", "Hostname");
# Do the query
my $sth = $dbh->prepare($sql);
$sth->execute;
while (my @row = $sth->fetchrow_array) {
$table->add(@row);
}
$sth->finish;
print $table->render;
TODO
These are listed in the order in which I'd like to implement them.
More tests!
I'm particularly unimpressed with the test suite for the SQL parser;
I think it is pretty pathetic. It needs much better testing, with
more edge cases and more things I'm not expecting to find.
I've specifically avoided including tests that actually query
Google, because the free API keys have a daily limit to the number
of requests that will be answered. My original test suite did a few
dozen queries each time it was run; if you run the test suite a few
dozen times in a day (easy to do if you are actively developing the
software or changing the feature set), your daily quota can be eaten
up very easily.
Integration of search metadata
There are several pieces of metadata that come back with searches;
access to the via the statement handle ($sth) would be nice:
my $search_time = $sth->searchTime();
my $total = $sth->estimatedTotalResultsNumber();
The metadata includes:
o documentFiltering
o searchTime
o estimatedTotalResultsNumber
o estimateIsExact
o searchTips
o searchTime
These are described in the Net::Google::Response manpage.
Extensible functions
Unknown functions that look like Perl package::function names should
probably be treated as such, and AUTOLOADed:
SELECT Foo::frob(title) FROM google WHERE q = "perl"
Would do, effectively:
require Foo;
$title = Foo::frob($title);
I'm slightly afraid of where this could lead, though:
SELECT title, LWP::Simple::get(url) as WholeDamnThing
FROM google
WHERE q = "perl apache"
LIMIT 0, 100
Elements return objects, instead of strings
It would be interesting for columns like URL and hostName to return
"URI" and "Net::hostent" objects, respectively.
On the other hand, this is definitely related to the previous item;
the parser could be extended to accept function names in method
format:
SELECT title, URI->new(URL), Net::hostent->new(hostName)
FROM google WHERE q = "perl"
DESCRIBE statement on the "google" table
It would be nice to provide a little introspection.
CAVEATS, BUGS, IMPROVEMENTS, SUGGESTIONS, FOIBLES, ETC
I've only tested this using my free, 1000-uses-per-day API key, so I
don't know how well/if this software will work for those of you who have
purchased real licenses for unlimited usage.
Placeholders are currently unsupported. They won't do any good, but
would be nice to have for consistency with other DBDs. I'll get around
to it someday.
There are many Interesting Things that can be done with this module, I
think -- suggestions as to what those things might actually be are very
welcome. Patches implementing said Interesting Things are also welcome,
of course.
More specifically, queries that the SQL parser chokes on would be very
useful, so I can refine the test suite (and the parser itself, of
course).
There are probably a few bugs, though I don't know of any. Please report
them via the DBD::google queue at <http://rt.cpan.org/>.
SEE ALSO
the DBI manpage, the DBI::DBD manpage, the Net::Google manpage, the
URI::Escape manpage, the HTML::Entities manpage
AUTHOR
darren chamberlain <darren@cpan.org>