The Query Process

Owned by AlexI (Unlicensed)
Last updated: Apr 11, 2015 by andrew johnston (Unlicensed)
10 min read

Overview of the Query Process

The IKANOW platform is queried using the available query terms, such as free/exact text queries, saved queries, raw query terms etc.  As part of the query process, scoring parameters, and input/output options are also specified.  The available query terms, and other options, comprise the parameters that are sent as part of the Knowledge - Document - Query API call.  These developer guides will describe the query parameters in detail, including object field guides, usage guidelines/best practices and walkthroughs.

In this section:

Query Parameters

Query Terms:

Scoring:

Input and Output:

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

  1. "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)
  2. Perform a "GET" to the URL described above, with the "json=" parameter set to a URL-encoded single-line representation of the JSON object
  3. 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:

Using 'curl' to POST a query
#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
        }
    }
}'
Using URL parameters to query via GET
#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'
Using a URL-encoded JSON object to query via GET
#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):

Invoking the query method from within ActionScript
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.

Invoking the query method using a 'GET' request from within JavaScript using jQuery
$.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.

Invoking the query method using a 'POST' request from within Javascript using jQuery
$.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.

Knowledge - Document - Query