# Search Reference

This section describes how Hume handles the search queries entered by the user in the visualisation search bar.

Make sure to setup the necessary indexes by following the Knowledge Graph Management - Schema - Setting up Indexes for Search and Performance section.

Starting with version 2.7 Hume features the fine-grained search option allowing users to search based on particular classes and attributes.

Let's start with a example query which finds Primitivo wines under 12 euros.

Fine Grained Search

The query consistes of two terms Wine.name ~ Primitivo and Wine.price < 12. Each term specifies a class, attribute, operator and value.

The Fine Grained search is disabled by default on new knowledge graphs. To enable it navigate to knowledge graph settings, under the Visualisation tab toggle the Fine Grained Search enabled and save the settings.

# Constructing a search term

A search query is a series of terms connected by &&. The terms are in AND relation - all of them must resolve to true.

A term has the following structure: {class}.{attribute} {operator} {value}.

Hume tries to parse the search input to understand the term. If the parsing fails (classes, attributes do not exist in the schema, the structure is incorrect,...), the entire string is considered a value and Hume will use it to search in a standard way.

E.g When searching for primitivo, Hume does not recognise the fine grained search term structure, but would still bring results as if the fine grained search was disabled.

Hume currently supports 4 operators: ~ like, = equals, > greater than, < less then.

Anything that is after the operator (the rest of the term) is the value. E.g.:

Wine.name ~ asolo prosecco superiore

-> asolo prosecco superiore is the value. It does not need to be in any backticks or quotes.

# Omitting the attribute

It is possible to leave out the attribute part of the term in a specific case - when using like operator. Hume will search on all the attributes of the class then. E.g.:

Wine ~ primitivo

# Suggestions

Hume helps users with their search queries by showing suggestions according to the schema. Hume suggests class names, their attributes and fitting operators (e.g. does not show > or < for an attribute of type string). The following picture shows the attributes suggestion.

Fine Grained Search

To show suggestions just start typing in the search field. Use arrows up and down to select a suggestion (in blue). Apply the selected suggestion by pressing TAB or return. Or simply click on any suggestion to apply it.

Although we strongly advice against it, you can use spaces or dots in the class labels and attribute names. To specify an attribute with spaces in a search query, use backticks like this:

Person.`attribute with spaces` = exampleValue

When you apply a suggestion which requires backticks, Hume will automatically add them.

# Limitations

  • When omitting the attribute like Wine ~ primitivo we support only a single term query.
  • The `~ like' operator can be used only in the first term of a multi-term query.

Do this:

Wine.name ~ primitivo && Wine.price < 12

NOT this:

Wine.price < 12 && Wine.name ~ primitivo

# Schema inference

As of today ( Hume 2.6 ), Hume relies on the information from the schema ( gathered via the Perspective used by the visualisation ) and makes simple assumptions.

Given the following schema for a class :

Schema

If there is at least one attribute that has the Full Text Search enabled, then it considered searches for that class to be full text, otherwise it will search on the attributes separately ( actual queries will be shown later ).

# Search Behaviour

Always based on our Wines Knowledge Graph, let's take the following search :

Schema

And on the assumption of the schema above, the search query will trigger the following behaviour against the Neo4j database :

a) for each schema class having at least 1 attribute with full text search enabled, search the full text index with as name the label of the class with a default rewritten query enabling wildcard search b) for each schema class having no attributes with full text search enabled, search on their attributes with a UNION query c) return top 20 results ( no FTS search results have a default score of 1.0 )

# Query rewrite for Lucene

By default, Hume will rewrite the query the user typed, doing 4 steps :

  1. split the query on a whitespace in order to create a list of tokens
  2. sanitize each token ( remove non alphanumeric characters )
  3. duplicate the token with a wildcard token
  4. produce an AND/OR query

For example, the following query :

primi~ mand

will be rewritten as :

((primi AND mand) OR (primi* AND mand*))

The query will then be matched against every attribute that is matched as full text search, the final query will be :

CALL db.index.fulltext.queryNodes('Wine', '
    name: ((primi AND mand) OR (primi* AND mand*)) 
 OR description: ((primi AND mand) OR (primi* AND mand*))
 ')

Searching for primitivo di manduria would produce and AND query, so that each token must appear in the indexed document to be returned as result, however nothing dictates that the sequence of the tokens as a phrase does actually matters, in fact each token can be 1000 characters apart from each other in the indexed document and it would be a valid result.

To force a phrase search like, you can enclose your search within double quotes :

"primitivo di manduria"

# Using the Lucene Search Query Syntax

The user can perform its own Lucene queries, to do so, he needs to prefix the search query with the : sign.

Example :

: name:heracl~ AND description:blackberry^3

will execute the exact search minus the : sign against the full text search index.

# Searching without Full Text

If you uncheck the FTS options from the Schema class attributes, the following behaviour will happen :

It will make one UNION query with all the attributes with type STRING and matches on equality or starts with.

Based on the above schema, searching for primitivo will produce the following search :

MATCH (n:Wine) WHERE n.name = 'primitivo' OR n.name STARTS WITH 'primitivo' RETURN n LIMIT 20
UNION
MATCH (n:Wine) WHERE n.description = 'primitivo' OR n.description STARTS WITH 'primitivo' RETURN n LIMIT 20

# Summary

  • If one attribute has it's full text search enabled, it will consider FTS to be used on the whole class
  • Index names are considered to be the class label
  • When no FTS attributes exist, it uses an equals or starts with clause

Search is planned to be improved, we like feedback, please send it over.


# Search results snippet logic

When classes contain a large amount of attributes, the search result will display a truncated version of the item snippet with a badge for expanding all the information of the result item.

The following logic is applied to determine which attributes are shown in the snippet :

  • If you used Fine Grained Search with an attribute, the attribute will be displayed on top
  • If an attribute value contains the searched term, it will be pushed on top
  • If two attribute values match the searched term, the search relevance factors are used to re-order the attributes
  • Attributes that did not match the searched term are then based on search relevance factors if available
  • lastly, attributes are sorted alphabetically