Knowledge - Document - Query
- andrew johnston (Unlicensed)
/knowledge/document/query/{community-ids}?<parameters, see below> (GET)
/knowledge/document/query/{community-ids} (POST)
This is the most important API call the platform provides. It takes in a complex query object that controls what input sources are used, what information is desired, how scoring should be performed, and what form the returned information should take.
Authentication
Required, see Auth - Login. There are various exceptions for RSS output
Arguments
community-ids (required)
Community ID, or IDs (comma-separated), or community ID - regex to control which sources the query will use. Obviously the logged-in user must have access rights to those communities. A user's communities can be viewed using the "person/get" API call
Parameters/Basic Usage
The parameters that can be sent in the API call encompass the available query terms, scoring parameters, input options, and output options. These parameters are featured in the examples on this page, which cover query basics.
An in depth definition of the query terms and options along with usage guidelines and best practices is provided in the Developer Guides and Tutorials.
The remainder of this section provides some top level documentation.
Query Basics
The query request is represented by the following (top level) JSON object:
{
"qt": [ { ... } ],
"expandAlias": false, // See under "entity aliasing" above
"logic": string, // see query object above
"raw": { ... },
"input": { ... },
"score": { ... },
"output": { ... },
"explain": boolean // (optional, if present and true then each document has an "explain" field added, see below)
}
There are 3 ways to send this JSON object to the REST endpoint (see examples below):
- "POST" the JSON object to the URL described above (note that the "contentType" and "Accept" headers in the request field may need to be set to
"application/JSON"- eg to use the AS3 HTTPService) - Perform a "GET" to the URL described above, with the
"json="parameter set to a URL-encoded single-line representation of the JSON object - Perform a "GET" to the URL described above, with the different non-null JSON terms in the object above turned into individual URL parameters using the dot notation, eq
"&qt[0].etext="exact text"&output.docs.enable=true"(see examples below).
Note that the Widget API also allows visualization widgets to read, modify, and send these query objects to the server. In this case only the JSON object is required, the transport is handled by the framework and the community set cannot be changed.
The optional "explain" boolean is (primarily) a diagnostic aid that adds the elasticsearch explain object to each returned document (embedded as JSON inside a field called "explain").
project_id (optional): the id of a share of type "infinite_project_config", this will filter the query to only search on communities/sources active in this project. See projects documentation for more information. TODO add link
Examples
Queries can be made from the command-line or a URL browser in a few different ways:
#bash> curl -XPOST 'http://infinite.ikanow.com/api/knowledge/document/query/4e0c7e99eb5af0fbdcfbf697' -d '{
"qt": [
{
"etext": "BBC "
}
],
"score": {
"numAnalyze": 1000,
"sigWeight": 67,
"relWeight": 33
},
"logic": "1",
"output": {
"format": "json",
"docs": {
"facts": true,
"eventsTimeline": false,
"enable": true,
"geo": true,
"ents": true,
"numReturn": 100,
"summaries": true,
"events": true,
"skip": 0
},
"aggregation": {
"factsNumReturn": 100,
"sourceMetadata": 20,
"geoNumReturn": 100,
"eventsNumReturn": 100,
"entsNumReturn": 100,
"timesInterval": "1w",
"sources": 20
}
}
}'
#bash> curl -XPOST 'http://infinite.ikanow.com/api/knowledge/document/query/4e0c7e99eb5af0fbdcfbf697?qt[0].etext="BBC"&input.tags="news"&score.sigWeight=33&output.aggregation.factsNumReturn=100'
#bash> curl -XPOST 'http://infinite.ikanow.com/api/knowledge/document/query/4e0c7e99eb5af0fbdcfbf697?json='{"qt"%3A[{"etext"%3A"BBC "}]%2C"logic"%3A"1"%2C"output"%3A{"aggregation"%3A{"factsNumReturn"%3A100%2C"sourceMetadata"%3A20%2C"geoNumReturn"%3A100%2C"eventsNumReturn"%3A100%2C"entsNumReturn"%3A100%2C"timesInterval"%3A"1w"%2C"sources"%3A20}%2C"format"%3A"rss"}}'
Note that with these last 2, the URL could also be pasted into the URL bar of a browser (assuming a tab in that browser had acquired a cookie via a log-in call).
Accessing the query from within ActionScript is also a common operation (although note that the main GUI and the module plugins provide an encapsulated version of this service already):
private function buildQueryRequest(communityIdList:String, queryObj:Object):void
{
var service:mx.rpc.http.mxml.HTTPService = new mx.rpc.http.mxml.HTTPService();
service.method = "POST";
var header:Object=new Object();
header["Accept"] = "application/json";
service.contentType = "application/json";
service.headers = header;
service.url = BASE_URL + "knowledge/document/query/" + communityIdList;
service.addEventListener(ResultEvent.RESULT, onQuerySuccess);
service.addEventListener(FaultEvent.FAULT, onQueryFailure);
service.send(JsonEncoder.encode(queryObj));
}
private function onQuerySuccess(event:ResultEvent):void
{
// Handle a successful query
}
private function onQueryFailure(event:ResultEvent):void
{
// Handle a query failure, see below
}
Perhaps more useful is this code fragment showing how to access the query API call from Javascript, eg for lighter weight uses of the platform. For the purposes of the example below illustrates how to use jQuery to call the API using both a 'GET' and 'POST'. For more information on create data visualizations using AJAX, jQuery and Protovis or d3.js check out our blog.
The example illustrates how to use jQuery.ajax() to invoke a AJAX call using a 'GET' request. Upon success you can then process the response.
$.ajax( {
type:'GET',
url:'http://infinite.ikanow.com/api/knowledge/document/query/4e0c7e99eb5af0fbdcfbf697',
data:'qt[0]="BBC"&input.tags="news"&score.sigWeight=33&output.aggregation.factsNumReturn=100'
dataType: 'json',
success:function(response) {
// Logic Processing
}
})
The example illustrates how to use jQuery.post() to invoke a AJAX call using a 'POST' request. Upon success you can then process the response.
$.ajax({
type: 'POST',
url: 'http://infinite.ikanow.com/api/knowledge/document/query/4e0c7e99eb5af0fbdcfbf697',
data: '{
"qt":[
{
"etext": "BBC"
}
],
"score": {
"numAnalyze": 1000,
"sigWeight": 67,
"relWeight": 33
},
"qtOptions": null,
"logic": "1",
"output": {
"format": "json",
"docs": {
"facts": true,
"eventsTimeline": false,
"enable": true,
"geo": true,
"ents": true,
"numReturn": 100,
"summaries": true,
"events": true,
"skip": 0
},
"aggregation": {
"factsNumReturn": 100,
"sourceMetadata": 20,
"geoNumReturn": 100,
"eventsNumReturn": 100,
"entsNumReturn": 100,
"timesInterval": "1w",
"sources": 20
}
}
}',
dataType: 'json',
success:function(response) {
// Logic Processing
}
});
Error Response
Currently the error responses are fairly basic:
Authentication error (normally means that you are not logged in):
{ "response": { "action": "Cookie Lookup", "success": false, "message": "Cookie session expired or never existed, please login first", "time": 0 } }All other errors:
{ "response": { "action": "Query" "success": false "message": "Unknown query error" "time": 0 } }Typical candidates for "all other errors" include:
- Incorrect or unauthorized community ID strings
- Syntax errors in the JSON or "logic" field
Note that future releases will provide better error reporting.
Related Documentation:
An in depth definition of the query terms and options along with usage guidelines and best practices is provided in the Developer Guides and Tutorials.