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 contain related graphs, so that when you search for orders, but get a hit on an order’s delivery, the system will still return the order.

The GraphQL interface has a special phraseMatches field that can be used in conjunction with phrase search to outline exactly where in the result graph the hits are.

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.

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

expressiveCode.terminalWindowFallbackTitle
h_ search update [-e <env>] <node> [--rebuild]

For example, to update the order search index:

expressiveCode.terminalWindowFallbackTitle
h_ use <env>
h_ search update order

The --rebuild flag can be used to completely rebuild an index. This is only needed if you have removed fields from the index and wish to exclude them from 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:

expressiveCode.terminalWindowFallbackTitle
h_ signals processes/hantera/graph -w

When using the GraphQL API 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 affected by phrase search.

When using phrase search, it’s important to remember that only fields that are selected in the query are taken into account. For example, given that order has field orderNumber and customerNumber indexed, only orderNumber will be searched given the below query:

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


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

This behavior can be overridden by setting the phraseFields field to * in the query. With the below change, both orderNumber and customerNumber will be matched.

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


[{
  "edge": "orders",
  "phrase": "ORD1234",
  "phraseFields": "*",
  "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 graph for it to be returned, for example, the words are ANDed. Any word less than 3 characters are ignored.

Wildcard Matching

Wildcards (*) can be used to match parts of words:

  • *phrase - Matches any word that ends with “phrase”
  • phrase* - Matches any word that begins with “phrase”
  • pra*se - Matches any word that starts with “pra”, as “se” is ignored
  • han*tera - Matches any word that starts with “han” and ends with “tera”

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

Actor Extensions and Custom Nodes

When it comes to the dynamic nature of Actor Extensions, the generated nodes can not be configured separately in terms of search indexing. Instead, search indexing is always configured on the base node. When performing a phrase search, the base node’s index will be used whenever a Typed Node is searched. Of course, only Nodes that matches the current type will ever match.