Virtuoso Open-Source Wiki
Virtuoso Open-Source, OpenLink Data Spaces, and OpenLink Ajax Toolkit
Advanced Search
Help?
Location: / Dashboard / Main / VirtuosoFacetsWebService

Virtuoso Facets Web Service

What

The Virtuoso Facets web service is a general purpose RDF query facility for facet based browsing. It takes an XML description of the desired view, 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.

Why

The selection of facets and values is represented as an XML tree. 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 also returns the SPARQL source text, which can serve as a basis for hand-crafted queries.

How

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

The <query> element has the following attributes:

  • graph="graph_iri" — installed default is to search in all graphs, but system defaults may override this
  • timeout="no_of_msec" — installed default is no timeout, but system defaults may override this
  • inference="name" — where name is the name of an inference context declared with rdfs_rule_set.
  • same-as="boolean" — If "boolean" is "yes", then owl:sameAs links will be considered in the query evaluation.

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 is 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:

  • datatype — The xsd type of the value. If this is a URI, the datatype is "uri".
  • shortform — If the value is a URI, this is an abbreviated form where known namespaces are replaced with their prefixes, and very long URIs are middle-truncated, preserving start and end.
  • xml:lang — if the value is a language tagged string, this is the language.

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., a list of distinct values, a list of distinct values with occurrence counts, a list of 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:

  • "properties" 

    SELECT  ?p 
        COUNT (*) 
  WHERE  { ?this_s  ?p  ?any_o ... }
  GROUP BY  ?p 
  ORDER BY  DESC 2 
  LIMIT   l 
  OFFSET  o

  • "properties-in" 

    SELECT  ?p 
        COUNT (*) 
  WHERE  { ?any_s  ?p  ?this_s ... } 
  GROUP BY  ?p
  ORDER BY  DESC 2 
  LIMIT     l 
  OFFSET    o

  • "classes" 

    SELECT  ?c 
        COUNT (*) 
  WHERE {?xx  a  ?c ... } 
  GROUP BY  ?c 
  ORDER BY  DESC 2 
  LIMIT     l
  OFFSET    o

  • "text" 

    SELECT DISTINCT  ?s 
                 (bif:search_excerpt (sql:search_terms (""pattern"), ?o)) 
  WHERE { ... }
  ORDER BY ?s
  LIMIT   l 
  OFFSET  o

  • "list" 

    SELECT DISTINCT  ?s 
                 long::sql:fct_label (?s) 
  WHERE { ... }
  ORDER BY ?s
  LIMIT   l 
  OFFSET  o

  • "list-count" 

    SELECT  ?s 
        COUNT (*)
  WHERE { ... }
  GROUP BY  ?s
  ORDER BY  DESC 2

  • "alphabet" 

    SELECT  (sql:subseq (?s, 0, 1)) 
        COUNT (*)
  WHERE { ... }
  GROUP BY  (sql:subseq (?s, 0, 1)) 
  ORDER BY  1

  • "geo" 

    SELECT  DISTINCT ?lat 
                 ?long
                 ?s  
  WHERE { ?s  geo:lat   ?lat   . 
          ?s  geo:long  ?long  . 
          ... }

  • "years" 

    SELECT  sql::year (?s) 
        COUNT (*) 
  WHERE { ... }
  GROUP BY  (bif:year (?s))
  ORDER BY  1 
  LIMIT     l
  OFFSET    o

  • "months" 

    SELECT  sql::round_month (?s) 
        COUNT (*) 
  WHERE { ... }
  GROUP BY  (sql:round_month (?s))
  ORDER BY  1
  LIMIT     l
  OFFSET    o

  • "weeks" 

    SELECT  sql::round_week (?s) 
        COUNT (*) 
  WHERE { ... }
  GROUP BY  (sql:round_week (?s))
  ORDER BY  1
  LIMIT     l
  OFFSET    o

  • "describe" 

    DESCRIBE  ?s
  WHERE { ... }
  LIMIT     l
  OFFSET    o

Customizing

The following types of customization will be generally useful:

  • Resource accounting and limitations, managing access and login
  • Localization, choice of labels shown with class/property/instance URIs
  • Adding types of views, for example timelines, map or business graphics
  • Controlling navigation, for example choosing what type of view is initially presented when opening a given property.
  • Page layout, captions, help texts, etc.

The source code is deivided 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.

Example

Note: In all examples, the default namespace declaration, 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 datatype="string">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 datatype="string">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 datatype="string">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 datatype="string">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 datatype="string">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 datatype="string">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 datatype="string">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 datatype="string">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 datatype="string">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 datatype="string">Joe</value>
    </property>
    <property iri="geekCode"></property>
  </property> 
  <property-of iri="sioc:member_of"> 
    <class iri="sioc:Forum" /> 
  </property-of>   
  <view type="text"/> 
</query>

Looking up property count: 

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>
  <text>Mike</text>
  <property iri="[foaf:knows]">
    <view type="list-count" limit="20" />
  </property>
</query>

Produces the following response: 

<fct:facets xmlns:fct="http://openlinksw.com/services/facets/1.0/">
<fct:sparql>
   SELECT  ?s2 AS ?c1 
           COUNT (*) AS ?c2  
     WHERE { ?s1  ?s1textp                                 ?o1                         . 
             ?o1  bif:contains                             '"Mike"'  . 
             ?s1  <http://xmlns.com/foaf/0.1/knows>  ?s2 
           } 
     GROUP BY  ?s2 
     ORDER BY  DESC 2 
     LIMIT     20 
</fct:sparql>
<fct:time>68373</fct:time>
<fct:complete>yes</fct:complete>
<fct:timeout>0</fct:timeout>
<fct:db-activity> 273.2KR rnd  313.8KR seq  38.07KP disk   5.99MB /  3.176K messages</fct:db-activity>
 <fct:result type="list-count">
  <fct:row>
    <fct:column datatype="url" shortform="http://twitter.com/sxsw"><![CDATA[http://twitter.com/sxsw]]></fct:column>
    <fct:column><![CDATA[sxsw]]></fct:column>
    <fct:column><![CDATA[95]]></fct:column>
  </fct:row>
  <fct:row>
    <fct:column datatype="url" shortform="http://twitter.com/nick"><![CDATA[http://twitter.com/nick]]></fct:column>
    <fct:column><![CDATA[Nick Douglas]]></fct:column>
    <fct:column><![CDATA[91]]></fct:column>
  </fct:row>
  <fct:row>
    <fct:column datatype="url" shortform="http://twitter.com/ev"><![CDATA[http://twitter.com/ev]]></fct:column>
    <fct:column><![CDATA[Evan Williams]]></fct:column>
    <fct:column><![CDATA[88]]></fct:column>
  </fct:row>
  <fct:row>
    <fct:column datatype="url" shortform="http://twitter.com/veen"><![CDATA[http://twitter.com/veen]]></fct:column>
    <fct:column><![CDATA[veen]]></fct:column>
    <fct:column><![CDATA[76]]></fct:column>
  </fct:row>
  <fct:row>
    <fct:column datatype="url" shortform="http://twitter.com/joshdura"><![CDATA[http://twitter.com/joshdura]]></fct:column>
    <fct:column><![CDATA[Josh Dura]]></fct:column>
    <fct:column><![CDATA[75]]></fct:column>
  </fct:row>
  <fct:row>
    <fct:column datatype="url" shortform="http://twitter.com/khoi"><![CDATA[http://twitter.com/khoi]]></fct:column>
    <fct:column><![CDATA[Khoi Vinh]]></fct:column>
    <fct:column><![CDATA[72]]></fct:column>
  </fct:row>
  <fct:row>
    <fct:column datatype="url" shortform="http://twitter.com/jkottke"><![CDATA[http://twitter.com/jkottke]]></fct:column>
    <fct:column><![CDATA[Jason Kottke]]></fct:column>
    <fct:column><![CDATA[72]]></fct:column>
  </fct:row>
  <fct:row>
    <fct:column datatype="url" shortform="http://twitter.com/anildash"><![CDATA[http://twitter.com/anildash]]></fct:column>
    <fct:column><![CDATA[anildash]]></fct:column>
    <fct:column><![CDATA[61]]></fct:column>
  </fct:row>
  <fct:row>
    <fct:column datatype="url" shortform="http://twitter.com/festmob"><![CDATA[http://twitter.com/festmob]]></fct:column>
    <fct:column><![CDATA[fest mob]]></fct:column>
    <fct:column><![CDATA[56]]></fct:column>
  </fct:row>
  <fct:row>
    <fct:column datatype="url" shortform="http://twitter.com/ekai"><![CDATA[http://twitter.com/ekai]]></fct:column>
    <fct:column><![CDATA[Eddie Codel]]></fct:column>
    <fct:column><![CDATA[56]]></fct:column>
  </fct:row>
  <fct:row>
    <fct:column datatype="url" shortform="http://twitter.com/gruber"><![CDATA[http://twitter.com/gruber]]></fct:column>
    <fct:column><![CDATA[John Gruber]]></fct:column>
    <fct:column><![CDATA[54]]></fct:column>
  </fct:row>
  <fct:row>
    <fct:column datatype="url" shortform="http://twitter.com/factoryjoe"><![CDATA[http://twitter.com/factoryjoe]]></fct:column>
    <fct:column><![CDATA[Twitter / factoryjoe]]></fct:column>
    <fct:column><![CDATA[53]]></fct:column>
  </fct:row>
  <fct:row>
    <fct:column datatype="url" shortform="http://twitter.com/zeldman"><![CDATA[http://twitter.com/zeldman]]></fct:column>
    <fct:column><![CDATA[Jeffrey Zeldman]]></fct:column>
    <fct:column><![CDATA[51]]></fct:column>
  </fct:row>
  <fct:row>
    <fct:column datatype="url" shortform="http://twitter.com/jasonsantamaria"><![CDATA[http://twitter.com/jasonsantamaria]]></fct:column>
    <fct:column><![CDATA[Jason Santa Maria]]></fct:column>
    <fct:column><![CDATA[51]]></fct:column>
  </fct:row>
  <fct:row>
    <fct:column datatype="url" shortform="http://twitter.com/biz"><![CDATA[http://twitter.com/biz]]></fct:column>
    <fct:column><![CDATA[Biz Stone]]></fct:column>
    <fct:column><![CDATA[51]]></fct:column>
  </fct:row>
  <fct:row>
    <fct:column datatype="url" shortform="http://twitter.com/laughingsquid"><![CDATA[http://twitter.com/laughingsquid]]></fct:column>
    <fct:column><![CDATA[laughingsquid]]></fct:column>
    <fct:column><![CDATA[49]]></fct:column>
  </fct:row>
  <fct:row>
    <fct:column datatype="url" shortform="http://twitter.com/vpieters"><![CDATA[http://twitter.com/vpieters]]></fct:column>
    <fct:column><![CDATA[Veerle Pieters]]></fct:column>
    <fct:column><![CDATA[47]]></fct:column>
  </fct:row>
  <fct:row>
    <fct:column datatype="url" shortform="http://twitter.com/adactio"><![CDATA[http://twitter.com/adactio]]></fct:column>
    <fct:column><![CDATA[Jeremy Keith]]></fct:column>
    <fct:column><![CDATA[45]]></fct:column>
  </fct:row>
  <fct:row>
    <fct:column datatype="url" shortform="http://twitter.com/Malarkey"><![CDATA[http://twitter.com/Malarkey]]></fct:column>
    <fct:column><![CDATA[Malarkey]]></fct:column>
    <fct:column><![CDATA[45]]></fct:column>
  </fct:row>
  <fct:row>
    <fct:column datatype="url" shortform="http://twitter.com/lloydi"><![CDATA[http://twitter.com/lloydi]]></fct:column>
    <fct:column><![CDATA[Ian Lloyd]]></fct:column>
    <fct:column><![CDATA[45]]></fct:column>
  </fct:row>
 </fct:result>
</fct:facets>

Looking up instances of a class: 

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>
  <text>Mike</text>
  <class iri="[foaf:Person]"/>
  <view type="list" limit="10" />
</query>

Produces the following response: 

<fct:facets xmlns:fct="http://openlinksw.com/services/facets/1.0/">
<fct:sparql>
   SELECT DISTINCT  ?s1 AS ?c1  
     WHERE { ?s1  ?s1textp      ?o1                                       . 
             ?o1  bif:contains  '"Mike"'                .
             ?s1  a             <http://xmlns.com/foaf/0.1/Person> 
           } 
     ORDER BY  DESC (<LONG::IRI_RANK> (?s1))  
     LIMIT     10 
</fct:sparql>
<fct:time>518</fct:time>
<fct:complete>yes</fct:complete>
<fct:timeout>0</fct:timeout>
<fct:db-activity> 304.3KR rnd  182.1KR seq      0P disk  7.596MB /  3.236K messages</fct:db-activity>
 <fct:result type="">
  <fct:row>
    <fct:column datatype="url" shortform="http://www.photojunkie.ca"><![CDATA[http://www.photojunkie.ca]]></fct:column>
    <fct:column><![CDATA[http://www.photojunkie.ca]]></fct:column>
  </fct:row>
  <fct:row>
    <fct:column datatype="url" shortform="dbpedia:Bruce_Springsteen"><![CDATA[http://dbpedia.org/resource/Bruce_Springsteen]]></fct:column>
    <fct:column><![CDATA[?????-?????<?????????'???????>???'???????-???????????????'?°???'???????????'??????????????]]></fct:column>
  </fct:row>
  <fct:row>
    <fct:column datatype="url" shortform="dbpedia:John_McCain"><![CDATA[http://dbpedia.org/resource/John_McCain]]></fct:column>
    <fct:column><![CDATA[???'???????§???????????>?????????'?+???'?¤??????]]></fct:column>
  </fct:row>
  <fct:row>
    <fct:column datatype="url" shortform="dbpedia:Miles_Davis"><![CDATA[http://dbpedia.org/resource/Miles_Davis]]></fct:column>
    <fct:column><![CDATA[?????????'?¤?????<???'???????>?????????'?¤?????????'?????'??]]></fct:column>
  </fct:row>
  <fct:row>
    <fct:column datatype="url" shortform="dbpedia:Phil_Collins"><![CDATA[http://dbpedia.org/resource/Phil_Collins]]></fct:column>
    <fct:column><![CDATA[????????'???????<?????>???'?????????????????'??]]></fct:column>
  </fct:row>
  <fct:row>
    <fct:column datatype="url" shortform="dbpedia:Brian_Wilson"><![CDATA[http://dbpedia.org/resource/Brian_Wilson]]></fct:column>
    <fct:column><![CDATA[?????-?????c???'?¤???'?????????????>???'?????'???????<???'????????]]></fct:column>
  </fct:row>
  <fct:row>
    <fct:column datatype="url" shortform="http://www.w3.org/Pe.../Berners-Lee/card#i"><![CDATA[http://www.w3.org/People/Berners-Lee/card#i]]></fct:col
umn>
    <fct:column><![CDATA[?????????'??????? ?????>???????????????????????????'????????????????????"]]></fct:column>
  </fct:row>
  <fct:row>
    <fct:column datatype="url" shortform="dbpedia:Jimmy_Page"><![CDATA[http://dbpedia.org/resource/Jimmy_Page]]></fct:column>
    <fct:column><![CDATA[???'???????????????????>?????????'?¤???'??]]></fct:column>
  </fct:row>
  <fct:row>
    <fct:column datatype="url" shortform="dbpedia:Carlos_Santana"><![CDATA[http://dbpedia.org/resource/Carlos_Santana]]></fct:column>
    <fct:column><![CDATA[???'?<?????<?????-???'???????>???'???????????'????????]]></fct:column>
  </fct:row>
  <fct:row>
    <fct:column datatype="url" shortform="dbpedia:Wayne_Gretzky"><![CDATA[http://dbpedia.org/resource/Wayne_Gretzky]]></fct:column>
    <fct:column><![CDATA[???'?????'?§???'?¤???????????>???'?°???????????"???'?-??????]]></fct:column>
  </fct:row>
 </fct:result>
</fct:facets>

Note: If the entire <text> element is missing, the FCT service will not add a bif:contains to the triple pattern. Thus it is possible to search for some property or class, etc. For example: 

<query>
  <property iri="[foaf:knows]">
    <view type="properties" limit="20" offset="0"/>
  </property>
</query>

is executed as: 

SELECT  ?s2p AS ?c1 
        COUNT (*) AS ?c2  
WHERE
   { 
     ?s1  <http://xmlns.com/foaf/0.1/knows>  ?s2  . 
     ?s2  ?s2p  ?s2o  . 
   } 
GROUP BY ?s2p 
ORDER BY DESC 2 
LIMIT 20

Choice of Labels

The Virtuoso Facets web service offers the feature of using label inferencing for better labels handling.

We use inference for labels called "facets". The inference is: 

-- The SPARUL statement for loading it into the Quad Store:
ttlp ('
@prefix  foaf:      <http://xmlns.com/foaf/0.1/>
@prefix  dc:        <http://purl.org/dc/elements/1.1/>
@prefix  rdfs:      <http://www.w3.org/2000/01/rdf-schema#>
@prefix  virtrdf:   <http://www.openlinksw.com/schemas/virtrdf#>
@prefix  geonames:  <http://www.geonames.org/ontology#>

rdfs:label     rdfs:subPropertyOf  virtrdf:label  .
dc:title       rdfs:subPropertyOf  virtrdf:label  .
foaf:name      rdfs:subPropertyOf  virtrdf:label  .
foaf:nick      rdfs:subPropertyOf  virtrdf:label  .
geonames:name  rdfs:subPropertyOf  virtrdf:label  . ', 
'xx', 'facets');


--Making the rule from the graph:
rdfs_rule_set ('facets', 'facets');

Example

  1. Go to http://lod.openlinksw.com/sparql
  2. Enter the following query in the text area: 

    DEFINE  output:valmode   'LONG' 
DEFINE  input:inference  'facets' 
SELECT * 
  WHERE
    { 
      ?s  virtrdf:label  ?o 
    }





  3. The found triples will be shown as a result:



WebService Interfaces

REST interface

The Virtuoso Facets web service provide following REST interface:

Service description
  • Endpoint: http://cname/fct/service or http://lod.openlinksw.com/fct/service
  • HTTP method: POST
  • Content-Type: MUST be 'text/xml'
  • The entity body must be XML document with top element 'query' as described above.
  • The request response namespace MUST be "http://openlinksw.com/services/facets/1.0"
Error conditions

All error conditions are reported via '<error>Error explanation</error>'

Files

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

Examples Using CURL program
Example 1
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 the 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"><![CDATA[http://bobdupuy.mlblogs.com/bobdupuy/2006/03/world_baseball__6.html]]></fct:column>
    <fct:column />
    <fct:column><![CDATA[<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"><![CDATA[http://bobdupuy.mlblogs.com/bobdupuy/2006/03/world_baseball__6.html]]></fct:column>
    <fct:column />
    <fct:column><![CDATA[<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>
Example 2
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>napoleon</text>
  <view type="text" limit="5" offset=""/>
</query>

Produces the following response: 

<fct:facets xmlns:fct="http://openlinksw.com/services/facets/1.0/">
<fct:sparql>
   SELECT  ?s1 AS ?c1,
           ( bif:search_excerpt 
             ( bif:vector 
               ( 'napoleon' ), 
               ?o1
             )
           ) AS ?c2, 
           ?sc, 
           ?rank 
     WHERE {
             {{ SELECT  ?s1, 
                        (?sc * 3e-1) AS ?sc, 
                        ?o1, 
                        (sql:rnk_scale (<LONG::IRI_RANK> (?s1))) AS ?rank  
                  WHERE { ?s1  ?s1textp      ?o1                             . 
                          ?o1  bif:contains  '"napoleon"'  
                               OPTION (score ?sc) 
                        }
                  ORDER BY  DESC (?sc * 3e-1 + sql:rnk_scale (<LONG::IRI_RANK> (?s1)))  
                  LIMIT     5
                  OFFSET    0 
              }}
            }
</fct:sparql>
<fct:time>3531</fct:time>
<fct:complete>yes</fct:complete>
<fct:timeout>0</fct:timeout>
<fct:db-activity>  23.1KR rnd  13.29KR seq  80.41KP disk  1.341MB /    472 messages</fct:db-activity>
 <fct:result type="text">
  <fct:row>
    <fct:column datatype="trank"><![CDATA[7.8]]></fct:column>
    <fct:column datatype="erank"><![CDATA[7.184050388930453]]></fct:column>
    <fct:column datatype="url" shortform="dbpedia:Napoleon_Dynamite"><![CDATA[http://dbpedia.org/resource/Napoleon_Dynamite]]></fct:column>
    <fct:column><![CDATA[Napoleon Wybuchowiec]]></fct:column>
    <fct:column><![CDATA[<span class="srch_xerpt"><b>Napoleon</b> Dynamite <b>Napoleon</b> Dynamite no original um filme de longa metragem de com dia baseado no curta...</span>]]></fct:column>
  </fct:row>
  <fct:row>
    <fct:column datatype="trank"><![CDATA[7.8]]></fct:column>
    <fct:column datatype="erank"><![CDATA[7.184050388930453]]></fct:column>
    <fct:column datatype="url" shortform="dbpedia:Napoleon_Dynamite"><![CDATA[http://dbpedia.org/resource/Napoleon_Dynamite]]></fct:column>
    <fct:column><![CDATA[Napoleon Wybuchowiec]]></fct:column>
    <fct:column><![CDATA[<span class="srch_xerpt"><b>Napoleon</b> Dynamite <b>Napoleon</b> Dynamite no original um filme de longa metragem de com dia baseado no curta...</span>]]></fct:column>
  </fct:row>
  <fct:row>
    <fct:column datatype="trank"><![CDATA[7.5]]></fct:column>
    <fct:column datatype="erank"><![CDATA[7.28072164871858]]></fct:column>
    <fct:column datatype="url" shortform="dbpedia:Charles_Napol%C3%A9on"><![CDATA[http://dbpedia.org/resource/Charles_Napol%C3%A9on]]></fct:column>
    <fct:column><![CDATA[Charles Napol???con Bonaparte, Duc de Montfort]]></fct:column>
    <fct:column><![CDATA[<span class="srch_xerpt">Charles <b>Napoleon</b> Bonaparte prins <b>Napoleon</b> f dd 19 oktober 1950 son till Louis <b>Napoleon</b> Bonaparte och...</span>]]></fct:column>
  </fct:row>
  <fct:row>
    <fct:column datatype="trank"><![CDATA[7.5]]></fct:column>
    <fct:column datatype="erank"><![CDATA[7.260916174007062]]></fct:column>
    <fct:column datatype="url" shortform="dbpedia:Napol%C3%A9o...%2C_Prince_Imperial"><![CDATA[http://dbpedia.org/resource/Napol%C3%A9on_Eug%C3%A8ne%2C_Prince_Imperial]]></fct:column>
    <fct:column><![CDATA[Napole????n Eugenio Luis Bonaparte]]></fct:column>
    <fct:column><![CDATA[<span class="srch_xerpt">Louis <b>Napoleon</b> Bonaparte <b>Napoleon</b> IV.</span>]]></fct:column>
  </fct:row>
  <fct:row>
    <fct:column datatype="trank"><![CDATA[6]]></fct:column>
    <fct:column datatype="erank"><![CDATA[8.727351287724161]]></fct:column>
    <fct:column datatype="url" shortform="dbpedia:1815"><![CDATA[http://dbpedia.org/resource/1815]]></fct:column>
    <fct:column><![CDATA[1815 ????????????]]></fct:column>
    <fct:column><![CDATA[<span class="srch_xerpt">... kes kuuta <b>Napoleon</b> Bonaparte julistautuu uudelleen Ranskan keisariksi. <b>Napoleon</b> Bonaparten satap iv inen keisarikunta Ranskassa Vuoden 1812 sota p ttyi Yhdysvaltain ja Ison...</span>]]></fct:column>
  </fct:row>
 </fct:result>
</fct:facets>

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 the same command as in the example for REST interface and here it uses 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"><![CDATA[http://bobdupuy.mlblogs.com/bobdupuy/2006/03/world_baseball__6.html]]></fct:column>
          <fct:column/>
          <fct:column><![CDATA[<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"><![CDATA[http://bobdupuy.mlblogs.com/bobdupuy/2006/03/world_baseball__6.html]]></fct:column>
          <fct:column/>
          <fct:column><![CDATA[<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>

Virtuoso Facets API for REST services

A full list of Facets API calls for REST services can be viewed here.

Related

Powered By Virtuoso