Author: fchrist
Date: Fri Jan 13 14:10:29 2012
New Revision: 1231082
URL: http://svn.apache.org/viewvc?rev=1231082&view=rev
Log:
STANBOL-456 Incrementally moving FactStore specification from IKS Wiki
Modified:
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/factstore/specification.mdtext
Modified:
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/factstore/specification.mdtext
URL:
http://svn.apache.org/viewvc/incubator/stanbol/site/trunk/content/stanbol/docs/trunk/factstore/specification.mdtext?rev=1231082&r1=1231081&r2=1231082&view=diff
==============================================================================
---
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/factstore/specification.mdtext
(original)
+++
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/factstore/specification.mdtext
Fri Jan 13 14:10:29 2012
@@ -160,160 +160,156 @@ creates two new facts. The first one of
Status: **Implemented**
-=== Query Interface ===
+## Query Interface ##
The query interface allows clients to query for facts and combination of facts
(reasoning). The JSON-LD query structure is inspired by SQL using SELECT FROM
[JOIN] WHERE constructs. Depending on the implementation the JSON-LD queries
may be transformed directly into valid SQL queries.
-==== Query for Facts of a Certain Type ====
+### Query for Facts of a Certain Type ###
-{|
- |valign="top"|Description:||Allows clients to query stored facts of a
specific type defined by the fact's schema. The clients specify the desired
fact plus an arbitrary number of entities that play some role in the fact.
- |-
- |Path:||/factstore/query
- |-
- |Method:||POST with data type application/json returns application/json
- |-
- |valign="top"|Data:||The query is specified by a JSON-LD object in the
payload of the request. The query defines a "select" to specify the desired
type of result to be returned in the result set. The "from" part specifies the
fact type to query and the "where" clause specifies constraints to be
fulfilled.<br>
-Note:For the moment constraints only support the equals "=" relation. There
may be more relations like ">" in future versions of this specification. If
there is more than one constraint all constraints are concatenated by "AND".
- |-
- |valign="top"|Example 1:||POST /factstore/query<br>
-with the following data"
-
- {
- "@context" : {
- "iks" : "http://iks-project.eu/ont/";
- },
- "select" : [ "person" ],
- "from" : "iks:employeeOf",
- "where" : [
- {
- "=" : {
- "organization" : { "@iri" : "http://uni-paderborn.de"; }
- }
- }
- ]
- }
+Allows clients to query stored facts of a specific type defined by the fact's
schema. The clients specify the desired fact plus an arbitrary number of
entities that play some role in the fact.
-<nowiki>returns the list of all persons participating in the fact of type
http://iks-project.eu/ont/employeeOf where the organization is
http://uni-paderborn.de. The result is sent back in JSON-LD format with the
result set specified by the select clause.</nowiki>
+Path: /factstore/query
- {
- "@subject" : [
- {
- "@subject" : "_bnode1",
- "PERSON" : "http://upb.de/persons/gengels";
- },
- {
- "@subject" : "_bnode2",
- "PERSON" : "http://upb.de/persons/ssauer";
+Method: POST with data type application/json returns application/json
+
+Data: The query is specified by a JSON-LD object in the payload of the
request. The query defines a "select" to specify the desired type of result to
be returned in the result set. The "from" part specifies the fact type to query
and the "where" clause specifies constraints to be fulfilled.
+
+_Note_: For the moment constraints only support the equals "=" relation. There
may be more relations like ">" in future versions of this specification. If
there is more than one constraint all constraints are concatenated by "AND".
+
+Example 1: POST /factstore/query with the following data
+
+ {
+ "@context" : {
+ "iks" : "http://iks-project.eu/ont/";
},
+ "select" : [ "person" ],
+ "from" : "iks:employeeOf",
+ "where" : [
+ {
+ "=" : {
+ "organization" : { "@iri" : "http://uni-paderborn.de"; }
+ }
+ }
+ ]
+ }
+
+returns the list of all persons participating in the fact of type
http://iks-project.eu/ont/employeeOf where the organization is
http://uni-paderborn.de. The result is sent back in JSON-LD format with the
result set specified by the select clause.
+
{
- "@subject" : "_bnode3",
- "PERSON" : "http://upb.de/persons/bnagel";
- },
+ "@subject" : [
+ {
+ "@subject" : "_bnode1",
+ "PERSON" : "http://upb.de/persons/gengels";
+ },
+ {
+ "@subject" : "_bnode2",
+ "PERSON" : "http://upb.de/persons/ssauer";
+ },
+ {
+ "@subject" : "_bnode3",
+ "PERSON" : "http://upb.de/persons/bnagel";
+ },
+ {
+ "@subject" : "_bnode4",
+ "PERSON" : "http://upb.de/persons/fchrist";
+ }
+ ]
+ }
+
+If there is only one entry in the result set, this would be returned as
follows.
+
{
- "@subject" : "_bnode4",
"PERSON" : "http://upb.de/persons/fchrist";
}
- ]
- }
-<nowiki>If there is only one entry in the result set, this would be returned
as follows.</nowiki>
+Status: **Example 1 is implemented**.
+
+Example 2: GET /factstore/query?q= with the following data as the request
parameter "q"
- {
- "PERSON" : "http://upb.de/persons/fchrist";
- }
- |-
- |valign="top"| Status: || Example 1 is implemented and should work in latest
[http://incubator.apache.org/stanbol/ Apache Stanbol] versions.
- |-
- |valign="top"| Example 2: || GET /factstore/query?q=<br>
-with the following data as the request parameter "q"
- {
- "@context" : {
- "iks" : "http://iks-project.eu/ont/";
- },
- "select" : [
- "person.name", "person.email"
- ],
- "from" : "iks:employeeOf",
- "where" : [
{
- "=" : {
- "organization" : { "@iri" : "http://upb.de"; }
- }
+ "@context" : {
+ "iks" : "http://iks-project.eu/ont/";
+ },
+ "select" : [
+ "person.name", "person.email"
+ ],
+ "from" : "iks:employeeOf",
+ "where" : [
+ {
+ "=" : {
+ "organization" : { "@iri" : "http://upb.de"; }
+ }
+ }
+ ]
}
- ]
- }
-<nowiki>returns a list with names and e-mail addresses of all persons
participating in the fact of type http://iks-project.eu/ont/employeeOf where
the organization is http://upb.de. The result is sent back in JSON-LD format
with the result set specified by the select clause.</nowiki>
+returns a list with names and e-mail addresses of all persons participating in
the fact of type http://iks-project.eu/ont/employeeOf where the organization is
http://upb.de. The result is sent back in JSON-LD format with the result set
specified by the select clause.
- {
- "resultset": [
- { "person.name" : "Gregor Engels",
- "person.email": "[email protected]" },
- { "person.name" : "Stefan Sauer",
- "person.email": "[email protected]" },
- { "person.name" : "Benjamin Nagel",
- "person.email": "[email protected]" },
- { "person.name" : "Fabian Christ",
- "person.email": "[email protected]" }
- ]
- }
- |-
- |Status || Implemention in progress.
- |}
-
-==== Query for Combinations of Facts ====
-{|
- |Description:||Allows clients to query for combinations of facts.
- |-
- |Path:||/factstore/query?q=
- |-
- |Method:||GET with data type application/json returns application/json
- |-
- |Data:||The query is specified by a JSON-LD object in request parameter "q"
of the request. The query defines a "select" to specify the desired type of
result to be returned in the result set. Instead of using a "from" part this
type of query supports joins over facts using the "join" field. The "join"
field specifies which facts are joined by specifying the elements of the facts
that are evaluated to be equal during the join. The "where" clause specifies
constraints over the join to be fulfilled.<br>
-Note: For the moment constraints only support the equals "=" relation. There
may be more relations like ">" in future versions of this specification. If
there is more than one constraint all constraints are concatenated by "AND".
- |-
- |valign="top"|Example:||GET /factstore/query?q=<br>
-with the following request data in request parameter "q"
-
- {
- "@context" : {
- "iks" : "http://iks-project.eu/ont/";
- },
- "select": [
- "iks:friendOf.friend.name"
- ],
- "join" : {
- "iks:employeeOf.person" : "iks:friendOf.person"
- },
- "where" : [
- {
- "=" : {
- "iks:employeeOf.organization" : {
- "@iri" : "http://upb.de";
- }
- }
- },
{
- "=" : {
- "iks:friendOf.friend.city" : "Paderborn"
- }
+ "resultset": [
+ { "person.name" : "Gregor Engels",
+ "person.email": "[email protected]" },
+ { "person.name" : "Stefan Sauer",
+ "person.email": "[email protected]" },
+ { "person.name" : "Benjamin Nagel",
+ "person.email": "[email protected]" },
+ { "person.name" : "Fabian Christ",
+ "person.email": "[email protected]" }
+ ]
+ }
+
+Status: **NOT Implemented, yet.**
+
+### Query for Combinations of Facts ###
+
+Allows clients to query for combinations of facts.
+
+Path: /factstore/query?q=
+
+Method: GET with data type application/json returns application/json
+
+Data: The query is specified by a JSON-LD object in request parameter "q" of
the request. The query defines a "select" to specify the desired type of result
to be returned in the result set. Instead of using a "from" part this type of
query supports joins over facts using the "join" field. The "join" field
specifies which facts are joined by specifying the elements of the facts that
are evaluated to be equal during the join. The "where" clause specifies
constraints over the join to be fulfilled.
+
+_Note_: For the moment constraints only support the equals "=" relation. There
may be more relations like ">" in future versions of this specification. If
there is more than one constraint all constraints are concatenated by "AND".
+
+Example: GET /factstore/query?q= with the following request data in request
parameter "q"
+
+ {
+ "@context" : {
+ "iks" : "http://iks-project.eu/ont/";
+ },
+ "select": [
+ "iks:friendOf.friend.name"
+ ],
+ "join" : {
+ "iks:employeeOf.person" : "iks:friendOf.person"
+ },
+ "where" : [
+ {
+ "=" : {
+ "iks:employeeOf.organization" : {
+ "@iri" : "http://upb.de";
+ }
+ }
+ },
+ {
+ "=" : {
+ "iks:friendOf.friend.city" : "Paderborn"
+ }
+ }
+ ]
}
- ]
- }
-<nowiki>
-will return a list of names of all the friends living in Paderborn of the
employees of the University of Paderborn. The result in JSON-LD format would
look like the following.</nowiki>
-
- {
- "@context" : {
- "iks" : "http://iks-project.eu/ont/";
- },
- "resultset": [
- { "iks:friendOf.friend.name" : "Schmidt" },
- { "iks:friendOf.friend.name" : "Meier" },
- { "iks:friendOf.friend.name" : "Schneider" },
- { "iks:friendOf.friend.name" : "Schuster" }
- ]
- }
-|}
+will return a list of names of all the friends living in Paderborn of the
employees of the University of Paderborn. The result in JSON-LD format would
look like the following.
+
+ {
+ "@context" : {
+ "iks" : "http://iks-project.eu/ont/";
+ },
+ "resultset": [
+ { "iks:friendOf.friend.name" : "Schmidt" },
+ { "iks:friendOf.friend.name" : "Meier" },
+ { "iks:friendOf.friend.name" : "Schneider" },
+ { "iks:friendOf.friend.name" : "Schuster" }
+ ]
+ }
