Differences

This shows you the differences between two versions of the page.

--- docs:userman [2017/12/04 16:12]
kkutt [SPARQL queries]
+++ docs:userman [2022/03/23 16:59] (current)
@@ Line 1: / Line 1: @@
+====== Loki Manual - User manual ======
+===== Editing =====
+==== Defining Semantic data ====
+There are three main methods of semantic annotations used in Semantic MediaWiki that are supported in Loki:
+  * categories - a simple form of annotation that allows users to classify pages. To state that article (Wiki page) belongs to the category ''country'' it is necesary to write
+<code>[[category:country]]</code>
+  * relations - there is a possibility to describe relationships between two Wiki pages. For example there is a relation ''capital_of'' between ''cities:warsaw'' and coutries:poland. To express this it is necesary to edit the page ''countries:warsaw'' and add
+<code>[[capital of::countries:poland]]</code>
+  * attributes - allows to specify relationships of Wiki pages to things that are not Wiki pages. For example, one can state that Wiki page ''namespace:page'' was created at April 22 2009 by writing
+<code>[[created:=April 22 2009]]</code>
+It is possible to assign one value to multiple relations or attributes in one annotation, thus:
+<code smw>Warsaw is the capital city of [[capital of::located in::countries:poland]]
+inhabited by [[inhabited by:=population:=1 800 000]] people. </code>
+The other functionality allows users to decide, how an annotation should be displayed on the page. It is done by defining an lternative text for the annotation using the pipe symbol (|). If no alternative text is specified, the annotation value (default text) is isplayed. If the alternative text is a single space, no value is displayed. For example, code:
+<code smw>Warsaw is located in [[located in::countries:poland|Poland]]. It's inhabited
+by about [[population:=1 800 000|1.8 mln]] people. [[page created:=2011-02-14| ]]</code>
+will be displayed as:
+Warsaw is located in [[located in::countries:poland|Poland]]. It's inhabited by about [[population:=1 800 000|1.8 mln]] people.
+[[page created:=2011-02-14| ]]
+All attributes are displayed as plain text, relations as links to the related page and categories as links to the selected category's special page.
+==== Special pages ====
+Special pages are pages containing metadata informations, namely pages describing categories, relations and attributes used in the wiki with information about their usages in the wiki. Loki supports these pages, but it doesn't automatically create them - they have to be created manually. Special pages supported in Loki are:
+  * [[special:categories]] - page listing all categories used in the wiki.
+  * [[special:relations]] - page listing all relations used in the wiki.
+  * [[special:attributes]] - page listing all attributes used in the wiki.
+Namespaces for these pages are: for categories - ''special:category'', for relations - ''special:relation'' and for attributes - ''special:attribute''.
+Each property (including categories) can be a subproperty of another property of the same type (eg. a relation cannot be a subproperty of an attribute). This is set on the subproperty's special page:
+  * for categories:
+<code smw>
+Category is a subcategory of [[category:another_category]].
+</code>
+  * for relations:
+<code smw>
+Relation is a subrelation of [[subrelation of::another_relation]].
+</code>
+  * for attributes:
+<code smw>
+Attribute is a subattribute of [[subattribute of:=another_attribute]].
+</code>
+  * for compatibility with SMW syntax, relations and attributes can use the construction ''subproperty of::'' to set their superior properties. This construction is translated into a subrelation or a subattribute depending on the current page namespace. Example use:
+<code smw>
+Property is a [[subproperty of::another_property]]
+</code>
+==== Prolog in DokuWiki====
+The simplest way to use Prolog in DokuWiki is to place code between ''<pl> ... </pl>'' tags. Code will be interpreted and it will appear as a result of given goal. It can be explained by the following example:
+<code><pl goal="woman(X),write(X),nl,fail.">
+woman(kate).
+woman(alice).
+woman(anna).
+man(john).
+man(tom).
+</pl></code>
+Result of given example:
+<pl goal="woman(X),write(X),nl,fail.">
+woman(kate).
+woman(alice).
+woman(anna).
+man(john).
+man(tom).
+</pl>
+It is important to remember that adding ''write(X)'' string to the goal shows a result. When more than one result is expected, it is necesary to add ''nl,fail''.
+There are three ways to deliver Prolog code:
+  * As a code placed between tags ''<pl> ... </pl>''
+  * As a DokuWiki file with code ''<pl file="manespace:file.pl"></pl>''
+  * As url to external file with Prolog code ''<pl url="http://example.page.com/file.pl"></pl>''
+===== Searching interfaces =====
+==== Ask queries ====
+Loki supporst almost full functionality for ask queries known from SMW. Ask queries allow to define pages search conditions and display results. Each query contain list of arguments seperated with vertical line (''|''). First condition should be the criteria for wanted pages. Form of the search criteria:
+<code>[[condition1]] [[condition2]] [[condition3]]</code>
+This is conjunction of conditions. To use alternative, it is necessary to insert ''OR'' between conditions.
+<code>[[condition1]] OR [[condition2]]</code>
+Each condition determines the value of property which searched page must contain. Using empty strings for values is allowed.
+Conditions can contain alternative values:
+<code>{{#ask: [[property::value1||value2]] }}</code>
+which is equivalent to:
+<code>{{#ask: [[property::value1]] OR [[property::value2]] }}</code>
+Value of the condition can be sub-query:
+<code>{{#ask: [[property::<q>[[property1::value]] [[category:cat1]]</q>]] }}</code>
+Each sub-query can contain unlimited amount of sub-queries.
+There is special kind of queries in Loki - property chains. Properity chains can be used to obtain simpler notation. For example :
+<code>[[rel1::<q>[[rel2::[[rel3::value]]</q>]]</q>]]</code>
+can be replaced by:
+<code>{{#ask: [[rel1.rel2.rel3::value]] }}</code>
+Other query arguments are connected with displaying results. Optional arguments can consist of two types of data: columns to be displayed and additional options.
+First group contains names preceded by a question mark. Example:
+<code>
+{{#ask: [[category:city]]
+      | ?located in }}
+</code>
+There is possibility to specify collumn names.
+<code>{{#ask: [[category:city]]
+      | ?located in=Localisation}}</code>
+For categories, a specific category name can be selected to single out pages belonging to the given category. If the page belongs to the selected category, an ”X” sign will be put in the appropriate field. Example:
+<code>
+{{#ask: [[category:city]]
+      | ?category:city=City
+      | ?category:village=Village }}</code>
+Result of this example:
+{{#ask: [[category:city]]
+      | ?category:city=City
+      | ?category:village=Village }}
+The other kind of optional arguments of Ask queries are additional options. Loki supports most of the options used in Semantic MediaWiki. Those options are displayed in table below:
+^ Name     ^ Allowed values       ^ Description          ^
+|''format''| Avaliable options are listed below this table | defines the output format of the query results |
+|''limit''| non-negative integer | Maximum amount of displayed results|
+|''offset''| positive integer | Results which number will be lower then ''offset'' will not be displayed|
+|''sort''| names of displayed columns |names of columns by which the results should be sorted, separated by commas|
+|''order''|''asc'', ''ascending'', desc, ''descending'', ''reverse'', ''random'' |Sort order, seperated by commas. Default: ''asc''|
+|''headers''| ''show'', ''hide'' | specifies whether the column headers should be shown. Default: ''show''|
+|''mainlabel''| text | text to be used as the main result column header. Default: empty|
+|''link''| ''all'', ''subject'', ''none'' |specifies which  elements of results should be displayed as links. Atributes always are displayed as a text. Default: all|
+|''default''| text | text written when no results found|
+|''intro''| text | text written before the displayed results|
+|''outro''| text | text written after the displayed results|
+|''step''| text |concerns only ''list'' and ''csv'' formats. Defines result separator. Default: '','' (comma)|
+Correct values for ''format'' parameter:
+  * ''table'' - default format. An HTML table.
+  * ''broadtable'' - a page-wide HTML table.
+  * ''ul'' - unordered list. Additional properties written in parentheses and separated by commas.
+  * ''ol'' - ordered list. Additional properties written in parentheses and separated by commas.
+  * ''list'' - a list. Results are separated by a string defined by the ”sep” option (default ”,”). Additional properties written in parentheses and separated by commas.
+  * ''count'' - a single number depicting the number of results.
+  * ''csv'' - results exported to a csv (Comma Separated Values) file. Link to the file is displayed on the page. Field separator (”,” by default) can be set in the ”sep” option.
+  * ''debug'' - instead of query results, debug information is displayed on the page. This includes: the original query, Prolog goal used to find the matching pages, list of properties to be displayed, values of additional options and the number of results returned by the query.
+===== Semantic Web =====
+==== SPARQL queries ====
+Loki supports a limited version of SPARQL. SELECT, ASK and DESCRIBE queries are supported. Full wiki semantic data is always used as datasource. Datatypes are not supported - every literal is a string. Full documentation of SPARQL language is avaliable for example on W3 website (http://www.w3.org/TR/rdf-sparql-query/). SPARQL queries can be asked inside wiki pages: they are written between Loki prolog tags (''<pl>...</pl>''), with ''format=sparql'' option or can be asked using SPARQL Endpoint under ''<nowiki>http://youwiki-address/sparql/</nowiki>'' address (e.g. SPARQL Endpoint for this wiki: [[http://loki.ia.agh.edu.pl/wiki/sparql/]])
+SPARQL queries consist of:
+  * PREFIX list (''PREFIX ns : <URL>'') - Can be empty.
+  * Query type - At this moment SELECT, ASK and DESCRIBE is avaliable
+  * List of variables (or constants). For SELECT query it will be selection of columns. For DESCRIBE - list of pages that will be described .
+  * Search conditions. In this part there is possible to insert OPTIONAL block (not obligatory conditions) or FILTER element (additional conditions)
+  * additional options: ORDER BY, LIMIT, OFFSET.
+FILTER list supported in Loki:
+  * ''isIRI()'', ''isURI()'' - checks whether a given variable is a page.
+  * ''isLiteral()'' - check whether a given variable is a literal. Category names are treated as literals.
+  * ''samePred(x,y)'' - checks whether two predicates are the same. Uses the "''=''" opertator in Prolog.
+  * ''='', ''!='', ''>='', ''<='', ''>'', ''<'' - compare two values, all comparisons are done alphabetically.
+=== SELECT queries ===
+The result of a SELECT query is displayed as an HTML table.
+Example SELECT query:
+<code>
+<pl format="sparql">
+PREFIX wiki:   <>
+SELECT ?title ?genre ?author
+WHERE
+  {
+     ?book wiki:genre ?genre.
+     ?book wiki:title ?title.
+     ?book wiki:author ?author.
+     FILTER (?genre!=bookstore:genre:handbook)
+  }
+ORDER BY INC(?title)
+LIMIT 5
+</pl>
+</code>
+This query will return table containing title, author and genre of all books which genre is different than handbook. Only 5 results sorted alphabetically :
+<pl format="sparql">
+PREFIX wiki:   <>
+SELECT ?title ?genre ?author
+WHERE
+  {
+     ?book wiki:genre ?genre.
+     ?book wiki:title ?title.
+     ?book wiki:author ?author.
+     FILTER (?genre!=bookstore:genre:handbook)
+  }
+ORDER BY INC(?title)
+LIMIT 5
+</pl>
+=== ASK queries ===
+ASK queries determine whether a result exists. It returns either "''yes''" or "''no''". ORDER BY, LIMIT and OFFSET do not apply here. Example query:
+<code plwiki>
+<pl format="sparql">
+PREFIX wiki: <>
+ASK {
+        ?book wiki:genre ?genre.
+        FILTER ( ?genre!=bookstore:genre:horror)
+}
+</pl>
+</code>
+This query will return the answer to the question: "Are there any books which genre isn't horror?". Answer :
+<pl format="sparql">
+PREFIX wiki: <>
+ASK {
+        ?book wiki:genre ?genre.
+        FILTER ( ?genre!=bookstore:genre:horror)
+}
+</pl>
+Example query 2:
+<code>
+<pl format="sparql">
+PREFIX wiki: <>
+ASK {
+        ?book wiki:genre ?genre.
+        FILTER ( ?genre==bookstore:genre:thriller)
+}
+</pl>
+OR the same query with the use of direct URI
+<pl format="sparql">
+PREFIX wiki: <>
+ASK {
+        ?book wiki:genre wiki:bookstore:genre:thriller.
+}
+</pl>
+</code>
+"Are there any books which genre is thriller?". Answer :
+<pl format="sparql">
+PREFIX wiki: <>
+ASK {
+        ?book wiki:genre ?genre.
+        FILTER ( ?genre==bookstore:genre:thriller)
+}
+</pl>
+=== DESCRIBE queries ===
+DESCRIBE queries return all semantic informations about pages complying with the query criteria, written in TURTLE (http://www.w3.org/TeamSubmission/turtle/) format. ORDER BY, LIMIT and OFFSET do not apply. Example query:
+<code>
+<pl format="sparql">
+PREFIX wiki: <>
+DESCRIBE ?aktor
+WHERE {
+  ?aktor a "aktor" ;
+         wiki:plec "M" .
+  ?film a "film" ;
+        wiki:rola_glowna ?aktor ;
+        wiki:wytwornia <wytwornie:mgm> ;
+        wiki:rok_produkcji ?rok .
+ FILTER (?rok >= "1950" && ?rok <="1954")
+}
+</pl>
+</code>
+Query returns actors who plays major role in musicals Metro-Goldwyn-Mayer in years 1959 - 1954.
+<pl format="sparql">
+PREFIX wiki: <>
+DESCRIBE ?aktor
+WHERE {
+  ?aktor a "aktor" ;
+         wiki:plec "M" .
+  ?film a "film" ;
+        wiki:rola_glowna ?aktor ;
+        wiki:wytwornia <wytwornie:mgm> ;
+        wiki:rok_produkcji ?rok .
+ FILTER (?rok >= "1950" && ?rok <="1954")
+}
+</pl>
+==== Export to RDF ====
+Basic assumption of Loki is ability to storage and process semantic knowledge. For this reason this is very important to allow transfering knowledge from one system to another. For this purpose Semantic Web standards such as RDF, OWL or SPARQL were created. Every Loki page can be exported to a RDF/XML file. It can bo done by opening the page in the ''exportrdf'' mode. One can do this by either adding the action ''do=exportrdf'' to the page URL or by clicking the ''Export to RDF'' button displayed on the bottom of each page.
+The generated RDF/XML file consists of three main parts. The first part contains description of the exported page. The second part contains optional related pages data. This data includes descriptions of pages related to the exported page (determined by the wiki_relation predicate). The number of levels of related pages to be exported (default one - only the selected page is exported) is set by the PlWiki ''rdfexport_maxlevels'' option in **DokuWiki settings**. The third part contains descriptions of all ontology elements used in first two parts, along with their superior elements.
+===== Debug functions =====
+Debugging is a very useful function for user. It can help in the analysis of errors and solving problems. Loki supports debugging Prolog code.
+=== STDERR redirection ===
+Loki allows redirection of the standard error stream to display or save messages which are genereted by the SWI-Prolog engine. It is possible by using ''msgerr'' parameter in Prolog tags. There are three values avaliable for this parameter:
+  * ''ignore'' - default option - There are no error messages displayed or saved in the system. All error messages are redirected to /dev/null
+  * ''display'' - Error messages are displayed on the wiki page
+Example use:
+<code><pl goal="invalid_goal" scope="*" msgerr="display"></pl></code>
+Example how it look like on the wiki page :
+<code>ERROR: /geist/vhosts/loki_ia_agh_edu_pl/www/lokidev/lib/plugins/tmp/lokidokuwiki.code16d52847503c57b5d2592e2e52a31e8c:415:0: Syntax error: Operator expected
+ERROR: /geist/vhosts/loki_ia_agh_edu_pl/www/lokidev/lib/plugins/tmp/lokidokuwiki.code16d52847503c57b5d2592e2e52a31e8c:418:0: Syntax error: Operator expected
+ERROR: /geist/vhosts/loki_ia_agh_edu_pl/www/lokidev/lib/plugins/tmp/lokidokuwiki.code16d52847503c57b5d2592e2e52a31e8c:420:0: Syntax error: Operator expected
+ERROR: /geist/vhosts/loki_ia_agh_edu_pl/www/lokidev/lib/plugins/tmp/lokidokuwiki.code16d52847503c57b5d2592e2e52a31e8c:426:0: Syntax error: Operator expected
+ERROR: /geist/vhosts/loki_ia_agh_edu_pl/www/lokidev/lib/plugins/tmp/lokidokuwiki.code16d52847503c57b5d2592e2e52a31e8c:428:0: Syntax error: Operator expected
+ERROR: /geist/vhosts/loki_ia_agh_edu_pl/www/lokidev/lib/plugins/tmp/lokidokuwiki.code16d52847503c57b5d2592e2e52a31e8c:431:0: Syntax error: Operator expected
+ERROR: /geist/vhosts/loki_ia_agh_edu_pl/www/lokidev/lib/plugins/tmp/lokidokuwiki.code16d52847503c57b5d2592e2e52a31e8c:500:59: Syntax error: String too long (see style_check/1)
+ERROR: Prolog initialisation failed: ERROR: ignore/1: Undefined procedure: invalid_goal/0 </code>
+=== Tracing predicates ===
+PlWiki uses the non-interactive version of Prolog trace predicate to display debug information on the wiki page. It can be done by using the Prolog tag ”trace” attribute, with a comma separated list of predicate names as its value. Example use:
+<code><pl scope="*" goal="woman(X), write(X), nl, fail" trace="woman,man"></pl></code>
+Result of this example on the wikipage:
+<code>
+T Call: (6) woman(_G624)
+T Exit: (6) woman(kate)
+kate
+T Redo: (6) woman(_G624)
+T Exit: (6) woman(alice)
+alice
+T Redo: (6) woman(_G624)
+T Exit: (6) woman(anna)
+anna
+</code>

Logic in wiki

User Tools

Site Tools

Differences

Page Tools