7.19.2. Completion

This section describes about the following completion features:

  • How it works
  • How to use
  • How to learn

7.19.2.1. How it works

The completion feature uses three searches to compute completed words:

  1. Prefix RK search against registered words.
  2. Cooccurrence search against learned data.
  3. Prefix search against registered words. (optional)

7.19.2.2. How to use

Groonga provides suggest command to use completion. --type complete option requests completion.

For example, here is an command to get completion results by "en":

Execution example:

suggest --table item_query --column kana --types complete --frequency_threshold 1 --query en
# [
#   [
#     0,
#     1337566253.89858,
#     0.000355720520019531
#   ],
#   {
#     "complete": [
#       [
#         1
#       ],
#       [
#         [
#           "_key",
#           "ShortText"
#         ],
#         [
#           "_score",
#           "Int32"
#         ]
#       ],
#       [
#         "engine",
#         1
#       ]
#     ]
#   }
# ]

7.19.2.3. How it learns

Cooccurrence search uses learned data. They are based on query logs, access logs and so on. To create learned data, Groonga needs user input sequence with time stamp and user submit input with time stamp.

For example, an user wants to search by "engine". The user inputs the query with the following sequence:

  1. 2011-08-10T13:33:23+09:00: e
  2. 2011-08-10T13:33:23+09:00: en
  3. 2011-08-10T13:33:24+09:00: eng
  4. 2011-08-10T13:33:24+09:00: engi
  5. 2011-08-10T13:33:24+09:00: engin
  6. 2011-08-10T13:33:25+09:00: engine (submit!)

Groonga can be learned from the input sequence by the following command:

load --table event_query --each 'suggest_preparer(_id, type, item, sequence, time, pair_query)'
[
{"sequence": "1", "time": 1312950803.86057, "item": "e"},
{"sequence": "1", "time": 1312950803.96857, "item": "en"},
{"sequence": "1", "time": 1312950804.26057, "item": "eng"},
{"sequence": "1", "time": 1312950804.56057, "item": "engi"},
{"sequence": "1", "time": 1312950804.76057, "item": "engin"},
{"sequence": "1", "time": 1312950805.86057, "item": "engine", "type": "submit"}
]

7.19.2.4. How to update reading data

Groonga requires registered word and its reading for prefix RK search. This section describes how to register a word and its reading.

Here is an example to register "日本" which means Japan in English:

Execution example:

load --table event_query --each 'suggest_preparer(_id, type, item, sequence, time, pair_query)'
[
{"sequence": "1", "time": 1312950805.86058, "item": "日本", "type": "submit"}
]
# [[0, 1337566253.89858, 0.000355720520019531], 1]

Here is an example to update reading data to complete "日本":

Execution example:

load --table item_query
[
{"_key":"日本", "kana":["ニホン", "ニッポン"]}
]
# [[0, 1337566253.89858, 0.000355720520019531], 1]

Then you can complete registered word "日本" by Romaji input - "nihon".

Execution example:

suggest --table item_query --column kana --types complete --frequency_threshold 1 --query nihon
# [
#   [
#     0,
#     1337566253.89858,
#     0.000355720520019531
#   ],
#   {
#     "complete": [
#       [
#         1
#       ],
#       [
#         [
#           "_key",
#           "ShortText"
#         ],
#         [
#           "_score",
#           "Int32"
#         ]
#       ],
#       [
#         "日本",
#         2
#       ]
#     ]
#   }
# ]

Without loading above reading data, you can't complete registered word "日本" by query - "nihon".

You can register multiple readings for a registered word because kana column in item_query table is defined as a Vector column.

This is the reason that you can also complete the registered word "日本" by query - "nippon".

Execution example:

suggest --table item_query --column kana --types complete --frequency_threshold 1 --query nippon
# [
#   [
#     0,
#     1337566253.89858,
#     0.000355720520019531
#   ],
#   {
#     "complete": [
#       [
#         1
#       ],
#       [
#         [
#           "_key",
#           "ShortText"
#         ],
#         [
#           "_score",
#           "Int32"
#         ]
#       ],
#       [
#         "日本",
#         2
#       ]
#     ]
#   }
# ]

This feature is very convenient because you can search registered word even though Japanese input method is disabled.

If there are multiple candidates as completed result, you can customize priority to set the value of boost column in item_query table.

Here is an example to customize priority for prefix RK search:

Execution example:

load --table event_query --each 'suggest_preparer(_id, type, item, sequence, time, pair_query)'
[
{"sequence": "1", "time": 1312950805.86059, "item": "日本語", "type": "submit"}
{"sequence": "1", "time": 1312950805.86060, "item": "日本人", "type": "submit"}
]
# [[0, 1337566253.89858, 0.000355720520019531], 2]
load --table item_query
[
{"_key":"日本語", "kana":"ニホンゴ"}
{"_key":"日本人", "kana":"ニホンジン"}
]
# [[0, 1337566253.89858, 0.000355720520019531], 2]
suggest --table item_query --column kana --types complete --frequency_threshold 1 --query nihon
# [
#   [
#     0,
#     1337566253.89858,
#     0.000355720520019531
#   ],
#   {
#     "complete": [
#       [
#         3
#       ],
#       [
#         [
#           "_key",
#           "ShortText"
#         ],
#         [
#           "_score",
#           "Int32"
#         ]
#       ],
#       [
#         "日本",
#         2
#       ],
#       [
#         "日本人",
#         2
#       ],
#       [
#         "日本語",
#         2
#       ]
#     ]
#   }
# ]
load --table item_query
[
{"_key":"日本人", "boost": 100},
]
# [[0, 1337566253.89858, 0.000355720520019531], 1]
suggest --table item_query --column kana --types complete --frequency_threshold 1 --query nihon
# [
#   [
#     0,
#     1337566253.89858,
#     0.000355720520019531
#   ],
#   {
#     "complete": [
#       [
#         3
#       ],
#       [
#         [
#           "_key",
#           "ShortText"
#         ],
#         [
#           "_score",
#           "Int32"
#         ]
#       ],
#       [
#         "日本人",
#         102
#       ],
#       [
#         "日本",
#         2
#       ],
#       [
#         "日本語",
#         2
#       ]
#     ]
#   }
# ]