Similarity API

This API supports advanced search capabilities, which will allow clients to find similar documents base in the input.

Authentication

Clients calling the API are required to add an authentication header with the valid authentication token.

Authorization: Bearer {ACCESS_TOKEN}

Examples

Nearest documents

The similarity API allows the client to find the nearest document based off of a piece of text and a targeted field.

query FindNearestDocument {
  similarity(
    input: {
      nearest: {
        text: "eats carrots and is an animal",
        field: "post_content"
      }
    }) {
    total
    docs {
      id
      score
      data
    }
  }
}

sample response:

{
  "data": {
    "similarity": {
      "total": 1,
      "docs": [
        {
          "id": "rabbit:6",
          "score": 2.5204816,
          "data": {
            "ID": 1,
            "post_content": "Rabbit is happily running",
            "post_date": "11-06-2023T12:33:00",
            "post_status": "publish",
            "post_title": "George the rabbit",
            "post_type": "rabbit"
          }
        },
        {
          "id": "horse:7",
          "score": 2.2204816,
          "data": {
            "ID": 1,
            "post_content": "Horse in a field",
            "post_date": "11-06-2023T12:33:00",
            "post_status": "publish",
            "post_title": "Greg the horse",
            "post_type": "horse"
          }
        },
      ]
    }
  }
}

Using filters

The client can also filter for documents that match the provided query string, lets say we didn’t want to include the rabbit post type.

query FindNearestDocumentWithFilter {
  similarity(
    input: {
      nearest: {
        text: "eats carrots and is an animal",
        field: "post_content"
      },
      filter: "NOT post_type:rabbit"
    }) {
    total
    docs {
      id
      score
      data
    }
  }
}

Sample response:

{
  "data": {
    "similarity": {
      "total": 0,
      "docs": [
        {
          "id": "horse:7",
          "score": 2.2204816,
          "data": {
            "ID": 1,
            "post_content": "Horse in a field",
            "post_date": "11-06-2023T12:33:00",
            "post_status": "publish",
            "post_title": "Greg the horse",
            "post_type": "horse"
          }
        }
      ]
    }
  }
}

Pagination

The similarity API allows you to paginate through results. The following query would offset to the 10th document and then display the next five additional documents.

query FindNearestDocumentWithPagination {
  similarity(
    limit: 5
    offset: 10
    input: {
      nearest: {
        text: "eats carrots and is an animal",
        field: "post_content"
      },
      filter: "NOT post_type:rabbit"
    }) {
    total
    docs {
      id
      score
      data
    }
  }
}

Minimum score

The similarity API also allows you to set a min score, since the nearest documents are based on probability the client can set a minimum score threshold to omit documents that fall below the threshold.

query FindNearestDocumentWithMinScore {
  similarity(
    minScore: 0.8
    input: {
      nearest: {
        text: "eats carrots and is an animal",
        field: "post_content"
      },
    }) {
    total
    docs {
      id
      score
      data
    }
  }
}