From 87cd4ccbbf3ba15af5d420750d39b6a9aee89eac Mon Sep 17 00:00:00 2001 From: Spencer Markowski Date: Wed, 20 Mar 2024 14:19:06 -0400 Subject: [PATCH] Update guides --- docs/examples/semantic_search_with_llm.md | 2 +- docs/examples/simple-ingest-pipeline.md | 7 +++---- docs/guides/aggregations.md | 5 ++++- docs/guides/machine-learning.md | 8 ++++++-- docs/guides/models.md | 2 +- docs/guides/querying.md | 11 +++++++---- docs/guides/quick-start.md | 9 +++++---- docs/guides/scopes.md | 2 +- 8 files changed, 28 insertions(+), 18 deletions(-) diff --git a/docs/examples/semantic_search_with_llm.md b/docs/examples/semantic_search_with_llm.md index cbaf988..a58a2e7 100644 --- a/docs/examples/semantic_search_with_llm.md +++ b/docs/examples/semantic_search_with_llm.md @@ -1,6 +1,6 @@ # Semantic Search with LLMs ->[!INFO|style:flat] +>[!INFO|style:flat|label:OpenSearch Only] > This guide only works with features found in Opensearch 2.12+ **Prerequisites:** diff --git a/docs/examples/simple-ingest-pipeline.md b/docs/examples/simple-ingest-pipeline.md index 813c17e..82fc72b 100644 --- a/docs/examples/simple-ingest-pipeline.md +++ b/docs/examples/simple-ingest-pipeline.md @@ -1,10 +1,9 @@ # Simple Ingest Pipeline ->[!INFO|style:flat] ->**Prerequisites:** +>[!INFO|style:flat:label:Prerequisites] > ->- Opensearch installed and running ->- Ruby on Rails or stretchy-model's `bin/console` +>- Opensearch 2.12+ installed and running +>- Ruby on Rails > >Follow the [Quick Start](guides/quick-start) for detailed steps. diff --git a/docs/guides/aggregations.md b/docs/guides/aggregations.md index 8051bb6..1acd523 100644 --- a/docs/guides/aggregations.md +++ b/docs/guides/aggregations.md @@ -27,7 +27,10 @@ returns: } ``` -> You can access the entire structure through dot notation. `aggregations.flagged_counts.buckets.first.doc_count` => `123` +>[!TIP|label:Accessing Aggregation Results] +>You can access the entire structure through dot notation. +> +>`aggregations.flagged_counts.buckets.first.doc_count` => `123` --- diff --git a/docs/guides/machine-learning.md b/docs/guides/machine-learning.md index 341000b..f7807f8 100644 --- a/docs/guides/machine-learning.md +++ b/docs/guides/machine-learning.md @@ -1,10 +1,10 @@ # Machine Learning ->[!NOTE|style:flat] +>[!NOTE|style:flat|label:OpenSearch Compatability] > OpenSearch and Elasticsearch diverge in how they handle machine learning APIs. These features are in active development and subject to change. > > This guide largely covers OpenSearch Machine Learning unless otherwise stated. ->[!WARNING] +>[!WARNING|label:Machine Learning on Elasticsearch] > Elasticsearch requires a license to enable ML capabilities ## Models @@ -34,6 +34,10 @@ end ## Managing Models +>[!TIP|label:Machine Learning Settings] +> When running development or single-node clusters you may need to adjust your cluster settings to allow Machine Learning models to run on all nodes instead of dedicated machine learning nodes. +> Add `Stretchy::MachineLearning::Model.ml_on_all_nodes!` to your *config/environments/development.rb* file to enable machine learning on all nodes. + ### register Registers the machine learning model. diff --git a/docs/guides/models.md b/docs/guides/models.md index cc0de64..ef611ea 100644 --- a/docs/guides/models.md +++ b/docs/guides/models.md @@ -313,7 +313,7 @@ Associations largely work the same as their Rails counterparts. The following as * `has_one` ->[!WARNING] +>[!WARNING|label:Associations in Elasticsearch] > > Because Elasticsearch is not a relational database, there are no join statements. This means associations will generate additional queries to fetch data. diff --git a/docs/guides/querying.md b/docs/guides/querying.md index 4b86c1f..e2ec1bd 100644 --- a/docs/guides/querying.md +++ b/docs/guides/querying.md @@ -3,6 +3,9 @@ ## Adding Query Conditions ### Must +>[!TIP|style:flat|label:where] +> `.where` is aliased as `.must` and is provided for familiarity. They are interchangeable in functionality. + The `.where` method is used to filter the documents that should be returned from a search. It adds conditions to the `must` clause of the query, which means that only documents that match all of the conditions will be returned. The `.where` method is flexible and can accept multiple conditions and different types of expressions. The `.where` method returns a new `Stretchy::Relation` object, so you can chain other methods onto it to further refine your search. Here are some examples of how it can be used: @@ -12,7 +15,7 @@ You can pass one or more key-value pairs to `.where` to search for documents whe Model.where(color: 'blue', :title: "Candy") ``` -#### Ranges +##### Ranges You can use ranges to search for documents where a field's value falls within a certain range. For example, ```ruby Model.where(date: 2.days.ago...1.day.ago) @@ -22,13 +25,13 @@ Model.where(age: 18..30) Model.where(price: {gte: 100, lt: 140}) ``` -#### Regex +##### Regex You can use regular expressions to search for documents where a field's value matches a certain pattern. ```ruby Model.where(name: /br.*n/i) ``` -#### Terms +##### Terms You can use an array of values to search for documents where a field's value is in the array. ```ruby Model.where(name: ['Candy', 'Lilly']) @@ -254,7 +257,7 @@ In this example, the `:routing` requirement is skipped for the immediate query. Please note that skipping callbacks can potentially harm performance and lead to unexpected results, so it should be used sparingly and only when necessary. ## Vector Search ->[!NOTE|style:flat] +>[!NOTE|style:flat|label:Compatability ] > Some of these features only work with Opensearch 2.12+ or require an Elasticsearch license to access Machine Learning features. Before using neural search, you must set up a [Machine Learning](guides/machine-learning?id=machine-learning) model. diff --git a/docs/guides/quick-start.md b/docs/guides/quick-start.md index d7c36a4..10fb946 100644 --- a/docs/guides/quick-start.md +++ b/docs/guides/quick-start.md @@ -4,10 +4,11 @@ - Ruby and Rails installed on your machine ->[!TIP|style:flat] +>[!TIP|style:flat|label:Single Node Clusters] > These docker commands will run a single-node cluster suitable for local development. -> -> Choose Elasticsearch or OpenSearch + + +#### Choose Elasticsearch or OpenSearch __Start Elasticsearch:__ @@ -31,7 +32,7 @@ cd fantastic_thing bundle add stretchy-model ``` -> [!INFO|style:flat] +> [!INFO|style:flat|label:OpenSearch] > If using Opensearch be sure to add it to your Gemfile: > ```sh diff --git a/docs/guides/scopes.md b/docs/guides/scopes.md index fa48a61..5e0fb21 100644 --- a/docs/guides/scopes.md +++ b/docs/guides/scopes.md @@ -59,7 +59,7 @@ class Model < StretchyModel end ``` -> [!TIP] +> [!TIP|label:Naming Conventions] > _Implementing a naming convention for aggregation scopes can help make your code more readable and maintainable. By appending `_agg` to the name of aggregation scopes, you can easily distinguish them from other scopes._ In this example, a scope named `average_rating_agg` is defined. This scope includes an aggregation that calculates the average value of the `rating` field.