The Query Process
Query Parameters
Query Terms:
Scoring:
Input and Output:
- Input options (within the sources available based on the community list)
- Output options
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"
"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
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 Infinit.e 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 Infinit.e. For the purposes of the example below illustrates how to use jQuery to call the Infinit.e 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:
Detailed reference documentation for Query endpoint.