Skip to content

Commit

Permalink
Restructure content into clearer four types.
Browse files Browse the repository at this point in the history 
Signed-off-by: Eric Pugh <epugh@opensourceconnections.com>
  • Loading branch information
@epugh
epugh committed Feb 17, 2025
1 parent eba662e commit c9f610c
Showing 1 changed file with 49 additions and 24 deletions.
73 changes: 49 additions & 24 deletions _search-plugins/ubi/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,38 +14,63 @@ redirect_from:
**References UBI Specification 1.2.0**
{: .label .label-purple }

User Behavior Insights (UBI) is a project for capturing client-side events and queries for the purposes of improving search relevance and the user experience.
User Behavior Insights (UBI) is a standard for capturing client-side events and queries for the purposes of improving search relevance and the user experience.
It is a *causal* system, linking a user's query to all of their subsequent interactions with your application until they perform another search.
This differs from many systems that infer the linking of search to events through *chronological* sequence.

UBI includes the following elements:
* A machine-readable [schema](https://github.com/o19s/ubi) that faciliates interoperablity of the UBI specification.
* An OpenSearch [plugin](https://github.com/opensearch-project/user-behavior-insights) that facilitates the storage of client-side events and queries.
* A client-side JavaScript [reference implementation](https://github.com/opensearch-project/user-behavior-insights/tree/main/ubi-javascript-collector/ubi.js) that shows how to capture searches and events.

<!-- vale off -->

The UBI documentation is organized into two categories: *Explanation and reference* and *Tutorials and how-to guides*:
> “how our users are using our product, whether search results were useful for them and whether they clicked on top-n results we gave and all related stuff” - Data Scientist
*Explanation and reference*

| Link | Description |
| :--------- | :------- |
| [UBISearch.dev](https://UBISearch.dev) | The User Behavior Insights community website. |
| [UBI Request/Response Specification](https://github.com/o19s/ubi/) | The industry-standard schema for UBI requests and responses. The current version references UBI Specification 1.2.0. |
| [UBI index schema]({{site.url}}{{site.baseurl}}/search-plugins/ubi/schemas/) | Documentation on the individual OpenSearch query and event stores. |
UBI includes the following elements:
* [ubi.js](https://github.com/opensearch-project/user-behavior-insights/tree/main/ubi-javascript-collector/ubi.js): a client-side JavaScript library that captures searches and events.
* A machine-readable [schema](https://github.com/o19s/ubi) that faciliates interoperablity of the UBI specification.

Check failure on line 26 in _search-plugins/ubi/index.md

View workflow job for this annotation

GitHub Actions / style-job 

[vale] reported by reviewdog 🐶
[OpenSearch.Spelling] Error: faciliates. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.

Raw Output:
{"message": "[OpenSearch.Spelling] Error: faciliates. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.", "location": {"path": "_search-plugins/ubi/index.md", "range": {"start": {"line": 26, "column": 65}}}, "severity": "ERROR"}

Check failure on line 26 in _search-plugins/ubi/index.md

View workflow job for this annotation

GitHub Actions / style-job 

[vale] reported by reviewdog 🐶
[OpenSearch.Spelling] Error: interoperablity. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.

Raw Output:
{"message": "[OpenSearch.Spelling] Error: interoperablity. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.", "location": {"path": "_search-plugins/ubi/index.md", "range": {"start": {"line": 26, "column": 76}}}, "severity": "ERROR"}
* An (optional!) OpenSearch [plugin](https://github.com/opensearch-project/user-behavior-insights) that streamlines the recording of query data.

Advanced features in OpenSearch, such as the Search Quality Evaluation Framework, and the Hybrid Search Optimizer all build on the UBI specification.

*Tutorials and how-to guides*
<!-- vale off -->

| Link | Description |
| :--------- | :------- |
| [UBI plugin](https://github.com/opensearch-project/user-behavior-insights) | How to install and use the UBI plugin. |
| [UBI JavaScript Collector]({{site.url}}{{site.baseurl}}/search-plugins/ubi/ubi-javascript-collector/) | Clientside JavaScript library to capture events. |
| [Example UBI query DSL queries]({{site.url}}{{site.baseurl}}/search-plugins/ubi/dsl-queries/) | How to write queries for UBI data in OpenSearch query DSL. |
| [Example UBI SQL queries]({{site.url}}{{site.baseurl}}/search-plugins/ubi/sql-queries/) | How to write analytic queries for UBI data in SQL. |
| [UBI dashboard tutorial]({{site.url}}{{site.baseurl}}/search-plugins/ubi/ubi-dashboard-tutorial/) | How to build a dashboard containing UBI data. |
| [Chorus Opensearch Edition](https://github.com/o19s/chorus-opensearch-edition/?tab=readme-ov-file#structured-learning-using-chorus-opensearch-edition) katas | A series of structured tutorials that teach you how to use UBI with OpenSearch through a demo e-commerce store. |
<table>
<tr style="vertical-align: top;">
<td>
<h2>Tutorials</h2>
<ul>
<li><a href="#">Learn to use <code>ubi.js</code></a></li>
<li><a href="#">Using OpenSearch Ingestion from AWS with UBI</a></li>
<li><a href="#">Link 3</a></li>
</ul>
</td>
<td>
<h2>How To Guides</h2>
<ul>
<li><a href="https://github.com/opensearch-project/user-behavior-insights">How to install and use the UBI plugin</a><b>do we keep this</b></li>
<li><a href="{{site.url}}{{site.baseurl}}/search-plugins/ubi/ubi-dashboard-tutorial/">How to build a custom dashboard with UBI data.</a></li>
<li><a href="{{site.url}}{{site.baseurl}}/search-plugins/ubi/dsl-queries/">How to write queries for UBI data in OpenSearch query DSL.</a></li>
<li><a href="{{site.url}}{{site.baseurl}}/search-plugins/ubi/sql-queries/">How to write analytic queries for UBI data in SQL.</a></li>
<li><a href="https://github.com/o19s/chorus-opensearch-edition/blob/main/katas/006_protecting_sensitive_information.md">How to protect sensistive information when using UBI.</a> <small>Part of Chorus series.</small></li>
</ul>
</td>
</tr>
<tr style="vertical-align: top;">
<td>
<h2>Explanation</h2>
<ul>
<li><a href="https://UBISearch.dev">Why UBI?</a></li>
<li><a href="">How should I integrate UBI tracking?</a></li>
<li><a href="https://UBISearch.dev">UBISearch.dev</a> is the community website.</li>
<li><a href="{{site.url}}{{site.baseurl}}/search-plugins/ubi/ubi-javascript-collector/">UBI.js</a> JavaScript collector</li>
</ul>
</td>
<td>
<h2>Reference</h2>
<ul>
<li><a href="https://o19s.github.io/ubi/docs/html/1.2.0/query.request.schema.html">Query Tracking Specification</a></li>
<li><a href="https://o19s.github.io/ubi/docs/html/1.2.0/event.schema.html">Event Tracking Specification</a></li>
<li><a href="{{site.url}}{{site.baseurl}}/search-plugins/ubi/schemas/">UBI Plugin Schema</a><b>DO WE KEEP THIS</b></li>
</ul>
</td>
</tr>
</table>

<!-- vale on -->
The documentation categories were adapted using concepts based on [Diátaxis](https://diataxis.fr/).
Expand Down

0 comments on commit c9f610c

Please sign in to comment.