Interpreting natural language queries

The query expressions that the API uses to evaluate a query are not in a natural language format. To ensure that users can make queries in a natural way, we need to interpret their input.

When calling the Interpret feature of the API, it accepts a query string. This will be returned and formatted to reflect the user intent using academic grammar. In addition, this feature can be called as the user is writing, to provide an interactive experience.

The request is a GET request, as shown in the following code:

    private async void Interpret(object obj)
    {
        var queryString = HttpUtility.ParseQueryString(string.Empty);

        queryString["query"] = InputQuery;
        queryString["complete"] = "1";
        //queryString["count"] = "10";
        //queryString["offset"] = "0";
        //queryString["timeout"] = "1000";
        //queryString["model"] = "latest";

We start the call by creating a queryString variable. The parameters we can input are specified in the following table:

Parameter	Description
query (required)	The query from the user.
complete (optional)	If this is set to 1, then the service will return suggestions using the query as a prefix. A value of 0 means there will be no autocomplete.
count (optional)	The maximum number of interpretations to return.
offset (optional)	The index of the first interpretation. This is useful if a lot of results are expected and you need to add pagination.
timeout (optional)	The timeout specified in milliseconds. Only results found before this limit will be returned.
model (optional)	The name of the model you want to query. This defaults to the latest model.

We call the API to get interpretations, as shown in the following code:

    InterpretResponse response = await _webRequest.MakeRequest<object, 
    InterpretResponse>(HttpMethod.Get, $"interpret?{queryString.ToString()}");

    if (response == null || response.interpretations.Length == 0)
        return;

As this is a GET request, we do not need to specify any request bodies. We do, however, expect a result to be serialized into an InterpretResponse object. This is a data contract, containing properties from the result.

A successful call to the API will result in a JSON response, which looks as follows:

    {
        "query": "papers by jaime", "interpretations": [
        {
            "prob": 2.429e-006,
            "parse": "<rule id="#GetPapers"> papers by <attr name="academic#AA.AuN">
            jaime teevan </attr></rule>",
            "rules": [
            {
                "name": "#GetPapers",
                "output": {
                    "type": "query",
                    "value": "Composite(AA.AuN=='jaime teevan')"
                }
            }]
        }]
    }

The result contains the original query. It also contains an array with interpretations. Each item in this array consists of the data shown in the following table:

Data field	Description
prob	This is the probability of the current interpretation being correct. The scale goes from 0 to 1, where 1 is the highest.
parse	This is an XML string showing interpretations for each part of the string.
rules	This is an array with one or more rules defined. There will always be one rule for the academic API.
rules[x].name	This is the name of the current rule.
rules[x].output	This is the output of the current rule.
rules[x].output.type	This is the type of the rule output. This will always be query for the academic API.
rules[x].output.value	This is the output value for the rule. This will be a query expression string.

Create the InterpretResponse data contract based on the preceding JSON output. We are interested in the last data field, rules[x].output.value. This is the query expression string, which we will use to evaluate queries.

When the API call has succeeded, we want to update the ObservableCollection class as to the available query expressions, using the following code:

    ObservableCollection<string> tempList = new ObservableCollection<string>();

    foreach (Interpretation interpretation in response.interpretations)
    {
        foreach (Rule rule in interpretation.rules) {
            tempList.Add(rule.output.value);
        }
    }

    AvailableQueryExpressions = tempList;
    QueryExpression = AvailableQueryExpressions.FirstOrDefault();

We loop through all interpretations, adding the outputvalue from a rule to our AvailableQueryExpressions.

Finally, we set the selected QueryExpression as the first one available. This is just for our own convenience.

A successful test run can generate the following results:

An unsuccessful call will produce an error response code. The response codes that can be generated are as follows:

Response code	Description
400	Bad argument; request parameter is missing
401	Invalid subscription key
403	The call volume quota has been exceeded
404	The requested resources are not found
500	Internal server error