reworking how we articulate hit->object linkage with key fields and k…

documentation/documentation.md

@@ -27,7 +27,7 @@ docker compose -f docker-compose-cluster.yaml up
 Initialize the `awesome` UBI store:
 
 ```
-curl -X PUT "http://localhost:9200/_plugins/ubi/awesome?index=ecommerce&id_field=name"
+curl -X PUT "http://localhost:9200/_plugins/ubi/awesome?index=ecommerce&id_field=id"
 ```
 
 Send an event to the `awesome` store:
@@ -85,19 +85,23 @@ The current event mappings file can be found [here](https://github.com/o19s/open
 - `message` - (size 256) - optional text for the log entry
 
 **Other fields & data objects**
-- `event_attributes.position` - nested object to track user events to the location of the event origins
-  - `event_attributes.position.ordinal` - tracks the nth item within a list that a user could select, click
-  - `event_attributes.position.{x,y}` - tracks x and y values, that the client defines
-  - `event_attributes.position.page_depth` - tracks page depth
-  - `event_attributes.position.scroll_depth` - tracks scroll depth
-  - `event_attributes.position.trail` - text field for tracking the path/trail that a user took to get to this location
 - `event_attributes.object` - contains an associated JSONified data object (i.e. books, products, user info, etc) if there are any
+  - `event_attributes.object.object_id` - points to a unique, internal, id representing and instance of that object
+  - `event_attributes.object.key_value` - points to a unique, external key, matching the item that the user searched for, found and acted upon (i.e. sku, isbn, ean, etc.). 
+    **This field value should match the value in for the object's value in the `id_field` [below](#id_field) from the search store**
+     It is possible that the `object_id` and `key_value` match if the same id is used both internally for indexing and externally for the users. 
   - `event_attributes.object.object_type` - indicates the type/class of object
-  - `event_attributes.object.object_id` - points to a unique id representing and instance of that object
   - `event_attributes.object.description` - optional description of the object
   - `event_attributes.object.transaction_id` - optionally points to a unique id representing a successful transaction
   - `event_attributes.object.to_user_id` - optionally points to another user, if they are the recipient of this object
   - `event_attributes.object.object_detail` - optional data object/map of further data details
+- `event_attributes.position` - nested object to track user events to the location of the event origins
+  - `event_attributes.position.ordinal` - tracks the nth item within a list that a user could select, click
+  - `event_attributes.position.{x,y}` - tracks x and y values, that the client defines
+  - `event_attributes.position.page_depth` - tracks page depth
+  - `event_attributes.position.scroll_depth` - tracks scroll depth
+  - `event_attributes.position.trail` - text field for tracking the path/trail that a user took to get to this location
+
 * Other mapped fields in the schema are intended to be optional placeholders for common attributes like `user_name`, `email`, `price`
 
 **the users can dynamically add any further fields to the event mapping
@@ -118,7 +122,7 @@ The plugin exposes a REST API for managing UBI stores and persisting events.
 
 | Method | Endpoint                                                  | Purpose                                                                                                                                                                                                                                   |
 |--------|-----------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `PUT`    | `/_plugins/ubi/{store}?index={index}&id_field={id_field}` | Create a new UBI store for the given index. The `id_field` is optional and allows for providing the name of a field in the `index`'s schema to be used as the unique ID for each search result. If not provided, the `_id` field is used. |
+| `PUT`    | `/_plugins/ubi/{store}?index={index}&id_field={id_field}` | <p id="id_field">Initialize a new UBI store for the given index. The `id_field` is optional and allows for providing the name of a field in the `index`'s schema to be used as the unique result/item ID for each search result. If not provided, the `_id` field is used. </p>|
 | `DELETE` | `/_plugins/ubi/{store}`                                   | Delete a UBI store                                                                                                                                                                                                                        |
 | `GET` | `/_plugins/ubi`                                           | Get a list of all UBI stores                                                                                                                                                                                                              |
 | `POST` | `/_plugins/ubi/{store}`                                   | Index an event into the UBI store                                                                                                                                                                                                         |

src/main/resources/events-mapping.json

@@ -91,6 +91,9 @@
         },
         "object": {
           "properties": {
+            "key_value": {
+              "type": "keyword"
+            },
             "object_id": {
               "type": "keyword",
               "ignore_above": 256
@@ -103,6 +106,10 @@
               "type": "keyword",
               "ignore_above": 100
             },
+            "name": {
+              "type": "keyword",
+              "ignore_above": 256
+            },
             "description": {
               "type": "text",
               "fields": {