diff --git a/_search-plugins/ubi/documentation.md b/_search-plugins/ubi/documentation.md index 484c7873e9..32c5b25f2b 100644 --- a/_search-plugins/ubi/documentation.md +++ b/_search-plugins/ubi/documentation.md @@ -15,74 +15,6 @@ to improve search relevance and user experience. ## Quick start -Build the plugin. Note that you will have to match up the JDK 11 on your system to java home in the `gradle.properties` file: -```bash -./gradlew build -``` -{% include copy.html %} - -Build the OpenSearch Docker image and add the plugin, then start the containers: - -```bash -docker compose build -docker compose up -``` -{% include copy.html %} - -Or to start a three-node OpenSearch cluster: - -```bash -docker compose build -docker compose -f docker-compose-cluster.yaml up -``` -{% include copy.html %} - -Initialize the `awesome` UBI store: - -```bash -curl -X PUT "http://localhost:9200/_plugins/ubi/awesome?index=ecommerce&object_id=id" -``` -{% include copy-curl.html %} - -Send an event to the `awesome` store: - -```bash -curl -X POST http://localhost:9200/_plugins/ubi/mystore -H "Content-Type: application/json" -d ' -{ - "action_name": "search", - "user_id": "98fcf189-4fa8-4322-b6f5-63fbb6b556c9", - "timestamp": 1705596607509 -}' -``` -{% include copy-curl.html %} - -Get events: - -```bash -curl -s http://localhost:9200/.awesome_events/_search | jq -``` -{% include copy-curl.html %} - -Do a search of the `ecommerce` index: - -```bash -curl -s http://localhost:9200/ecommerce/_search -H "X-ubi-store: awesome" | jq -``` -{% include copy-curl.html %} - -Get queries: - -```bash -curl -s http://localhost:9200/.awesome_queries/_search | jq -``` -{% include copy-curl.html %} - -Delete the store: - -```bash -curl -X DELETE http://localhost:9200/_plugins/ubi/awesome -``` -{% include copy-curl.html %} ## UBI store @@ -164,15 +96,6 @@ To make this association, queries need to have a header value that indicates the ### Example queries -The following query tells the plugin that the query being run should be persisted to the store `mystore` and be associated with user ID `john`: - -``` -http://localhost:9200/ecommerce/_search -H "X-ubi-store: mystore" -H "X-ubi-user-id: 12345" -``` -{% include copy-curl.html %} - -With this query, when the plugin sees a query, the plugin will be able to associate the query with an individual user and know to persist the query in the UBI store `mystore`. - [Sample SQL queries]({{site.url}}{{site.baseurl}}/search-plugins/ubi/sql-queries/) [Sample OpenSearch queries]({{site.url}}{{site.baseurl}}/search-plugins/ubi/dsl-queries/) diff --git a/_search-plugins/ubi/index.md b/_search-plugins/ubi/index.md index 05a69325fc..5f8403ab62 100644 --- a/_search-plugins/ubi/index.md +++ b/_search-plugins/ubi/index.md @@ -43,6 +43,6 @@ TODO: link a client implementation [here](#TODO-clients-link) | ... | teaches how to do something | - -Documentation adapted using concepts from [Diátaxis](https://diataxis.fr/) {: .tip } +Documentation adapted using concepts from [Diátaxis](https://diataxis.fr/) + diff --git a/_search-plugins/ubi/schemas.md b/_search-plugins/ubi/schemas.md index 1610cf6d71..a3e8540521 100644 --- a/_search-plugins/ubi/schemas.md +++ b/_search-plugins/ubi/schemas.md @@ -11,12 +11,12 @@ nav_order: 7 ## Key ID's UBI is not functional unless the links between the following are consistently maintained within your UBI-enabled application: -- [`user_id`](#user_id) represents a unique user. +- [`client_id`](#client_id) represents a unique user. - [`object_id`](#object_id) represents an id for whatever item the user is searching for, such as `epc`, `isbn`, `ssn`, `handle`. - [`query_id`](#query_id) is a unique id for the raw query language executed and the resultant `object_id`'s that the query returned. \ - [`action_name`](#action_name), though not technically an *id*, the `action_name` tells us what exact action (such as `click` or `add_to_cart`) was taken (or not) with this `object_id`. -To summarize: the `query_id` signals the beginning of a `user_id`'s *Search Journey*, the `action_name` tells us how the user is interacting with the query results within the application, and [`event_attributes.object.object_id`](#object_id) is referring to the precise query result that the user interacts with. +To summarize: the `query_id` signals the beginning of a `client_id`'s *Search Journey*, the `action_name` tells us how the user is interacting with the query results within the application, and [`event_attributes.object.object_id`](#object_id) is referring to the precise query result that the user interacts with. ## UBI roles - **Search Client**: in charge of searching, and then recieving *objects* from some document index in OpenSearch. @@ -32,75 +32,7 @@ To summarize: the `query_id` signals the beginning of a `user_id`'s *Search Jour (8 and 9, following section) - -```mermaid -graph LR -style L fill:none,stroke-dasharray: 5 5 -subgraph L["`*Legend*`"] - style ss height:150px - subgraph ss["Standard Search"] - direction LR - - style ln1a fill:blue - ln1a[ ]--->ln1b[ ]; - end - subgraph ubi-leg["UBI data flow"] - direction LR - - ln2a[ ].->|"`**UBI interaction**`"|ln2b[ ]; - style ln1c fill:red - ln1c[ ]-->|query_id flow|ln1d[ ]; - end -end -linkStyle 0 stroke-width:2px,stroke:#0A1CCF -linkStyle 2 stroke-width:2px,stroke:red -``` -```mermaid -%%{init: { - "flowchart": {"htmlLabels": false}, - - } -}%% -graph TB - -User--1) raw search string-->Search; -Search--2) search string-->Docs -style OS stroke-width:2px, stroke:#0A1CCF, fill:#62affb, opacity:.5 -subgraph OS[OpenSearch Cluster fa:fa-database] - style E stroke-width:1px,stroke:red - E[( UBI Events )] - style Docs stroke-width:1px,stroke:#0A1CCF - style Q stroke-width:1px,stroke:red - Docs[(Document Index)] -."3) {DSL...} & [object_id's,...]".-> Q[( UBI Queries )]; - Q -.4) query_id.-> Docs ; -end - -Docs -- "5) return both query_id & [objects,...]" --->Search ; -Search-.6) query_id.->U; -Search --7) [results, ...]--> User - -style *client-side* stroke-width:1px, stroke:#D35400 -subgraph "`*client-side*`" - style User stroke-width:4px, stroke:#EC636 - User["`**User**`" fa:fa-user] - App - Search - U - style App fill:#D35400,opacity:.35, stroke:#0A1CCF, stroke-width:2px - subgraph App[       UserApp fa:fa-store] - style Search stroke-width:2px, stroke:#0A1CCF - Search( Search Client ) - style U stroke-width:1px,stroke:red - U( UBI Client ) - end -end - -User -.8) selects object_id:123.->U; -U-."9) index event:{query_id, onClick, object_id:123}".->E; - -linkStyle 1,2,0,6 stroke-width:2px,fill:none,stroke:#0A1CCF -linkStyle 3,4,5,8 stroke-width:2px,fill:none,stroke:red -``` + ## UBI stores There are 2 separate stores for UBI: @@ -117,7 +49,7 @@ Since UBI manages the **UBI Queries** store, the developer should never have to - `query_id`   A unique ID of the query provided by the client or generated automatically. The same query text issued multiple times would generate different `query_id`. - - `user_id` + - `client_id`   A user ID provided by the client - `session_id` @@ -144,10 +76,10 @@ Since this schema is dynamic, the developer can add any new fields and structure

  (size 100) - ID for some query. Either the client provides this, or the `query_id` is generated at index time by **UBI Queries**. -- `user_id`. `session_id`, `source_id`

+- `client_id`. `session_id`, `source_id`

  (size 100) - are id's largely at the calling client's discretion for tracking users, sessions and sources (i.e. pages) of the event. - The `user_id` must be consistent in both the **UBI Queries** and **UBI Events** stores. + The `client_id` must be consistent in both the **UBI Queries** and **UBI Events** stores. - `timestamp`:   UTC-based, UNIX epoch time. @@ -208,9 +140,9 @@ Since this schema is dynamic, the developer can add any new fields and structure   optionally points to a unique id representing a successful transaction - - `event_attributes.object.to_user_id` + - `event_attributes.object.to_client_id` -   optionally points to another user, if they are the recipient of this object, perhaps as a gift, from the user's `user_id` +   optionally points to another user, if they are the recipient of this object, perhaps as a gift, from the user's `client_id` - `event_attributes.object.object_detail`   optional text for further data object details diff --git a/_search-plugins/ubi/ubi-schema-interactions.mermaid b/_search-plugins/ubi/ubi-schema-interactions.mermaid new file mode 100644 index 0000000000..dc606472be --- /dev/null +++ b/_search-plugins/ubi/ubi-schema-interactions.mermaid @@ -0,0 +1,73 @@ +contains the source for the mermaid diagrams in schemas.md +The mermaid source is converted into an png under +.../images/ubi/ubi-schema-interactions.png + + +```mermaid +graph LR +style L fill:none,stroke-dasharray: 5 5 +subgraph L["`*Legend*`"] + style ss height:150px + subgraph ss["Standard Search"] + direction LR + + style ln1a fill:blue + ln1a[ ]--->ln1b[ ]; + end + subgraph ubi-leg["UBI data flow"] + direction LR + + ln2a[ ].->|"`**UBI interaction**`"|ln2b[ ]; + style ln1c fill:red + ln1c[ ]-->|query_id flow|ln1d[ ]; + end +end +linkStyle 0 stroke-width:2px,stroke:#0A1CCF +linkStyle 2 stroke-width:2px,stroke:red +``` +```mermaid +%%{init: { + "flowchart": {"htmlLabels": false}, + + } +}%% +graph TB + +User--1) raw search string-->Search; +Search--2) search string-->Docs +style OS stroke-width:2px, stroke:#0A1CCF, fill:#62affb, opacity:.5 +subgraph OS[OpenSearch Cluster fa:fa-database] + style E stroke-width:1px,stroke:red + E[( UBI Events )] + style Docs stroke-width:1px,stroke:#0A1CCF + style Q stroke-width:1px,stroke:red + Docs[(Document Index)] -."3) {DSL...} & [object_id's,...]".-> Q[( UBI Queries )]; + Q -.4) query_id.-> Docs ; +end + +Docs -- "5) return both query_id & [objects,...]" --->Search ; +Search-.6) query_id.->U; +Search --7) [results, ...]--> User + +style *client-side* stroke-width:1px, stroke:#D35400 +subgraph "`*client-side*`" + style User stroke-width:4px, stroke:#EC636 + User["`**User**`" fa:fa-user] + App + Search + U + style App fill:#D35400,opacity:.35, stroke:#0A1CCF, stroke-width:2px + subgraph App[       UserApp fa:fa-store] + style Search stroke-width:2px, stroke:#0A1CCF + Search( Search Client ) + style U stroke-width:1px,stroke:red + U( UBI Client ) + end +end + +User -.8) selects object_id:123.->U; +U-."9) index event:{query_id, onClick, object_id:123}".->E; + +linkStyle 1,2,0,6 stroke-width:2px,fill:none,stroke:#0A1CCF +linkStyle 3,4,5,8 stroke-width:2px,fill:none,stroke:red +``` \ No newline at end of file diff --git a/images/ubi/ubi-schema-interactions.png b/images/ubi/ubi-schema-interactions.png new file mode 100644 index 0000000000..f2319bb2c1 Binary files /dev/null and b/images/ubi/ubi-schema-interactions.png differ