Skip to content
Hantera Developer Portal Developer Portal

Graph Phrase Search

Phrase Search is when the graph is queried using the phrase argument. This argument uses a pre-calculated search index to find entities.

The index can be configured to include edges, so that when you search for orders, but get a hit on an order’s delivery, the system will still return the order.

Configuring and Managing Search Indexes

Before a phrase search can be successfully performed, the search index must be prepared. Hantera normally comes with a basic standard configuration, which can be adjusted for your needs.

To configure a search index for a given graph node, use the /system/graph/<node>/search registry key. Note that nodes related to typed actors are separately indexed.

Once the search index is configured and applied, you need to trigger an index update. This can be done using hantera-cli.

Terminal window
h_ manage update-search [-s <session>] <node> [--rebuild]

For example, to update the order search index:

Terminal window
h_ manage use <session>
h_ manage update-search order

The --rebuild flag can be used to completely rebuild an index. This is generally never needed but can be used in case there’s something wrong with the existing index.

If you want to see the status of an ongoing update, or just check the status of the search indexes in general, you can check Hantera’s signals:

Terminal window
h_ manage signals graph -w

When using the Graph to query, you may use the phrase argument to add phrase search filtering to the result. Phrase filter is applied in combination with any filter you might apply as well. orderBy is not allowed in combination with phrase. Records are automatically sorted by search rank, which is basically how well the search phrase matches the node.

Example

POST https://<hantera-hostname>/resources/graph
Authorization: Bearer <YOUR TOKEN>
Content-Type: application/json


[{
  "edge": "orders",
  "phrase": "ORD1234",
  "limit": 1,
  "node": {
    "fields": ["orderId", "orderNumber"]
  }
}]

If a node search index is configured to contain edges, it’s possible to make a search on one set that matches a navigation. To expand on our previous example, let’s say that order search index has edge delivery configured, and delivery has field deliveryAddress.name indexed, the following query will search both orderNumber and deliveries.deliveryAddress.name and only return orders where either match:

POST https://<hantera-hostname>/resources/graph
Authorization: Bearer <YOUR TOKEN>
Content-Type: application/json


[{
  "edge": "orders",
  "phrase": "John Doe",
  "limit": 1,
  "node": {
    "fields": ["orderId", "orderNumber"],
    "navigate": [{
      "edge": "deliveries",
      "node": {
        "fields": ["deliveryAddress.name"],
      }
    }]
  }
}]

Phrase Matching Logic

Each separate word in a search must match a node for it to be returned, in essence the the words are ANDed. For fields that are indexed as non-keywords, any word less than 3 characters are ignored.

Prefix Matching

Wildcards (*) can be used to match the beginning of a word. For example, phrase* matches any word that begins with “phrase”.

Exact Matching

Single or multiple words can be quoted (single or double quotes) to search for exact phrases:

  • "phrase" - Matches words that are exactly “phrase”
  • "John Doe" - Matches exactly “John Doe” appearing in exactly that order