opensearch-sugar 1.0.0

data/docs/TUTORIAL.md

@@ -0,0 +1,327 @@
+# Getting Started with opensearch-sugar
+
+Created by various AI agents. 
+
+By the end of this tutorial you will have a running, searchable book catalog: a live
+OpenSearch index with custom text analysis, structured field mappings, real documents,
+and a working full-text search query.
+
+## What you'll build
+
+A Ruby script that connects to a local OpenSearch cluster, configures a `books` index
+with a custom analyzer, adds three documents, and queries them by keyword.
+
+## Before you start
+
+- Ruby 3.1 or higher
+- Docker installed and running
+- Basic familiarity with running Ruby scripts from the terminal
+
+---
+
+## Step 1: Start OpenSearch
+
+Run a single-node OpenSearch container:
+
+```bash
+docker run -d \
+  -p 9200:9200 \
+  -e "discovery.type=single-node" \
+  -e "OPENSEARCH_INITIAL_ADMIN_PASSWORD=MyPassword123!" \
+  --name opensearch-tutorial \
+  opensearchproject/opensearch:latest
+```
+
+Wait about 30 seconds, then confirm it is up:
+
+```bash
+curl -sk https://localhost:9200 -u admin:MyPassword123! | ruby -e "require 'json'; puts JSON.parse(STDIN.read)['tagline']"
+```
+
+The output should be:
+
+```
+The OpenSearch Project: https://opensearch.org/
+```
+
+## Step 2: Install the gem
+
+Create a project directory and a `Gemfile`:
+
+```bash
+mkdir book-catalog && cd book-catalog
+```
+
+```ruby
+# Gemfile
+source "https://rubygems.org"
+gem "opensearch-sugar"
+gem "dotenv"
+```
+
+```bash
+bundle install
+```
+
+Create a `.env` file with your connection details:
+
+```
+OPENSEARCH_URL=https://localhost:9200
+OPENSEARCH_USER=admin
+OPENSEARCH_PASSWORD=MyPassword123!
+```
+
+## Step 3: Connect to the cluster
+
+Create `catalog.rb`:
+
+```ruby
+require "opensearch/sugar"
+require "dotenv/load"
+
+client = OpenSearch::Sugar::Client.new
+puts client.ping ? "Connected!" : "Could not connect"
+puts "Existing indexes: #{client.index_names}"
+```
+
+Run it:
+
+```bash
+bundle exec ruby catalog.rb
+```
+
+You should see:
+
+```
+Connected!
+Existing indexes: []
+```
+
+Notice that `index_names` returns only user-created indexes — system indexes are hidden.
+
+## Step 4: Create the books index
+
+Add to `catalog.rb`:
+
+```ruby
+index = client.open_or_create_index("books")
+puts "Index '#{index.name}' ready. Documents: #{index.count}"
+```
+
+The output should be:
+
+```
+Index 'books' ready. Documents: 0
+```
+
+Notice that `open_or_create_index` is safe to call repeatedly — it creates the index on
+the first run and opens it on subsequent runs.
+
+## Step 5: Configure a custom analyzer
+
+Add the settings block. This must be done before you add documents:
+
+```ruby
+index.update_settings(
+  settings: {
+    analysis: {
+      filter: {
+        book_stop: {
+          type: "stop",
+          stopwords: ["the", "a", "an", "and", "or", "of"]
+        }
+      },
+      analyzer: {
+        book_title: {
+          type: "custom",
+          tokenizer: "standard",
+          filter: ["lowercase", "asciifolding", "book_stop"]
+        }
+      }
+    }
+  }
+)
+puts "Settings applied."
+```
+
+## Step 6: Map the fields
+
+```ruby
+index.update_mappings(
+  mappings: {
+    properties: {
+      title:       { type: "text", analyzer: "book_title" },
+      author:      { type: "text" },
+      description: { type: "text", analyzer: "book_title" },
+      isbn:        { type: "keyword" },
+      year:        { type: "integer" },
+      categories:  { type: "keyword" }
+    }
+  }
+)
+puts "Mappings applied."
+```
+
+## Step 7: Verify the analyzer
+
+Before adding data, confirm the analyzer tokenizes as expected:
+
+```ruby
+tokens = index.test_analyzer_by_name(analyzer: "book_title", text: "The Lord of the Rings")
+puts "Tokens: #{tokens.join(", ")}"
+```
+
+The output should be:
+
+```
+Tokens: lord, rings
+```
+
+Notice that "the", "of", and "a" are removed by the `book_stop` filter — those words
+will not be indexed and do not need to appear in queries.
+
+## Step 8: Add books
+
+```ruby
+books = [
+  {
+    title: "The Hobbit",
+    author: "J.R.R. Tolkien",
+    description: "A hobbit's unexpected journey through Middle-earth.",
+    isbn: "978-0547928227",
+    year: 1937,
+    categories: ["fantasy", "adventure"]
+  },
+  {
+    title: "1984",
+    author: "George Orwell",
+    description: "A dystopian novel about totalitarian surveillance.",
+    isbn: "978-0451524935",
+    year: 1949,
+    categories: ["dystopian", "classic"]
+  },
+  {
+    title: "To Kill a Mockingbird",
+    author: "Harper Lee",
+    description: "Racial injustice in the American South, seen through a child's eyes.",
+    isbn: "978-0061120084",
+    year: 1960,
+    categories: ["classic", "drama"]
+  }
+]
+
+books.each { |b| index.index_document(b, b[:isbn]) }
+index.refresh
+puts "Indexed #{index.count} books."
+```
+
+The output should be:
+
+```
+Indexed 3 books.
+```
+
+Notice the call to `index.refresh` — without it, the documents may not be visible to
+search queries immediately.
+
+## Step 9: Compare index-time and search-time tokenization
+
+Before searching, confirm how your analyzer transforms text — this makes unexpected
+search results much easier to diagnose later.
+
+```ruby
+title = "The Fellowship of the Ring"
+
+index_tokens  = index.test_analyzer_by_name(analyzer: "book_title", text: title)
+search_tokens = index.test_analyzer_by_name(analyzer: "standard",   text: title)
+
+puts "Indexed as:  #{index_tokens.join(", ")}"
+puts "Standard as: #{search_tokens.join(", ")}"
+```
+
+The output should be:
+
+```
+Indexed as:  fellowship, ring
+Standard as: the, fellowship, the, ring
+```
+
+Notice that `book_title` removes stop words ("the", "of") while the built-in `standard`
+analyzer keeps them. A query using `standard` would include tokens your index never
+stored — understanding this gap is the key to debugging zero-result searches.
+
+## Step 10: Search the catalog
+
+
+
+```ruby
+results = client.search(
+  index: "books",
+  body: {
+    query: {
+      multi_match: {
+        query: "fantasy adventure",
+        fields: ["title^2", "description", "categories"]
+      }
+    }
+  }
+)
+
+puts "\nSearch results for 'fantasy adventure':"
+results["hits"]["hits"].each do |hit|
+  src = hit["_source"]
+  puts "  #{src["title"]} by #{src["author"]} (score: #{hit["_score"].round(2)})"
+end
+```
+
+The output should be:
+
+```
+Search results for 'fantasy adventure':
+  The Hobbit by J.R.R. Tolkien (score: 1.23)
+```
+
+Notice that `client.search` is the standard OpenSearch Ruby client method — opensearch-sugar
+delegates all methods it does not define directly to the underlying client.
+
+## Step 11: Create an alias
+
+```ruby
+index.create_alias("current_catalog")
+puts "Aliases: #{index.aliases.join(", ")}"
+
+# Access the same index through the alias
+via_alias = client["current_catalog"]
+puts "Documents via alias: #{via_alias.count}"
+```
+
+The output should be:
+
+```
+Aliases: current_catalog
+Documents via alias: 3
+```
+
+## What you've built
+
+You have connected to OpenSearch, created a custom analyzer, mapped fields, indexed
+documents, run a full-text search, and set up an alias.
+
+Your `catalog.rb` is now a working foundation for any Ruby application that needs
+structured, full-text search.
+
+## Next steps
+
+- **Solve specific problems** → [How-to Guides](HOWTO.md)
+- **Look up a method** → [API Reference](REFERENCE.md)
+- **Understand the design** → [Explanation](EXPLANATION.md)
+
+## Clean up
+
+```ruby
+index.delete!
+```
+
+```bash
+docker stop opensearch-tutorial && docker rm opensearch-tutorial
+```

data/docs/alias-api-design-notes.md

@@ -0,0 +1,119 @@
+# Index Alias API Design Notes
+
+Working notes for expanding alias support in `OpenSearch::Sugar::Index`.
+Not finished — pick up here.
+
+---
+
+## Current state
+
+`Index` has two alias methods:
+
+```ruby
+def aliases
+  # Returns Array<String> of alias names only
+  response = client.indices.get_alias(index: name)
+  response.dig(name, "aliases")&.keys || []
+end
+
+def create_alias(alias_name)
+  # Creates the alias, returns updated Array<String>
+  client.indices.put_alias(index: name, name: alias_name)
+  aliases
+end
+```
+
+Covered by `spec/opensearch/sugar/index/aliases_spec.rb`.
+
+---
+
+## Critique of current methods
+
+**`#aliases`**
+- Name is fine; reads naturally.
+- Lossy: discards all alias metadata (`filter`, `routing`, `is_write_index`). Can't answer "is this a write alias?" without hitting the raw client.
+
+**`#create_alias`**
+- Name is clear.
+- The `@raise BadRequest` YARD note is misleading — OpenSearch may silently move the alias rather than error, depending on configuration.
+- No support for alias-level parameters: `filter`, `routing`, `index_routing`, `search_routing`, `is_write_index`.
+
+---
+
+## What the OpenSearch API offers (not yet wrapped)
+
+### Missing operations
+
+| Method | HTTP | Notes |
+|---|---|---|
+| `delete_alias(name)` | `DELETE /<index>/_alias/<alias>` | Symmetry with create |
+| `alias?(name)` | `HEAD /<index>/_alias/<alias>` | Returns bool; 200 = exists |
+| Atomic swap | `POST /_aliases` (bulk actions) | add + remove in one atomic call; standard for zero-downtime reindex |
+
+### Missing parameters on `create_alias`
+
+| Param | Type | Purpose |
+|---|---|---|
+| `filter:` | Hash (query DSL) | Filtered alias — only surfaces matching docs |
+| `is_write_index:` | Boolean | Designates this index as the write target |
+| `routing:` | String | Routing for both index and search |
+| `index_routing:` | String | Routing for indexing only |
+| `search_routing:` | String | Routing for search only |
+
+---
+
+## Design options
+
+### Option A — Simple completeness (no breaking changes)
+
+Keep `aliases` returning `Array<String>`. Add missing operations and params.
+
+```
+#aliases                                    → Array<String>   (unchanged)
+#create_alias(name, filter: nil,            → Array<String>   (add keyword params)
+              routing: nil, is_write_index: nil)
+#delete_alias(name)                         → Array<String>   (new)
+#alias?(name)                               → Boolean         (new)
+```
+
+Atomic swap is not covered; caller uses raw client.
+
+### Option B — Richer return values + atomic swap
+
+```
+#aliases                                    → Hash<String, Hash>  (BREAKING — name => metadata)
+#add_alias(name, **opts)                    → Hash             (rename of create_alias)
+#remove_alias(name)                         → Hash
+#alias?(name)                               → Boolean
+#swap_alias(from:, to:)                     → result of /_aliases bulk call
+```
+
+Rename `aliases` return type is breaking unless old method is aliased.
+
+### Option C — Separate name list from full detail
+
+```
+#alias_names                                → Array<String>   (rename of current #aliases)
+#aliases                                    → Hash<String, Hash>  (full metadata)
+#create_alias(name, **opts)                 → keep name, add opts
+#delete_alias(name)                         → new
+#alias?(name)                               → new
+#swap_alias(old_alias:, new_alias:)         → new
+```
+
+---
+
+## Open questions
+
+1. Should `aliases` stay `Array<String>` or become a richer Hash (with metadata)?
+2. `delete_alias` vs `remove_alias` — match the API verb (`delete`) or use a softer Ruby name (`remove`)?
+3. Is `swap_alias` worth adding? It's the standard pattern for zero-downtime index cutover.
+4. Should `create_alias` grow keyword params (`filter:`, `routing:`, `is_write_index:`) or stay simple?
+
+---
+
+## Recommendation (starting point)
+
+Option A is the lowest-risk starting point — no breaking changes, fills the obvious gaps.
+Add `delete_alias`, `alias?`, and keyword params on `create_alias`.
+If `swap_alias` is wanted, add it standalone — it's high value for reindex workflows.