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>