www.openlinksw.com
docs.openlinksw.com

Book Home

Contents
Preface

RDF Data Access and Data Management

Data Representation
SPARQL
Extensions
RDF Graphs Security
RDF Views over RDBMS Data Source
Automated Generation of RDF Views over Relational Data Sources
Examples of RDF Views
RDF Insert Methods in Virtuoso
RDFizer Middleware (Sponger)
Virtuoso Facet Browser Installation and configuration
Virtuoso Facets Web Service
Customizing Examples WebService Interface
Linked Data
Inference Rules & Reasoning
RDF and Geometry
Performance Tuning
RDF Data Access Providers (Drivers)
RDF Graph Replication

14.11. Virtuoso Facets Web Service

The Virtuoso Facets web service is a general purpose RDF query facility for facet based browsing. It takes an XML description of the view desired and generates the reply as an XML tree containing the requested data. The user agent or a local web page can use XSLT for rendering this for the end user. The selection of facets and values is represented as an XML tree. The rationale for this is the fact that such a representation is easier to process in an application than the SPARQL source text or a parse tree of SPARQL and more compactly captures the specific subset of SPARQL needed for faceted browsing. The web service returns the SPARQL source text also, thus this can serve as a basis for and-crafted queries.

The top element of the tree is <query>, it must be in namespace "http://openlinksw.com/services/facets/1.0/".

This has the following attributes:

The result is a tree of the form:

<facets xmlns="http://openlinksw.com/services/facets/1.0/">
<result><row><column datatype="..." shortform="..." xml:lang="..">...</column></row></result>
<time>msecs</time>
<complete>yes or no</complete>
<db-activity>resource use string</db-activity>
<sparql>sparql statement text</sparql>
</facets>

By convention, the first column is the subject selected by the view element, typically a URI, the second a label of the URI and the third, if present, is either a count or a search summary.

The first column's text child is the text form of the value. The column element has the following attributes qualifying this further:

The query has the top level element <query>. The child elements of this represent conditions pertaining to a single subject. A join is expressed with the property or property-of element. This has in turn children which state conditions on a property of the first subject. property and property-of elements can be nested to an arbitrary depth and many can occur inside one containing element. In this way, tree-shaped structures of joins can be expressed.

Expressing more complex relationships, such as intermediate grouping, subqueries, arithmetic or such requires writing the query in SPARQL. The XML format is a shorthand for easy automatic composition of queries needed for showing facets, not a replacement for SPARQL.

A facet query contains a single view element. This specifies which subject of the joined subjects is shown. Its attributes specify the manner of viewing, e.g. list of distinct values, distinct values with occurrence counts, properties or classes of the selected subjects etc.

The top query element or any property or property-of element can have the following types of children:

<text property="iri">text pattern</text>

The subject has an O that matches the text pattern. If property is given, the text pattern must occur in a value of this property. If not specified, any property will do. The value "none" for property is the same as not specifying a property. This is restricted to occurring directly under the top level query element.

<class iri="iri" inference="ctx_name" />

The S must be an instance of this class. If inference is specified then option (input:inference "ctx_name" is added and applies to this pattern alone.

<property iri="iri" same_as="yes" inference="ctx_name">

The child elements of this are conditions that apply to the value of this property of the S that is in scope in the enclosing <query> or <property> element. If same_as is present, then option (input:same-as "yes") is added to the triple pattern which specifies this property. If inference is present, then option (input:inference "ctx_name") is added to the triple pattern for the property.

<property-of iri="iri" same_as="yes" inference="ctx_name" >

The child elements of this are conditions that apply to an S which has property "iri" whose object is the S in scope in the enclosing <query> or <property> element. The options are otherwise the same as with property.

<value datatype="type" xml:lang="lng" op="= | < | > | >= | <=">value </value>

When this occurs inside <property> or <property-of> this means that the property in scope has the specified relation to the value. type and language can be used for XML typed or language tagged literals. The "uri" type means that the value is a qualified name of a URI. If this occurs directly under the <query> element, this means that the query starts with a fixed subject. If this is so, then there must be property or propertyof elements or the view element must specify properties or classes, list is not allowed as a view type. This is so because the query must have at least one triple pattern.

<view type="view" limit="n" offset="n" >

This may occur once inside a <query> element but may occur either at top level or inside property or property-of elements. This specifies what which subject is presented in the result set.

The type can be:

14.11.1. Customizing

The following types of customization will be generally useful:

The source code is divided in two SQL files and a number of XSLT sheets. The file facet.sql has the code for the web service. The facet_view.sql file contains the procedures for the sample HTML interface.


14.11.2. Examples

Note: in all examples the default namespace xmlns="http://openlinksw.com/services/facets/1.0/" is omitted for brevity.

For people called Mike:

<query>
  <text>Mike</text>
  <view type="text"/>
</query>

To open the list of people who Mike knows:

<query>
  <text>Mike</text>
  <view type="properties"/>
</query>

To show the list of subjects Mike knows:

<query>
  <text>Mike</text>
  <property iri="foaf:knows>
    <view type="list" />
  </property>
</query>

To show the properties of people Mike knows:

<query>
  <text>Mike</text>
  <property iri="foaf:knows>
    <view type="properties" />
  </property>
</query>

To show the names:

<query>
  <text>Mike</text>
  <property iri="foaf:knows>
    <property iri="foaf:name>
      <view type="list" />
    </property>
  </property>
</query>

To specify one named Joe:

<query>
  <text>Mike</text>
  <property iri="foaf:knows>
     <property iri="foaf:name>
        <value>Joe</value>
     </property>
    <view type="properties" />
  </property>
</query>

This lists the properties of the friends of Mike that are called Joe.

To show the Mikes that know a Joe, one would change the shown variable in the navigation and get:

<query>
  <text>Mike</text>
  <property iri="foaf:knows>
    <property iri="foaf:name>
      <value>Joe</value>
    </property>
   </property>
   <view type="text" />
</query>

This would be the search summaries of subjects with Mike in some field that know a subject with name Joe.

Now to specify that Mike must be a member of a discussion board:

<query>
  <text>Mike</text>
  <property iri="foaf:knows>
    <property iri="foaf:name>
     <value>Joe</value>
   </property>
  </property>
  <view type="property-in" />
</query>

This lists the properties of triples whom object is Mike. Pick sioc:member_of

<query>
  <text>Mike</text>
  <property iri="foaf:knows>
    <property iri="foaf:name>
      <value>Joe</value>
    </property>
  </property>
  <property-of iri="sioc:member_of>
    <view type="list" />
  </property-of>
</query>

This would show things where Mike is a member. To specify that the thing must be a forum:

<query>
  <text>Mike</text>
  <property iri="foaf:knows>
    <property iri="foaf:name>
      <value>Joe</value>
    </property>
  </property>
  <property-of iri="sioc:member_of>
    <view type="classes" />
  </property-of>
</query>

This shows classes of things where Mike is a member Clicking on sioc:Forum gives:

<query>
  <text>Mike</text>
  <property iri="foaf:knows>
    <property iri="foaf:name>
      <value>Joe</value>
    </property>
  </property>
  <property-of iri="sioc:member_of>
    <class iri="sioc:Forum" />
    <view type="classes"/>
  </property-of>
</query>

The view stays with classes, but now scoped to the classes of things where Mike is a member that are instances of sioc:Forum.

To go look at the list of Mikes with the added restriction, click the shown variable in the navigation and set it to s1.

<query>
  <text>Mike</text>
  <property iri="foaf:knows>
    <property iri="foaf:name>
      <value>Joe</value>
    </property>
  </property>
  <property-of iri="sioc:member_of>
   <class iri="sioc:Forum" />
  </property-of>
  <view type="list"/>
</query>

To say that Joe must also have a geekCode, One clicks the shown variable and sets it to s2 and the view to properties.

<query>
  <text>Mike</text>
  <property iri="foaf:knows>
    <property iri="foaf:name>
      <value>Joe</value>
    </property>
    <view type="properties"/>
  </property>
  <property-of iri="sioc:member_of>
    <class iri="sioc:Forum" />
   </property-of>
</query>

Pick geekCode

<query>
  <text>Mike</text>
  <property iri="foaf:knows>
    <property iri="foaf:name>
      <value>Joe</value>
    </property>
    <property iri="geekCode">
      <view type="list"/>
    </property>
  </property>
  <property-of iri="sioc:member_of>
    <class iri="sioc:Forum" />
  </property-of>
</query>

We specify no restriction on the geekCode. Click the shown variable to take the focus back to Mike.

<query>
  <text>Mike</text>
  <property iri="foaf:knows>
    <property iri="foaf:name>
      <value>Joe</value>
    </property>
    <property iri="geekCode"></property>
  </property>
  <property-of iri="sioc:member_of>
    <class iri="sioc:Forum" />
  </property-of>
  <view type="text"/>
</query>

14.11.3. WebService Interface

14.11.3.1. REST interface

The Virtuoso Facets web service provide following REST interface:

Service description:

Error conditions:

The all error conditions are reported via 'Error explanation'

Files:

The facet_svc.sql contains web service code and virtual directory mapping, and it uses fct_req.xsl & fct_resp.xsl as request & response filters.

Example:

Using CURL program

curl -H "Content-Type: text/xml" -d @post.xml  http://lod.openlinksw.com/fct/service

Where 'post.xml' document contains query document:

<?xml version="1.0"?>
<query xmlns="http://openlinksw.com/services/facets/1.0" inference="" same-as="">
  <text> Seattle Mariners traveled all the way to Japan to watch</text>
  <view type="text" limit="20" offset=""/>
</query>

Produces following response:

<fct:facets xmlns:fct="http://openlinksw.com/services/facets/1.0/">
<fct:sparql>   SELECT distinct ?s1 as ?c1, (bif:search_excerpt (bif:vector ('THE', 'MARINERS', 'WAY', 'SEATTLE', 'WATCH', 'ALL', 'TO', 'JAPAN', 'TRAVELED'), ?o1)) as ?c2  WHERE { ?s1 ?s1textp ?o1 . FILTER (bif:contains (?o1, '(THE AND MARINERS AND WAY AND SEATTLE AND WATCH AND ALL AND TO AND JAPAN AND TRAVELED)')) . } LIMIT 20  OFFSET 0 </fct:sparql>
<fct:time>116</fct:time>
<fct:complete>yes</fct:complete>
<fct:db-activity>   134R rnd  9.488KR seq      0P disk  8.966MB /    602 messages</fct:db-activity>
 <fct:result>
  <fct:row>
    <fct:column datatype="url" shortform="http://bobdupuy.mlbl...ld_baseball__6.html">http://bobdupuy.mlblogs.com/bobdupuy/2006/03/world_baseball__6.html></fct:column>
    <fct:column />
    <fct:column><span class="srch_xerpt">... While Chuck Armstrong president of <b>the</b> <b>Seattle</b> <b>Mariners</b> <b>traveled</b> <b>all</b> <b>the</b> <b>way</b> <b>to</b> <b>Japan</b> <b>to</b> <b>watch</b> Ichiro... for <b>the</b> advancing <b>Japan</b> team last week <b>the</b> star from <b>the</b> <b>Seattle</b> roster so far in Round 1 has without a doubt... leading <b>the</b> Dominican <b>to</b> its...</span></fct:column>
  </fct:row>
  <fct:row>
    <fct:column datatype="url" shortform="http://bobdupuy.mlbl...ld_baseball__6.html">http://bobdupuy.mlblogs.com/bobdupuy/2006/03/world_baseball__6.html></fct:column>
    <fct:column />
    <fct:column><span class="srch_xerpt">Orlando While Chuck Armstrong president of <b>the</b> <b>Seattle</b> <b>Mariners</b> <b>traveled</b> <b>all</b> <b>the</b> <b>way</b> <b>to</b> <b>Japan</b> <b>to</b> <b>watch</b>... perform for <b>the</b> advancing <b>Japan</b> team last week <b>the</b> star from <b>the</b> <b>Seattle</b> roster so far in Round 1 has without...</span></fct:column>
  </fct:row>
 </fct:result>
</fct:facets>

14.11.3.2. Virtuoso APIs for Facet REST services

The Virtuoso APIs for FCT REST services are Virtuoso Stored Procedures that enable faceted browsing over Linked Data hosted in the RDF Quad Store. This also includes Linked Data that is progressively added to the Quad Store via URI de-referencing.

They enable the use Virtuoso's VSP/VSPX technology to produce (X)HTML-based Linked Data explorer pages that are endowed with high-performance (in-process) faceted browsing capability.

You can use this API with Virtuoso SQL calls that provide data to your VSP/VSPX, ASP.NET, PHP, etc., -based interfaces using ODBC, JDBC, ADO.NET, or XMLA connectivity (SPASQL) to Virtuoso.

14.11.3.2.1. API Definition
CREATE PROCEDURE
fct_exec
  (
    IN  tree     ANY ,
    IN  timeout  INT
  )
{
  DECLARE  start_time,
           view3,
           inx,
           n_rows      INT     ;
  DECLARE  sqls,
           msg,
           qr,
           qr2,
           act,
           query       VARCHAR ;
  DECLARE  md,
           res,
           results,
           more        ANY     ;
  DECLARE  tmp         ANY     ;
  DECLARE  offs,
           lim         INT     ;

  SET result_timeout = _min
                         (
                           timeout,
                           ATOI
                             (
                               registry_get ('fct_timeout_max')
                             )
                         )
  ;

  offs := xpath_eval ('//query/view/@offset', tree);
  lim := xpath_eval ('//query/view/@limit', tree);

  -- db_activity ();

  results := vector (null, null, null);
  more := vector ();

  IF
    (
      xpath_eval
        (
          '//query[@view3="yes"]//view[@type="text"]',
          tree
        )
      IS NOT NULL
    )
      {
      more := VECTOR ('classes', 'properties');
  }

  sqls := '00000';
  qr := fct_query
          (
            xpath_eval ('//query', tree, 1)
          )
  ;
  query := qr;
--  dbg_obj_print (qr);
  qr2 := fct_xml_wrap (tree, qr);
  start_time := msec_time ();

  dbg_printf('query: %s', qr2);

  EXEC
    (
      qr2,
      sqls,
      msg,
      vector (),
      0,
      md,
      res
    )
  ;
  n_rows := row_count ();
  act := db_activity ();
  SET result_timeout = 0;
  IF (
       sqls <> '00000'
       AND
       sqls <> 'S1TAT'
     )
    SIGNAL (sqls, msg);
  IF (
       NOT ISARRAY (res)
       OR
       0 = length (res)
       OR
       NOT ISARRAY (res[0])
       OR
       0 = length (res[0])
     )
    results[0] := xtree_doc ('<result/>');
  ELSE
    results[0] := res[0][0];

  inx := 1;

  FOREACH (VARCHAR tp IN more) DO
    {
      tree := XMLUpdate (
                          tree,
                          '/query/view/@type',
                          tp,
                          '/query/view/@limit',
                          '40',
                          '/query/view/@offset',
                          '0'
                        )
      ;
      qr := fct_query (xpath_eval ('//query', tree, 1));
      qr2 := fct_xml_wrap (tree, qr);
      sqls := '00000';
      SET result_timeout = _min (
                                  timeout,
                                  ATOI
                                    (
                                      registry_get ('fct_timeout_max')
                                    )
                                )
      ;
      EXEC (
             qr2,
             sqls,
             msg,
             vector (),
             0,
             md,
             res
           );
      n_rows := row_count ();
      act := db_activity ();
      SET result_timeout = 0;
      IF ( sqls <> '00000'
           AND
           sqls <> 'S1TAT'
         )
    SIGNAL (sqls, msg);
      IF (
           ISARRAY (res)
           AND
           LENGTH (res)
           AND
           ISARRAY (res[0])
           AND
           LENGTH (res[0])
         )
    {
      tmp := res[0][0];
      tmp := XMLUpdate (tmp, '/result/@type', tp);
      results[inx] := tmp;
    }
      inx := inx + 1;
    }



  res := XMLELEMENT
           (
             "facets",
             XMLELEMENT
               ( "sparql", query ),
             XMLELEMENT
               ( "time", msec_time () - start_time ),
             XMLELEMENT
               (
                 "complete",
                 CASE WHEN sqls = 'S1TAT'
                      THEN 'no'
                      ELSE 'yes'
                  END
                ),
             XMLELEMENT
               (
                 "timeout",
                 _min
                   (
                     timeout * 2,
                     ATOI
                       (
                         registry_get
                           ( 'fct_timeout_max' )
                       )
                   )
               ),
             XMLELEMENT
               ("db-activity", act),
             XMLELEMENT
               ("processed", n_rows),
             XMLELEMENT
               (
                 "view",
                 XMLATTRIBUTES
                   (
                     offs AS "offset",
                     lim AS "limit"
                   )
               ),
             results[0],
             results[1],
             results[2]
           );

---- for debugging:
--string_to_file ('ret.xml', serialize_to_UTF8_xml (res), -2);
--  dbg_obj_print (res);

  RETURN res;
}
;

14.11.3.2.2. Example

The following example shows how to use the fct_exec APi in vsp page to perform a "text" search for the word "Mike" assuming this exists in your Virtuoso RDF store (if not amend the query in the fct_example.vsp code sample below to search for text known to exist).

  1. The service can be used in the following sample fct_example.vsp:
    <?vsp
    
    declare txt, reply, tree any;
    declare timeout int;
    
    tree := xtree_doc ('
      <query>
        <text>Mike</text>
        <view type="text"/>
      </query>
    ');
    
    timeout := 3000;
    reply := fct_exec (tree, timeout);
    
    txt := string_output ();
    
    http_value (xslt ('virt://WS.WS.SYS_DAV_RES.RES_FULL_PATH.RES_CONTENT:/DAV/fct_example.xsl',
                     reply,
       	         vector ()),
    	         null, txt);
    
    http (txt);
    ?>
    
  2. The xsl:
    <?xml version="1.0" encoding="utf-8"?>
    <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
      <xsl:output method="html" encoding="ISO-8859-1"/>
      <xsl:variable name="rowcnt" select="count(/facets/result/row)"/>
      <xsl:template match="facets">
        <div id="res">
          <xsl:if test="/facets/complete = 'yes' and /facets/processed = 0 and $rowcnt = 0">
            <div class="empty_result">
              Nothing found.
            </div>
          </xsl:if>
          <xsl:for-each select="/facets/result">
            <xsl:call-template name="render-result"/>
          </xsl:for-each>
        </div>
        <!-- #res -->
        </xsl:template>
      <xsl:template name="render-result">
        <table class="result" border="1">
          <thead>
            <tr>
              <th>Entity</th>
              <th>Title</th>
              <th>Text excerpt</th>
            </tr>
          </thead>
          <tbody>
            <xsl:for-each select="row">
              <tr>
                <td class="rnk">
                  <xsl:for-each select="column[@datatype='trank' or @datatype='erank']">
    		<xsl:choose>
                      <xsl:when test="./@datatype='trank'">Text Rank:</xsl:when>
                      <xsl:when test="./@datatype='erank'">Entity Rank:</xsl:when>
                    </xsl:choose>
                    <xsl:value-of select="."/>
                    <br/>
                  </xsl:for-each>
                </td>
                <xsl:for-each select="column">
                  <xsl:choose>
                    <xsl:when test="'url' = ./@datatype">
                      <td>
                        <a>
                          <xsl:attribute name="href">http://lod.openlinksw.com/describe/?url=<xsl:value-of select="urlify (.)"/></xsl:attribute>
                          <xsl:attribute name="title"><xsl:value-of select="."/></xsl:attribute>
                          <xsl:choose>
                            <xsl:when test="'' != ./@shortform">
                              <xsl:value-of select="./@shortform"/>
    		    </xsl:when>
                            <xsl:when test="'erank' = ./@datatype or 'trank' = ./@datatype">rank</xsl:when>
    		    <xsl:otherwise>
                              <xsl:value-of select="."/>
    		    </xsl:otherwise>
    		</xsl:choose>
                        </a>
                      </td>
                    </xsl:when>
                    <xsl:when test="'erank' = ./@datatype or 'trank' = ./@datatype"/>
                    <xsl:when test="'srch_xerpt' = ./span/@class">
                      <td>
                        <xsl:value-of select="."/>
                      </td>
                    </xsl:when>
                    <xsl:otherwise/>
                  </xsl:choose>
                </xsl:for-each>
              </tr>
            </xsl:for-each>
          </tbody>
        </table>
      </xsl:template>
      <xsl:template match="@* | node()">
        <xsl:copy>
          <xsl:apply-templates select="@* | node()"/>
        </xsl:copy>
        </xsl:template>
    </xsl:stylesheet>
    
  3. The result of executing the fct_example.vsp should be:
    Facet API Example
    Figure: 14.11.3.2.2.1. Facet API Example


14.11.3.3. SOAP interface

The facet web service is also available via SOAP protocol.

The request message contains single element 'query' with syntax explained earlier. Also the SOAPAction HTTP header should be '#query' . After successful evaluation of the query, the service will return a SOAP envelope containing in the Body element single 'facets' element described above.

Example:

This example shows execution of same command as in example for REST interface here it using SOAP:

Request message:

<SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP:Body>
    <query xmlns="http://openlinksw.com/services/facets/1.0/" inference="" same-as="">
      <text>Seattle Mariners traveled all the way to Japan to watch</text>
      <view type="text" limit="20" offset="0"/>
    </query>
  </SOAP:Body>
</SOAP:Envelope>

Response message:

<SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP:Body>
    <fct:facets xmlns:fct="http://openlinksw.com/services/facets/1.0/">
      <fct:sparql>SELECT distinct ?s1 as ?c1, (bif:search_excerpt (bif:vector ('THE', 'MARINERS', 'WAY', 'SEATTLE', 'WATCH', 'ALL', 'TO', 'JAPAN', 'TRAVELED'), ?o1)) as ?c2  where { ?s1 ?s1textp ?o1 . filter (bif:contains (?o1, '(THE AND MARINERS AND WAY AND SEATTLE AND WATCH AND ALL AND TO AND JAPAN AND TRAVELED)')) . } LIMIT 20  OFFSET 0</fct:sparql>
      <fct:time>114</fct:time>
      <fct:complete>yes</fct:complete>
      <fct:db-activity>   134R rnd  9.488KR seq      0P disk  8.966MB /    602 messages</fct:db-activity>
      <fct:result>
        <fct:row>
          <fct:column datatype="url" shortform="http://bobdupuy.mlbl...ld_baseball__6.html">http://bobdupuy.mlblogs.com/bobdupuy/2006/03/world_baseball__6.html</fct:column>
          <fct:column/>
          <fct:column><span class="srch_xerpt">... While Chuck Armstrong president of <b>the</b> <b>Seattle</b> <b>Mariners</b> <b>traveled</b> <b>all</b> <b>the</b> <b>way</b> <b>to</b> <b>Japan</b> <b>to</b> <b>watch</b> Ichiro... for <b>the</b> advancing <b>Japan</b> team last week <b>the</b> star from <b>the</b> <b>Seattle</b> roster so far in Round 1 has without a doubt... leading <b>the</b> Dominican <b>to</b> its...</span></fct:column>
        </fct:row>
        <fct:row>
          <fct:column datatype="url" shortform="http://bobdupuy.mlbl...ld_baseball__6.html">http://bobdupuy.mlblogs.com/bobdupuy/2006/03/world_baseball__6.html</fct:column>
          <fct:column/>
          <fct:column><span class="srch_xerpt">Orlando While Chuck Armstrong president of <b>the</b> <b>Seattle</b> <b>Mariners</b> <b>traveled</b> <b>all</b> <b>the</b> <b>way</b> <b>to</b> <b>Japan</b> <b>to</b> <b>watch</b>... perform for <b>the</b> advancing <b>Japan</b> team last week <b>the</b> star from <b>the</b> <b>Seattle</b> roster so far in Round 1 has without...</span></fct:column>
        </fct:row>
      </fct:result>
    </fct:facets>
  </SOAP:Body>
</SOAP:Envelope>