Back to main page

Search

The search API is used make SQL like selections in aito

Description

Aito's search query structure resembles the SQL query structure.

First, you specify the examined table in the 'from' field. You can for example state, that you are looking at the impression table.

Second, you can declare a set of conditions in the 'where' field. For example, you may declare, that the customer id is 4, and the query is laptop. The returned results will fulfil these conditions

Third, you may declare the order the results are results. You may e.g. order the results, by the displayed product id.

Fourth, you may select the displayed fields. The fields may belong to the examined table, like 'query', or they may belong to linked tables such as 'user.name' and 'product.title'.

Fifth, you may page the results, using the offset and the limit fields. By default, aito returns only 10 results in order to limit server memory consumption and avoid slow responses with huge datasets (there may be thousands or millions of matches).

API end point

/api/v1/_search

Format:

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

See also:

Normal Search Query

Give me 3 laptops, ordered by price. Include only specific fields in results.

POST /api/v1/_search

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

Result

    {
      "offset" : 0,
      "total" : 3,
      "hits" : [ {
        "id" : 3,
        "title" : "apple macbook",
        "price" : 1500.0
      }, {
        "id" : 4,
        "title" : "hp spectre",
        "price" : 1500.0
      }, {
        "id" : 5,
        "title" : "lenovo ideapad white",
        "price" : 400.0
      } ]
    }

Normal Search Query with Ascending Order

By default Aito sorts everything from the biggest to the smallest. This is a design choice, dictated by the fact that within the domain of statistical reasoning: the highest values are often the most interesting ones.

For example: the items with the highest probabilities, the highest frequencies, the highest similarities, the highest mutual information and the highest scores are often the most desired ones .

Use $asc to sort values from the smallest to the biggest, as shown in the example.

POST /api/v1/_search

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

Result

    {
      "offset" : 0,
      "total" : 3,
      "hits" : [ {
        "id" : 5,
        "title" : "lenovo ideapad white",
        "price" : 400.0
      }, {
        "id" : 3,
        "title" : "apple macbook",
        "price" : 1500.0
      }, {
        "id" : 4,
        "title" : "hp spectre",
        "price" : 1500.0
      } ]
    }

Get Everything Query

Minimalistic query, that lists the first page of all products.

Note, that the amount of results is limited to 10 by default. This limitation exist to prevent the server from running out of heap, when formatting the results, in the case the table is extremely big. Use offset and limit to to page the results, in case you need more items or bigger pages.

POST /api/v1/_search

    {
      "from" : "products"
    }

Result

    {
      "offset" : 0,
      "total" : 11,
      "hits" : [ {
        "description" : "apple iphone is a premium phone",
        "id" : 0,
        "name" : "iphone",
        "price" : 800.0,
        "tags" : "ios phone premium",
        "title" : "apple iphone"
      }, {
        "description" : "samsung s8 is a premium phone with all sorts of features ",
        "id" : 1,
        "name" : "s8",
        "price" : 600.0,
        "tags" : "android phone premium",
        "title" : "samsung s8"
      }, {
        "description" : "huawei is an affordable android phone",
        "id" : 2,
        "name" : "honor",
        "price" : 150.0,
        "tags" : "android phone affordable",
        "title" : "huawei honor"
      }, {
        "description" : "apple macbook is the top laptop in the market",
        "id" : 3,
        "name" : "macbook",
        "price" : 1500.0,
        "tags" : "macosx laptop premium",
        "title" : "apple macbook"
      }, {
        "description" : "hp spectre is a premium laptop, that is compatible with phones",
        "id" : 4,
        "name" : "spectre",
        "price" : 1500.0,
        "tags" : "windows laptop premium",
        "title" : "hp spectre"
      }, {
        "description" : "lenovo idea pad is an affordable white laptop",
        "id" : 5,
        "name" : "ideapad",
        "price" : 400.0,
        "tags" : "windows laptop affordable",
        "title" : "lenovo ideapad white"
      }, {
        "description" : "protect iphone with a white phone cover",
        "id" : 6,
        "name" : "iphone_cover_white",
        "price" : 25.0,
        "tags" : "cover",
        "title" : "iphone protection white"
      }, {
        "description" : "protect iphone with an amazing and premium leather phone cover",
        "id" : 7,
        "name" : "iphone_cover_leather",
        "price" : 25.0,
        "tags" : "cover",
        "title" : "iphone protection leather"
      }, {
        "description" : "protect samsung s8 with an amazing and premium leather phone cover",
        "id" : 8,
        "name" : "s8_cover_leather",
        "price" : 25.0,
        "tags" : "cover",
        "title" : "samsung s8 leather cover"
      }, {
        "description" : "this is a waterproof acme thingie for all sorts and kinds of people with lots of common words like find, amazing, market, you, your, in, with, the, feature, an, a, laptop and phone",
        "id" : 9,
        "name" : "generic0",
        "price" : 100.0,
        "tags" : "",
        "title" : "generic acme product"
      } ]
    }

Paging

This query lists the second page of all products.

POST /api/v1/_search

    {
      "from" : "products",
      "offset": 10,
      "limit" : 10
    }

Result

    {
      "offset" : 10,
      "total" : 11,
      "hits" : [ {
        "description" : "this is a waterproof acme thingie for all sorts and kinds of people with lots of common words like find, amazing, market, you, your, in, with, the, feature, awesome, an, a, laptop and phone",
        "id" : 10,
        "name" : "generic1",
        "price" : 100.0,
        "tags" : "",
        "title" : "generic acme product"
      } ]
    }

Or Operation

Give me phones and phone covers. Show title and tags.

POST /api/v1/_search

    {
      "from" : "products",
      "where": {
        "tags" :
          {"$or" : [
            {"$match" : "phone"},
            {"$match" : "cover"}
          ]}
      },
      "select" : ["title", "tags"]
    }

Result

    {
      "offset" : 0,
      "total" : 6,
      "hits" : [ {
        "title" : "apple iphone",
        "tags" : "ios phone premium"
      }, {
        "title" : "samsung s8",
        "tags" : "android phone premium"
      }, {
        "title" : "huawei honor",
        "tags" : "android phone affordable"
      }, {
        "title" : "iphone protection white",
        "tags" : "cover"
      }, {
        "title" : "iphone protection leather",
        "tags" : "cover"
      }, {
        "title" : "samsung s8 leather cover",
        "tags" : "cover"
      } ]
    }

And operation

Give me products in price range 300-800.

POST /api/v1/_search

    {
      "from" : "products",
      "where": {
        "price":
          {"$and" : [
            {"$gte":300},
            {"$lte":800}
          ]}
      }
    }

Result

    {
      "offset" : 0,
      "total" : 3,
      "hits" : [ {
        "description" : "apple iphone is a premium phone",
        "id" : 0,
        "name" : "iphone",
        "price" : 800.0,
        "tags" : "ios phone premium",
        "title" : "apple iphone"
      }, {
        "description" : "samsung s8 is a premium phone with all sorts of features ",
        "id" : 1,
        "name" : "s8",
        "price" : 600.0,
        "tags" : "android phone premium",
        "title" : "samsung s8"
      }, {
        "description" : "lenovo idea pad is an affordable white laptop",
        "id" : 5,
        "name" : "ideapad",
        "price" : 400.0,
        "tags" : "windows laptop affordable",
        "title" : "lenovo ideapad white"
      } ]
    }

Order by similarity

Find me iphone related products. Order by similarity and highlight the match

POST /api/v1/_search

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

Result

    {
      "offset" : 0,
      "total" : 3,
      "hits" : [ {
        "$score" : 0.33454658651343117,
        "title" : "apple iphone",
        "$highlight" : [ {
          "score" : 0.6185748089123267,
          "field" : "title",
          "highlight" : "apple <font color=\"green\">iphone</font>"
        } ]
      }, {
        "$score" : 0.33454658651343117,
        "title" : "iphone protection white",
        "$highlight" : [ {
          "score" : 0.6185748089123267,
          "field" : "title",
          "highlight" : "<font color=\"green\">iphone</font> protection white"
        } ]
      }, {
        "$score" : 0.3309068269731376,
        "title" : "iphone protection leather",
        "$highlight" : [ {
          "score" : 0.6185748089123267,
          "field" : "title",
          "highlight" : "<font color=\"green\">iphone</font> protection leather"
        } ]
      } ]
    }

Order by similarity with a field specific weighting

Find me phone related products. Order by similarity and highlight the match. This query returns all products, that contain phone in the tags or the description fields, while giving greater emphasis to the matches in tags.

POST /api/v1/_search

    {
      "from" : "products",
      "where": {
        "$or" : [
          { "tags" : {"$match" : "phone" } },
          { "description" :  {"$match" : "phone" } }
        ]
      },
      "orderBy" : {
        "$multiply" : [
          {"$pow": [ { "$similarity" : { "tags" : "phone"  } }, 2] },
          {"$pow": [ { "$similarity" : { "description" : "phone"  } }, 1] }
        ]
      },
      "select" : ["$score", "title", "$highlight"],
      "limit" : 3
    }

Result

    {
      "offset" : 0,
      "total" : 9,
      "hits" : [ {
        "$score" : 0.0016374469451412817,
        "title" : "apple iphone",
        "$highlight" : [ {
          "score" : 1.2371496178246535,
          "field" : "tags",
          "highlight" : "ios <font color=\"green\">phone</font> premium"
        }, {
          "score" : 0.09553718367434502,
          "field" : "description",
          "highlight" : "apple iphone is a premium <font color=\"green\">phone</font>"
        } ]
      }, {
        "$score" : 0.0016374469451412817,
        "title" : "huawei honor",
        "$highlight" : [ {
          "score" : 1.2371496178246535,
          "field" : "tags",
          "highlight" : "android <font color=\"green\">phone</font> affordable"
        }, {
          "score" : 0.09553718367434502,
          "field" : "description",
          "highlight" : "huawei is an affordable android <font color=\"green\">phone</font>"
        } ]
      }, {
        "$score" : 0.0015792783006373567,
        "title" : "samsung s8",
        "$highlight" : [ {
          "score" : 1.2371496178246535,
          "field" : "tags",
          "highlight" : "android <font color=\"green\">phone</font> premium"
        }, {
          "score" : 0.09553718367434502,
          "field" : "description",
          "highlight" : "samsung s8 is a premium <font color=\"green\">phone</font> with all sorts of features "
        } ]
      } ]
    }