Back to main page

Similarity

The similarity API is used to find similar documents

Description

Similarity can be used to return documents, that are similar to the given specification. E.g. you can ask for messages, that are similar to phrase "How can I do similarity query?"

Similarity operation uses TF-IDF for scoring the documents.

API end point

/api/v1/_similarity

Format:

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

See also:

Example Similarity Query

Find me 3 products, that are similar to apple iphone, order by similarity

POST /api/v1/_similarity

    {
      "from": "products",
      "similarity": {
        "title" : "apple iphone",
        "tags"  : "premium phone"
      },
      "limit":3
    }

Result

    {
      "offset" : 0,
      "total" : 11,
      "hits" : [ {
        "$score" : 0.12001954421019684,
        "description" : "apple iphone is a premium phone",
        "id" : 0,
        "name" : "iphone",
        "price" : 800.0,
        "tags" : "ios phone premium",
        "title" : "apple iphone"
      }, {
        "$score" : 0.09863886369078853,
        "description" : "apple macbook is the top laptop in the market",
        "id" : 3,
        "name" : "macbook",
        "price" : 1500.0,
        "tags" : "macosx laptop premium",
        "title" : "apple macbook"
      }, {
        "$score" : 0.09489498290185765,
        "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"
      } ]
    }

Example Query with Highlights

Find me 3 products, that are similar to apple iphone, order by similarity

POST /api/v1/_similarity

    {
      "from": "products",
      "similarity": {
        "title" : "apple iphone",
        "tags"  : "premium phone"
      },
      "select":["$highlight"],
      "limit":3
    }

Result

    {
      "offset" : 0,
      "total" : 11,
      "hits" : [ {
        "$highlight" : [ {
          "score" : 1.430187243062635,
          "field" : "title",
          "highlight" : "<font color=\"green\">apple</font> <font color=\"green\">iphone</font>"
        }, {
          "score" : 1.100187243062635,
          "field" : "tags",
          "highlight" : "ios <font color=\"green\">phone</font> <font color=\"green\">premium</font>"
        } ]
      }, {
        "$highlight" : [ {
          "score" : 0.8116124341503081,
          "field" : "title",
          "highlight" : "<font color=\"green\">apple</font> macbook"
        }, {
          "score" : 0.48161243415030824,
          "field" : "tags",
          "highlight" : "macosx laptop <font color=\"green\">premium</font>"
        } ]
      }, {
        "$highlight" : [ {
          "score" : 1.100187243062635,
          "field" : "tags",
          "highlight" : "android <font color=\"green\">phone</font> <font color=\"green\">premium</font>"
        } ]
      } ]
    }

Example Query with Explanations

Find me 3 products, that are similar to apple iphone, order by similarity

POST /api/v1/_similarity

    {
      "from": "products",
      "similarity": {
        "title" : "apple iphone",
        "tags"  : "premium phone"
      },
      "select":["title", "$why"],
      "limit":3
    }

Result

    {
      "offset" : 0,
      "total" : 11,
      "hits" : [ {
        "title" : "apple iphone",
        "$why" : {
          "type" : "product",
          "factors" : [ {
            "type" : "hitVariableLift",
            "variable" : "title:appl",
            "value" : 1.7551720221592049,
            "factors" : [ ]
          }, {
            "type" : "hitVariableLift",
            "variable" : "tags:phone",
            "value" : 1.5353577023874483,
            "factors" : [ ]
          }, {
            "type" : "hitVariableLift",
            "variable" : "title:iphon",
            "value" : 1.5353577023874483,
            "factors" : [ ]
          }, {
            "type" : "hitVariableLift",
            "variable" : "tags:premium",
            "value" : 1.3963033788935442,
            "factors" : [ ]
          } ]
        }
      }, {
        "title" : "apple macbook",
        "$why" : {
          "type" : "product",
          "factors" : [ {
            "type" : "hitVariableLift",
            "variable" : "title:appl",
            "value" : 1.7551720221592049,
            "factors" : [ ]
          }, {
            "type" : "hitVariableLift",
            "variable" : "tags:premium",
            "value" : 1.3963033788935442,
            "factors" : [ ]
          } ]
        }
      }, {
        "title" : "samsung s8",
        "$why" : {
          "type" : "product",
          "factors" : [ {
            "type" : "hitVariableLift",
            "variable" : "tags:phone",
            "value" : 1.5353577023874483,
            "factors" : [ ]
          }, {
            "type" : "hitVariableLift",
            "variable" : "tags:premium",
            "value" : 1.3963033788935442,
            "factors" : [ ]
          } ]
        }
      } ]
    }