Examples

cyga edited this page Feb 22, 2013 · 13 revisions
Clone this wiki locally

Examples

Twitter

Following is simplest example for twitter without any callbacks:

DROP EXTENSION IF EXISTS www_fdw CASCADE;
CREATE EXTENSION www_fdw;
CREATE SERVER www_fdw_server_twitter FOREIGN DATA WRAPPER www_fdw OPTIONS
    (uri 'http://search.twitter.com/search.json');
CREATE USER MAPPING FOR current_user SERVER www_fdw_server_twitter;
CREATE FOREIGN TABLE www_fdw_twitter (
    /* parameters used in request */
    q text,
    page text,
    rpp text,
    result_type text,

    /* fields in response */
    created_at text,
    from_user text,
    from_user_id text,
    from_user_id_str text,
    geo text,
    id text,
    id_str text,
    is_language_code text,
    profile_image_url text,
    source text,
    text text,
    to_user text,
    to_user_id text
) SERVER www_fdw_server_twitter;

As far as you can see fields in www_fdw_twitter table can be divided into 2 groups:

  • fields used in request;
  • response fields.

Fields those are used in request will be null in response, nonetheless they give us easy way for specifying queries. You can check current twitter search API here.

Simple query (response text field is truncated for the sake of formatting (same in the father examples)):

postgres=# select id,substr(text,1,30)||'...' from www_fdw_twitter where q='postgres';
    id     |                        ?column?                       
------------+---------------------------------------------------------
2147483647 | http://t.co/NfrK4B2T この項目かな...
2147483647 | Database Developer - Datenbank...
2147483647 | Web hosting news: devoted e107...
2147483647 | RT @sora_h: まあGAEがオワコンでゴミであること...
2147483647 | Postgres suena demasiado a Pos...
2147483647 | @sgerrand Yes, this is only ab...
2147483647 | RT @soudai1025: xmlを吐くためにpostg...
2147483647 | xmlを吐くためにpostgresにテーブル作ってテストデー...
2147483647 | Macでpostgresにmagic3を入れようとしたらエラ...
2147483647 | Linux results for that Postgre...
2147483647 | http://t.co/1nSyFydm Enterpris...
2147483647 | EnterpriseDB's Karen Padir: Fr...
2147483647 | DBはSQLiteも選択肢に入れて自分が使いやすいやつでいい...
2147483647 | RT @soudai1025: とりあえずFTPとsshとア...
2147483647 | RT @soudai1025: とりあえずFTPとsshとア...
(15 rows)

More sophisticated one:

postgres=# select id,substr(text,1,30)||'...' from www_fdw_twitter where q='postgres' and page='2' and rpp='3';
    id     |                     ?column?                     
------------+--------------------------------------------------
2147483647 | RT @sora_h: まあGAEがオワコンでゴミであること...
2147483647 | Postgres suena demasiado a Pos...
2147483647 | @sgerrand Yes, this is only ab...
(3 rows)

Easy, right?

The trick is made by auto request serialization and auto response parsing. Basically auto request serialization process converts " where column0=value0 and ..." into "?column0=value0&...". Auto response parsing gets "First array (with all elements of the same type/structure) will be returned (breadth-first search)". Details are in documentation.

Google search

Here is example for google search usage:

DROP EXTENSION IF EXISTS www_fdw CASCADE;
CREATE EXTENSION www_fdw;
CREATE SERVER www_fdw_server_google_search FOREIGN DATA WRAPPER www_fdw
    OPTIONS (uri 'https://ajax.googleapis.com/ajax/services/search/web?v=1.0');
CREATE USER MAPPING FOR current_user SERVER www_fdw_server_google_search;
CREATE FOREIGN TABLE www_fdw_google_search (
    /* parameters used in request */
    q text,

    /* fields in response */
    GsearchResultClass text,
    unescapedUrl text,
    url text,
    visibleUrl text,
    cacheUrl text,
    title text,
    titleNoFormatting text,
    content text
) SERVER www_fdw_server_google_search;

postgres=# select url,substring(title,1,25)||'...',substring(content,1,25)||'...'
    from www_fdw_google_search where q='postgres';
                url                   |           ?column?           |           ?column?           
-----------------------------------------+------------------------------+------------------------------
http://www.postgresql.org/              | <b>PostgreSQL</b>: The wo... | Sophisticated open-source...
http://www.postgresql.org/download/     | <b>PostgreSQL</b>: Downlo... | The core of the <b>Postgr...
http://www.postgresql.org/docs/         | <b>PostgreSQL</b>: Docume... | There is a wealth of <b>P...
http://en.wikipedia.org/wiki/PostgreSQL | <b>PostgreSQL</b> - Wikip... | <b>PostgreSQL</b>, often ...
(4 rows)

It's also very easy as twitter's one. It's here for the reference that you can use parameters in the url (https://ajax.googleapis.com/ajax/services/search/web?v=1.0). Here you can find documentation for Google search API

Google maps API

Here is example for google maps API:

DROP EXTENSION IF EXISTS www_fdw CASCADE;                             
CREATE EXTENSION www_fdw;                                             
CREATE SERVER www_fdw_server_geocoder_google FOREIGN DATA WRAPPER www_fdw
    OPTIONS (uri 'maps.googleapis.com/maps/api/geocode/xml?sensor=false',
        response_type 'xml', response_deserialize_callback 'test_response_deserialize_callback');

CREATE USER MAPPING FOR current_user SERVER www_fdw_server_geocoder_google;      
CREATE FOREIGN TABLE www_fdw_geocoder_google (
    /* parameters used in request */                                  
    address text,

    /* fields in response */                                          
    "type" text,
    "formatted_address" text,
    "lat" text,
    "lng" text,
    "location_type" text
) SERVER www_fdw_server_geocoder_google; 
CREATE OR REPLACE FUNCTION test_response_deserialize_callback(options WWWFdwOptions, response xml)
    RETURNS SETOF www_fdw_geocoder_google AS $$
DECLARE
    rows RECORD;
    address text;
    type text;
    formatted_address text;
    lat text;
    lng text;
    location_type text;
    r RECORD;
BEGIN
    RAISE INFO 'options parameter: %', options;
    RAISE INFO 'response parameter: %', response;
    FOR rows IN SELECT unnest(xpath('/GeocodeResponse/result', response)) LOOP
        type := (xpath('/result/type/text()', rows.unnest))[1];
        formatted_address := (xpath('/result/formatted_address/text()', rows.unnest))[1];
        lat := (xpath('/result/geometry/location/lat/text()', rows.unnest))[1];
        lng := (xpath('/result/geometry/location/lng/text()', rows.unnest))[1];
        location_type := (xpath('/result/geometry/location_type/text()', rows.unnest))[1];
        r := ROW(address, type, formatted_address, lat, lng, location_type);
        RETURN NEXT r;
    END LOOP;
END; $$ LANGUAGE PLPGSQL;

postgres=# select * from www_fdw_geocoder_google where address='1600 Amphitheatre Parkway,Mountain View, CA';
 address |      type      |                    formatted_address                    |    lat     |     lng      | location_type 
---------+----------------+---------------------------------------------------------+------------+--------------+---------------
         | street_address | 1600 Amphitheatre Parkway, Mountain View, CA 94043, USA | 37.4221941 | -122.0845932 | ROOFTOP
(1 row)

postgres=# select * from www_fdw_geocoder_google where address='Lenina str';
address | type  |                            formatted_address                             |    lat     |    lng     |  location_type 
--------+-------+--------------------------------------------------------------------------+------------+------------+------------------
        | route | Myru avenue, Chernihiv, Chernihivs'ka oblast, Ukraine                    | 51.5052790 | 31.2821798 | GEOMETRIC_CENTER
        | route | Lenina Street, Naryn, Kyrgyzstan                                         | 41.4259113 | 75.9641129 | GEOMETRIC_CENTER
        | route | Lenina Street, Cherkas'ka oblast, Ukraine                                | 49.5260500 | 31.7381490 | GEOMETRIC_CENTER
        | route | Lenina street, Smila, Cherkas'ka oblast, Ukraine                         | 49.2273820 | 31.8563590 | GEOMETRIC_CENTER
        | route | Lenina street, Berdychiv, Zhytomyrs'ka oblast, Ukraine                   | 49.9112730 | 28.5883189 | GEOMETRIC_CENTER
        | route | Lenina street, Sofiivs'ka Borshchahivka, Kyivs'ka oblast, Ukraine, 08131 | 50.4088780 | 30.3577571 | GEOMETRIC_CENTER
        | route | Lenina street, Koktebel', Crimea, Ukraine, 98186                         | 44.9600250 | 35.2388678 | GEOMETRIC_CENTER
        | route | Lenina street, Sudak, Crimea, Ukraine                                    | 44.8525730 | 34.9763101 | GEOMETRIC_CENTER
        | route | Lenina street, Chernihivka, Zaporiz'ka oblast, Ukraine                   | 47.1967920 | 36.1972080 | GEOMETRIC_CENTER
        | route | Lenina street, Hostomel', Kyivs'ka oblast, Ukraine                       | 50.5759920 | 30.2665500 | GEOMETRIC_CENTER
        | route | Lenina street, Poltava, Poltavs'ka oblast, Ukraine                       | 49.5804870 | 34.5690125 | GEOMETRIC_CENTER
(11 rows)

Wiki XML API

Another example is for XML format. It's Wiki OpenSearch API:

DROP EXTENSION IF EXISTS www_fdw CASCADE;                             
CREATE EXTENSION www_fdw;                                             
CREATE SERVER www_fdw_server_wiki FOREIGN DATA WRAPPER www_fdw
    OPTIONS (uri 'http://en.wikipedia.org/w/api.php?action=opensearch&namespace=0&format=xml',
        response_type 'xml');
CREATE USER MAPPING FOR current_user SERVER www_fdw_server_wiki;      
CREATE FOREIGN TABLE www_fdw_wiki (
    /* parameters used in request */                                  
    search text,
    "limit" text,

    /* fields in response */                                          
    "Text" text,
    "Description" text,                                               
    "Url" text
) SERVER www_fdw_server_wiki;                                         

postgres=# select "Text",substring("Description",1,25)||'...',"Url"
    from www_fdw_wiki where search='postgres' and "limit"='2';     
    Text     |           ?column?           |                    Url
--------------+------------------------------+-------------------------------------------
PostgreSQL   | PostgreSQL, often simply ... | http://en.wikipedia.org/wiki/PostgreSQL
EnterpriseDB | EnterpriseDB is a private... | http://en.wikipedia.org/wiki/EnterpriseDB
(2 rows)

Example with response_deserialize_callback

Following is example from test/xml-response-deserialize-callback.sql:

DROP EXTENSION IF EXISTS www_fdw CASCADE;
CREATE EXTENSION www_fdw;
CREATE SERVER www_fdw_server_test FOREIGN DATA WRAPPER www_fdw
    OPTIONS (uri 'http://localhost:7777', response_type 'xml',
        response_deserialize_callback 'test_response_deserialize_callback');
CREATE USER MAPPING FOR current_user SERVER www_fdw_server_test;
CREATE FOREIGN TABLE www_fdw_test (
    title text,                                                     
    link text,
    snippet text
) SERVER www_fdw_server_test;
CREATE OR REPLACE FUNCTION test_response_deserialize_callback(options WWWFdwOptions, response xml)
    RETURNS SETOF www_fdw_test AS $$
DECLARE
    rows RECORD;
    title text;
    link text;
    snippet text;
    r RECORD;
BEGIN
    RAISE NOTICE 'options parameter: %', options;
    RAISE NOTICE 'response parameter: %', response;
    FOR rows IN SELECT unnest(xpath('/doc/rows/row', response)) LOOP
        title := (xpath('/row/title/text()', rows.unnest))[1];
        link := (xpath('/row/link/text()', rows.unnest))[1];
        snippet := (xpath('/row/snippet/text()', rows.unnest))[1];
        r := ROW(title, link, snippet);
        RETURN NEXT r;
    END LOOP;
END; $$ LANGUAGE PLPGSQL;

It parses responses like:

<doc>
    <row>
        <title>TITLE</title>
        <link>LINK</link>
        <snippet>SNIPPET</snippet>
    </row>
</doc>

Example with response_iterate_callback

Here we have example almost the same as the previous one for twitter, but it reverses string for "text" field for each parsed row:

DROP EXTENSION IF EXISTS www_fdw CASCADE;
CREATE EXTENSION www_fdw;
CREATE SERVER www_fdw_server_test FOREIGN DATA WRAPPER www_fdw
    OPTIONS (uri 'http://search.twitter.com/search.json',             
        response_iterate_callback 'test_response_iterate_callback');
CREATE USER MAPPING FOR current_user SERVER www_fdw_server_test;      
CREATE FOREIGN TABLE www_fdw_test (
    /* parameters used in request */                                  
    q text,
    page text,
    rpp text,
    result_type text,                                                 

    /* fields in response */                                          
    text text
) SERVER www_fdw_server_test;                                         
CREATE OR REPLACE FUNCTION test_response_iterate_callback
    (options WWWFdwOptions, INOUT tuple www_fdw_test) AS $$
BEGIN
    RAISE NOTICE 'options parameter: %', options;                      
    RAISE NOTICE 'tuple parameter: %', tuple;                          
    tuple.text := reverse(tuple.text);
END; $$ LANGUAGE PLPGSQL;                                             

postgres=# select text from www_fdw_test where q='postgres' limit 2;
                                                    text                                                        
-------------------------------------------------------------------------------------------------------------------
boj# MyT1eXIr/oc.t//:ptth AM ,orobxoF ni k031 ot xuniL LQS/sergtsoP/LTE - tcetihcrA esabataD/ABD erohS htuoS :boJ
 .sppa orPxoF lausiV rof tnemecalper tseb eht si sergtsoP dna 0.2 xfavaJ kniht I vrgnXYJ9/oc.t//:ptth
(2 rows)

Example with request_serialize_callback

Request callback is the hardest one, that's why it's left as the last example.

Basically processing of request with callback depends on request_serialize_type. It specifies how "quals" (tree for parsed where statement) have to be serialized. Following options are available:

  • log - default, same serialization as with debug_print_parse option for postgres;
  • null - doesn't serialize quals and pass null value instead;
  • json - quals tree is serialized into json string;
  • xml - quals tree is serialized into xml string.

Following is an example from test/request-serialize-callback-type-json.sql:

DROP EXTENSION IF EXISTS www_fdw CASCADE;
CREATE EXTENSION www_fdw;
CREATE SERVER www_fdw_server_test FOREIGN DATA WRAPPER www_fdw
    OPTIONS (uri 'http://localhost:7777',
        request_serialize_callback 'test_request_serialize_callback',
        request_serialize_type 'json');
CREATE USER MAPPING FOR current_user SERVER www_fdw_server_test;
CREATE FOREIGN TABLE www_fdw_test (
    title text,                                                     
    link text,
    snippet text
) SERVER www_fdw_server_test;
CREATE OR REPLACE FUNCTION test_request_serialize_callback(options WWWFdwOptions,
    quals text, INOUT url text, INOUT post WWWFdwPostParameters) AS $$
BEGIN
    RAISE NOTICE 'options parameter: %', options;
    RAISE NOTICE 'quals parameter: %', quals;
    RAISE NOTICE 'url parameter: %', url;
    RAISE NOTICE 'post parameter: %', post;
END; $$ LANGUAGE PLPGSQL;

You have following arguments to your callback:

  • options WWWFdwOptions - options specified to extension/server/user;
  • quals text - serialized quals tree;
  • INOUT url text - url, OUT parameter;
  • INOUT post WWWFdwPostParameters - post parameters, OUT parameter.

So you can try to parse quals for better control over query parameters processing. Nonetheless it's not an easy task. You can switch on/off request_serialize_human_readable parameter (1/0) in order to have serialized quals string indented.

Also you can modify url according to quals or specify post parameters if any.

In general it's not an easy task to handle request and I can't see any easier general way for achieving this. Nonetheless you have great control over possible cases.