Back to main page

Query

Generic queries can be used to provide the functionality of most other functionality in the API

Description

Generic Aito queries are a more powerful expert tool, that essentially provide the functionality of every other query type in the Aito api. Search, similarity, match and recommend cann be seen as convenience APIs for the generic query.

Generic Aito query resembles the 'search' query, except that it supports 'get' statement. Get statement can be used in queries such as:

{
  "from" : "impressions",
  "where": {
    "customer" : 0,
    "query"    : "best laptop"
  },
  "get":"product",
  "orderBy": {"$p": {"$context" : {"click":true } } },
  "select": ["title", "$highlight"],
  "limit":2
}

This query 'gets' a product, that maximizes the click likelihood for given user & query. In essence, this generic query is a recommendation query.

Note: that 'get' operation changes the namespaces of 'select' and 'orderBy' operations. The namespace is changed from context table to the linked table. E.g. if you start from the impression table, and get a linked product, use "select":["title"] instead of "select":["product.title"] and use "orderBy":["price"] instead of "orderBy":["product"].

API end point

/api/v1/_query

Format:

    {
      "from" : From, 
      "where" : null | Proposition, 
      "get" : null | Get, 
      "orderBy" : null | OrderBy, 
      "select" : null | Selection, 
      "offset" : null | long, 
      "limit" : null | long
    }

See also:

Generic Search Query

Following query returns the laptop products ordered by price

POST /api/v1/_query

    {
      "from" : "products",
      "where": {
        "tags" : { "$match": "laptop" }
      },
      "orderBy": "price",
      "select": ["title"]
    }

Result

    {
      "offset" : 0,
      "total" : 3,
      "hits" : [ {
        "title" : "apple macbook"
      }, {
        "title" : "hp spectre"
      }, {
        "title" : "lenovo ideapad white"
      } ]
    }

Generic Search Query with OrderBy Similarity and Highlights

Following query returns the iphone related products highlighted and ordered by similarity

POST /api/v1/_query

    {
      "from" : "products",
      "where": {
        "title" : { "$match": "iphone" },
        "description" : { "$match": "iphone" }
      },
      "orderBy": "$similarity",
      "select": ["$score", "title", "$highlight"]
    }

Result

    {
      "offset" : 0,
      "total" : 3,
      "hits" : [ {
        "$score" : 0.335371208187104,
        "title" : "apple iphone",
        "$highlight" : [ {
          "score" : 0.6185748089123267,
          "field" : "title",
          "highlight" : "apple <font color=\"green\">iphone</font>"
        }, {
          "score" : 0.6185748089123267,
          "field" : "description",
          "highlight" : "apple <font color=\"green\">iphone</font> is a premium phone"
        } ]
      }, {
        "$score" : 0.335371208187104,
        "title" : "iphone protection white",
        "$highlight" : [ {
          "score" : 0.6185748089123267,
          "field" : "title",
          "highlight" : "<font color=\"green\">iphone</font> protection white"
        }, {
          "score" : 0.6185748089123267,
          "field" : "description",
          "highlight" : "protect <font color=\"green\">iphone</font> with a white phone cover"
        } ]
      }, {
        "$score" : 0.32925758362579194,
        "title" : "iphone protection leather",
        "$highlight" : [ {
          "score" : 0.6185748089123267,
          "field" : "title",
          "highlight" : "<font color=\"green\">iphone</font> protection leather"
        }, {
          "score" : 0.6185748089123267,
          "field" : "description",
          "highlight" : "protect <font color=\"green\">iphone</font> with an amazing and premium leather phone cover"
        } ]
      } ]
    }

Generic Similarity Query

Match a product to the customer's wish.

POST /api/v1/_query

    {
       "from" : "messages",
       "orderBy" : {
         "$similarity" : {
           "message" : "Recommend me a premium laptop"
         }
       },
       "limit" : 2
    }

Result

    {
      "offset" : 0,
      "total" : 30,
      "hits" : [ {
        "$score" : 0.0445636507326612,
        "id" : 28,
        "message" : "Can you recommend me a premium phone?",
        "operation" : "recommend",
        "prev" : 27,
        "product" : "s8",
        "user" : 11
      }, {
        "$score" : 0.04445669763120064,
        "id" : 17,
        "message" : "Can you recommend a premium laptop?",
        "operation" : "recommend",
        "prev" : 16,
        "product" : "macbook",
        "user" : 9
      } ]
    }

Generic Predict Query

Predict the operation type, which the user wants the system to do

POST /api/v1/_query

    {
       "from" : "messages",
       "where": {
         "message" : "Show me the laptops"
       },
       "get" : "operation",
       "orderBy" : "$p",
       "limit" : 1
    }

Result

    {
      "offset" : 0,
      "total" : 6,
      "hits" : [ {
        "$p" : 0.8942960270360091,
        "field" : "",
        "feature" : "show"
      } ]
    }

Generic Match Query

Match a product to the customer's wish.

POST /api/v1/_query

    {
       "from" : "messages",
       "where": {
         "message" : "Recommend me a premium laptop."
       },
       "get" : "product",
       "orderBy" : "$p",
       "select": ["title", "$highlight"],
       "limit" : 2
    }

Result

The above query returns an array of results, sorted by probability

    {
      "offset" : 0,
      "total" : 11,
      "hits" : [ {
        "title" : "hp spectre",
        "$highlight" : [ {
          "score" : 3.242274624661655,
          "field" : "description",
          "highlight" : "hp spectre <font color=\"green\">is</font> <font color=\"green\">a</font> premium <font color=\"green\">laptop</font>, that <font color=\"green\">is</font> compatible with <font color=\"red\">phones</font>"
        }, {
          "score" : 2.015373985784721,
          "field" : "tags",
          "highlight" : "windows <font color=\"green\">laptop</font> <font color=\"green\">premium</font>"
        }, {
          "score" : 1.067114222730826,
          "field" : "name",
          "highlight" : "<font color=\"green\">spectre</font>"
        }, {
          "score" : 0.632294986071229,
          "field" : "id",
          "highlight" : "<font color=\"green\">4</font>"
        } ]
      }, {
        "title" : "apple macbook",
        "$highlight" : [ {
          "score" : 2.1047655907782765,
          "field" : "description",
          "highlight" : "apple macbook <font color=\"green\">is</font> the top <font color=\"green\">laptop</font> in the market"
        }, {
          "score" : 2.015373985784721,
          "field" : "tags",
          "highlight" : "macosx <font color=\"green\">laptop</font> <font color=\"green\">premium</font>"
        }, {
          "score" : 1.067114222730826,
          "field" : "name",
          "highlight" : "<font color=\"green\">macbook</font>"
        } ]
      } ]
    }

Generic Recommendation Query

Following query returns the products, that maximizes click through rate for user 0 and query 'best laptop'.

POST /api/v1/_query

    {
      "from" : "impressions",
      "where": {
        "customer" : 0,
        "query"    : "best laptop"
      },
      "get":"product",
      "orderBy": {"$p": {"$context" : {"click":true } } },
      "select": ["title", "$highlight"],
      "limit":2
    }

Result

    {
      "offset" : 0,
      "total" : 11,
      "hits" : [ {
        "title" : "apple macbook",
        "$highlight" : [ {
          "score" : 1.889050922464782,
          "field" : "description",
          "highlight" : "apple macbook <font color=\"green\">is</font> the top <font color=\"green\">laptop</font> <font color=\"green\">in</font> the market"
        }, {
          "score" : 1.6688953121558205,
          "field" : "title",
          "highlight" : "<font color=\"green\">apple</font> macbook"
        }, {
          "score" : 1.6129244719554066,
          "field" : "price",
          "highlight" : "<font color=\"green\">1500.0</font>"
        }, {
          "score" : 0.2933119226785609,
          "field" : "tags",
          "highlight" : "macosx <font color=\"green\">laptop</font> <font color=\"green\">premium</font>"
        } ]
      }, {
        "title" : "hp spectre",
        "$highlight" : [ {
          "score" : 1.7722165541403896,
          "field" : "tags",
          "highlight" : "<font color=\"green\">windows</font> <font color=\"green\">laptop</font> <font color=\"green\">premium</font>"
        }, {
          "score" : 1.6129244719554066,
          "field" : "price",
          "highlight" : "<font color=\"green\">1500.0</font>"
        }, {
          "score" : 1.5878200211854012,
          "field" : "description",
          "highlight" : "hp spectre <font color=\"green\">is</font> <font color=\"red\">a</font> premium <font color=\"green\">laptop</font>, that <font color=\"green\">is</font> compatible with phones"
        } ]
      } ]
    }

A query, that combines personalization, similarity metrics and price

Find the customer 0 a phone. The query optimizes the store's revenue by multiplying the similarity extended clicking probability with the product price.

POST /api/v1/_query

    {
      "from" : "impressions",
      "where": {
        "customer"      : 0,
        "product.tags" : { "$match" : "phone" }
      },
      "get":"product",
      "orderBy": {
        "$multiply" : [
          {"$p": {"$context" : {"click":true } } },
          "$similarity",
          "price"
        ]
      },
      "select": ["$score", "title", "$highlight"],
      "limit": 3
    }

Result

    {
      "offset" : 0,
      "total" : 3,
      "hits" : [ {
        "$score" : 49.93067844754155,
        "title" : "huawei honor",
        "$highlight" : [ {
          "score" : 7.22881869049588,
          "field" : "price",
          "highlight" : "<font color=\"green\">150.0</font>"
        }, {
          "score" : 3.099436839267874,
          "field" : "tags",
          "highlight" : "<font color=\"green\">android</font> <font color=\"green\">phone</font> <font color=\"green\">affordable</font>"
        }, {
          "score" : 1.2565923590742214,
          "field" : "id",
          "highlight" : "<font color=\"green\">2</font>"
        }, {
          "score" : 1.0069712027025035,
          "field" : "description",
          "highlight" : "huawei <font color=\"green\">is</font> <font color=\"green\">an</font> affordable android phone"
        } ]
      }, {
        "$score" : 1.07615442988375,
        "title" : "apple iphone",
        "$highlight" : [ {
          "score" : 9.643856189774723,
          "field" : "price",
          "highlight" : "<font color=\"green\">800.0</font>"
        }, {
          "score" : 1.4580650012785115,
          "field" : "description",
          "highlight" : "apple <font color=\"red\">iphone</font> <font color=\"green\">is</font> <font color=\"red\">a</font> premium phone"
        }, {
          "score" : 1.401125366207483,
          "field" : "tags",
          "highlight" : "ios <font color=\"green\">phone</font> <font color=\"green\">premium</font>"
        }, {
          "score" : 0.8880026588868345,
          "field" : "title",
          "highlight" : "<font color=\"green\">apple</font> <font color=\"green\">iphone</font>"
        } ]
      }, {
        "$score" : 0.5765058091876076,
        "title" : "samsung s8",
        "$highlight" : [ {
          "score" : 9.228818690495881,
          "field" : "price",
          "highlight" : "<font color=\"green\">600.0</font>"
        }, {
          "score" : 2.1050728671251417,
          "field" : "description",
          "highlight" : "samsung s8 <font color=\"green\">is</font> <font color=\"red\">a</font> <font color=\"red\">premium</font> phone <font color=\"red\">with</font> all sorts of features "
        }, {
          "score" : 1.9795491357023143,
          "field" : "tags",
          "highlight" : "<font color=\"green\">android</font> <font color=\"green\">phone</font> <font color=\"green\">premium</font>"
        } ]
      } ]
    }

Generic Matching by Probability Lift

Find a customer, who is best characterized by the message.

To understand the practical difference between $p and $lift consider following situation:

  1. User A talks a lot, but he doesn't mention iPhone often

  2. User B talks very rarely, but only about the iphones.

Querying users by $p quite likely finds the user A, because he may be overall more likely to mention the iphone. Querying user $lift, will very certainly find the user B, because $lift describes that how characteristic the iphone is for the user.

A more mathematical and technical description for the phenomenon is the following:

Aito uses Bayesian probability inference to estimate p(X|context) so that p(X|context) = p(X) * ─║ift(X|context), where the probability lift component lift(X|context) = p(context|X)/p(context)

The probability lift component describes that how much more likely X is true in the specified context, when compared to average.

In Aito query syntax: $p stands for the p(X|context), while $lift stands for the lift(X|context) component. Currently, there is no expression for the base probability p(X).

POST /api/v1/_query

    {
       "from" : "messages",
       "where": {
         "message" : "I want an iphone!"
       },
       "get" : "user",
       "orderBy" : "$lift",
       "limit" : 2
    }

Result

The above query returns an array of results, sorted by the probability lift. The probability lift value is stored in the $score field.

    {
      "offset" : 0,
      "total" : 12,
      "hits" : [ {
        "$score" : 21.88776425061313,
        "id" : 10,
        "name" : "jane",
        "tags" : "nyc 60s"
      }, {
        "$score" : 9.898875544296102,
        "id" : 9,
        "name" : "john",
        "tags" : "london 60s"
      } ]
    }