caoutsearch 0.0.5 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a9f19fbbee99086c07a66881e1b3d5f5df90f4dc06d32ce4a4d4dfc323a85bb
-  data.tar.gz: cf8736b55478e95f3e98a529d9e2f4102de8a59921108bf99703d9c6fe742a54
+  metadata.gz: 2d22b648c6800d29d075baa757ec80d6c1429752918db6fb899fb7484d3ff9f7
+  data.tar.gz: 03fdbf0e6cd2dcc966bf435e9ea7e48ede4e14bd0ae3ec50215cb6867b07d90a
 SHA512:
-  metadata.gz: 3ee219e96b1b77bbdea6b20a91bb252915b2f557c82924892e67d9ca6d08caf7013f8a8ac05852375f9821cda4e7fb0ba23226ff04943e03a4a7f2d16dd80bf4
-  data.tar.gz: d154e911d74f71f14540d551ead74a9452770660a8be4b991a73d2d2dbed3a206274b51a30b1c7090587e6bbdea389729104af293fd6f542211ae7fd952ec12a
+  metadata.gz: 129553e5adac2bf6e4c4158ce977812ee49e7c05381987ba8a45e4f2dc6e9cac9a1d9203ca8f36e8a72fa8e0e0bc40ad11141db2adc8e5858ae8694e3bed39f5
+  data.tar.gz: e2207e9d3d647a4f4465aaf11ec9f5a7cbde73b1db4867b45b56ad67ffcc5d86be639cb03ec965cdc25ea1c686c1e3fd1e9805035cb946fdf051af8306547063

data/README.md

@@ -1,13 +1,13 @@
 # Caoutsearch [\ˈkawt͡ˈsɝtʃ\\](http://ipa-reader.xyz/?text=ˈkawt͡ˈsɝtʃ)
 
-[![Gem Version](https://badge.fury.io/rb/caoutsearch.svg)](https://rubygems.org/gems/caoutsearch)
-[![CI Status](https://github.com/mon-territoire/caoutsearch/actions/workflows/ci.yml/badge.svg)](https://github.com/mon-territoire/caoutsearch/actions/workflows/ci.yml)
-[![Ruby Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/testdouble/standard)
-[![Maintainability](https://api.codeclimate.com/v1/badges/fbe73db3fd8be9a10e12/maintainability)](https://codeclimate.com/github/mon-territoire/caoutsearch/maintainability)
-[![Test Coverage](https://api.codeclimate.com/v1/badges/fbe73db3fd8be9a10e12/test_coverage)](https://codeclimate.com/github/mon-territoire/caoutsearch/test_coverage)
+<span>[![Gem Version](https://badge.fury.io/rb/caoutsearch.svg)](https://rubygems.org/gems/caoutsearch)</span> <span>
+[![CI Status](https://github.com/mon-territoire/caoutsearch/actions/workflows/ci.yml/badge.svg)](https://github.com/mon-territoire/caoutsearch/actions/workflows/ci.yml)</span> <span>
+[![Ruby Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/testdouble/standard)</span> <span>
+[![Maintainability](https://api.codeclimate.com/v1/badges/fbe73db3fd8be9a10e12/maintainability)](https://codeclimate.com/github/mon-territoire/caoutsearch/maintainability)</span> <span>
+[![Test Coverage](https://api.codeclimate.com/v1/badges/fbe73db3fd8be9a10e12/test_coverage)](https://codeclimate.com/github/mon-territoire/caoutsearch/test_coverage)</span>
 
-[![JRuby](https://github.com/mon-territoire/caoutsearch/actions/workflows/jruby.yml/badge.svg)](https://github.com/mon-territoire/caoutsearch/actions/workflows/jruby.yml)
-[![Truffle Ruby](https://github.com/mon-territoire/caoutsearch/actions/workflows/truffle_ruby.yml/badge.svg)](https://github.com/mon-territoire/caoutsearch/actions/workflows/truffle_ruby.yml)
+<span>[![JRuby](https://github.com/mon-territoire/caoutsearch/actions/workflows/jruby.yml/badge.svg)](https://github.com/mon-territoire/caoutsearch/actions/workflows/jruby.yml)</span> <span>
+[![Truffle Ruby](https://github.com/mon-territoire/caoutsearch/actions/workflows/truffle_ruby.yml/badge.svg)](https://github.com/mon-territoire/caoutsearch/actions/workflows/truffle_ruby.yml)</span>
 
 **!! Gem under development before public release !!**
 
@@ -17,177 +17,42 @@ It provides a simple but powerful DSL to perform complex indexing and searching,
 Caoutsearch only supports Elasticsearch 8.x right now.  
 It is used in production in a robust application, updated and maintained for several years at [Mon Territoire](https://mon-territoire.fr).
 
-Caoutsearch was inspired by awesome gems such as [elasticsearch-rails](https://github.com/elastic/elasticsearch-rails) or [search_flip](https://github.com/mrkamel/search_flip). 
-If you don't have scenarios as complex as those described in this documentation, they should better suite your needs.
-
-## Table of Contents
-
-- [Installation](#installation)
-- [Configuration](#configuration)
-  - Instrumentation
-- [Usage](#usage)
-  - [Indice Configuration](#indice-configuration)
-    - Mapping & settings
-    - Text analysis
-    - Versionning
-  - [Index Engine](#index-engine)
-    - Properties
-    - Partial updates
-    - Eager loading
-    - Interdependencies
-  - [Search Engine](#search-engine)
-    - Queries
-    - [Filters](#filters)
-    - Full-text query
-    - Custom filters
-    - Orders
-    - [Aggregations](#aggregations)
-    - [Transform aggregations](#transform-aggregations)
-    - [Responses](#responses)
-    - [Loading records](#loading-records)
-  - [Model integration](#model-integration)
-    - [Add Caoutsearch to your models](#add-caoutsearch-to-your-models)
-    - [Index records](#index-records)
-      - [Index multiple records](#index-multiple-records)
-      - [Index single records](#index-single-records)
-      - [Delete documents](#delete-documents)
-      - [Automatic Callbacks](#automatic-callbacks)
-      - Asynchronous methods
-    - [Search for records](#search-for-records)
-      - [Search API](#search-api)
-      - [Pagination](#pagination)
-      - [Total count](#total-count)
-      - [Iterating results](#iterating-results)
-  - [Testing with Caoutsearch](#testing-with-Caoutsearch)
+Caoutsearch was inspired by awesome gems such as [elasticsearch-rails](https://github.com/elastic/elasticsearch-rails) or [search_flip](https://github.com/mrkamel/search_flip).  
+Depending on your search scenarios, they may better suite your needs.
 
 ## Installation
 
+Add the gem in your Gemfile:
+
 ```bash
 bundle add caoutsearch
 ```
 
-## Configuration
-
-TODO
-
-## Usage
-
-### Indice Configuration
-
-TODO
-
-### Index Engine
-
-TODO
+## Overview
 
-### Search Engine
+Caoutsearch let you create `Index` and `Search` classes to manipulate your data :
 
-#### Filters
-Filters declared in the search engine will define how Caoutsearch will build the queries 
-
-The main use of filters is to expose a field for search, but they can also be used to build more complex queries:
 ```ruby
-class ArticleSearch < Caoutsearch::Search::Base
-  # Build a filter on the author field
-  filter :author
+class ArticleIndex < Caoutsearch::Index::Base
+  property :title
+  property :published_on
+  property :tags
 
-  # Build a Match filter on multiple fields
-  filter :content,      indexes: %i[title.words content], as: :match
-  
-  # Build a more complex filter by using other filters
-  filter :public,       as: :boolean
-  filter :published_on, as: :date
-  filter :active do |value|
-    search_by(published: value, published_on: value)
+  def tags
+    records.tags.public.map(&:to_s)
   end
 end
-```
-
-Caoutsearch different types of filters to handle different types of data or ways to search them:
 
-##### Default filter
-
-##### Boolean filter
+ArticleIndex.reindex(:tags)
+```
 
-##### Date filter
 
-For a date filter defined like this:
 ```ruby
 class ArticleSearch < Caoutsearch::Search::Base
-  ...
-
+  filter :title, as: :match
   filter :published_on, as: :date
-end
-```
-
-You can now search the matching index with the `published_on` criterion:
-```ruby
-Article.search(published_on: Date.today)
-```
-
-and the following query will be generated to send to elasticsearch:
-```json
-{
-  "query": { 
-    "bool": { 
-      "filter": [ 
-        { "range": { "published_on": { "gte": "2022-23-11", "lte": "2022-23-11"}}}
-      ]
-    }
-  }
-}
-```
-
-The date filter accepts multiple types of arguments :
+  filter :tags
 
-```ruby
-# Search for articles published on a date:
-Article.search(published_on: Date.today)
-
-# Search for articles published before a date:
-Article.search(published_on: { less_than: "2022-12-25" })
-Article.search(published_on: { less_than_or_equal: "2022-12-25" })
-Article.search(published_on: ..Date.new(2022, 12, 25))
-Article.search(published_on: [[nil, "now-2w/d"]])
-
-# Search for articles published after a date:
-Article.search(published_on: { greater_than: "2022-12-25" })
-Article.search(published_on: { greater_than_or_equal: "2022-12-25" })
-Article.search(published_on: Date.new(2022, 12, 25)..)
-Article.search(published_on: [["now-1w/d", nil]])
-
-# Search for articles published between two dates:
-Article.search(published_on: { greater_than: "2022-12-25", less_than: "2023-12-25" })
-Article.search(published_on: Date.new(2022, 12, 25)..Date.new(2023, 12, 25))
-Article.search(published_on: [["now-1w/d", "now/d"]])
-```
-
-Dates of various formats are handled:
-```ruby
-"2022-10-11"
-Date.today
-Time.zone.now
-```
-
-We also support elasticsearch's date math
-```ruby
-"now-1h"
-"now+2w/d"
-```
-
-##### GeoPoint filter
-
-##### Match filter
-
-##### Range filter
-
-#### Aggregations
-
-You can define simple to complex aggregations.
-
-````ruby
-class ArticleSearch < Caoutsearch::Search::Base
-  has_aggregation :view_count, { sum: { field: :view_count } }
   has_aggregation :popular_tags, {
     filter: { term: { published: true } },
     aggs: {
@@ -197,637 +62,14 @@ class ArticleSearch < Caoutsearch::Search::Base
     }
   }
 end
-````
-
-Then you can request one or more aggregations at the same time or chain the `aggregate` method.  
-The `aggregations` method will trigger a request and returns a [Response::Aggregations](#responses).
-
-````ruby
-ArticleSearch.aggregate(:view_count).aggregations
-# ArticleSearch Search { "body": { "aggs": { "view_count": { "sum": { "field": "view_count" }}}}}
-# ArticleSearch Search (10ms / took 5ms)
-=> #<Caoutsearch::Response::Aggregations view_count=#<Caoutsearch::Response::Response value=119652>>
-
-ArticleSearch.aggregate(:view_count, :popular_tags).aggregations
-# ArticleSearch Search { "body": { "aggs": { "view_count": {…}, "popular_tags": {…}}}}
-# ArticleSearch Search (10ms / took 5ms)
-=> #<Caoutsearch::Response::Aggregations view_count=#<Caoutsearch::Response::Response value=119652> popular_tags=#<Caoutsearch::Response::Response buckets=…>>
-
-ArticleSearch.aggregate(:view_count).aggregate(:popular_tags).aggregations
-# ArticleSearch Search { "body": { "aggs": { "view_count": {…}, "popular_tags": {…}}}}
-# ArticleSearch Search (10ms / took 5ms)
-=> #<Caoutsearch::Response::Aggregations view_count=#<Caoutsearch::Response::Response value=119652> popular_tags=#<Caoutsearch::Response::Response buckets=…>>
-````
-
-You can create powerful aggregations using blocks and pass arguments to them.
-
-````ruby
-class ArticleSearch < Caoutsearch::Search::Base
-  has_aggregation :popular_tags_since do |date|
-    raise TypeError unless date.is_a?(Date)
-
-    query.aggregations[:popular_tags_since] = {
-      filter: { range: { publication_date: { gte: date.to_s } } },
-      aggs: {
-        published: {
-          terms: { field: :tags, size: 20 }
-        }
-      }
-    }
-  end
-end
-
-ArticleSearch.aggregate(popular_tags_since: 1.day.ago).aggregations
-# ArticleSearch Search { "body": { "aggs": { "popular_tags_since": {…}}}}
-# ArticleSearch Search (10ms / took 5ms)
-=> #<Caoutsearch::Response::Aggregations popular_tags_since=#<Caoutsearch::Response::Response …
-````
-
-Only one argument can be passed to an aggregation block.  
-Use an Array or a Hash if you need to pass multiple options.
-
-````ruby
-class ArticleSearch < Caoutsearch::Search::Base
-  has_aggregation :popular_tags_since do |options|
-    # …
-  end
-
-  has_aggregation :popular_tags_between do |(first_date, end_date)|
-    # …
-  end
-end
-
-ArticleSearch.aggregate(popular_tags_since: { date: 1.day.ago, size: 20 })
-ArticleSearch.aggregate(popular_tags_between: [date1, date2])
-````
-
-Finally, you can create a "catch-all" aggregation to handle cumbersome behaviors:
-
-````ruby
-class ArticleSearch < Caoutsearch::Search::Base
-  has_aggregation do |name, options = {}|
-    raise "unxpected_error" unless name.match?(/^view_count_(?<year>\d{4})$/)
-
-    query.aggregations[name] = {
-      filter: { term: { year: $LAST_LATCH_INFO[:year] } },
-      aggs: {
-        filtered: {
-          sum: { field: :view_count }
-        }
-      }
-    }
-  end
-end
-
-ArticleSearch.aggregate(:view_count_2020, :view_count_2019).aggregations
-# ArticleSearch Search { "body": { "aggs": { "view_count_2020": {…}, "view_count_2019": {…}}}}
-# ArticleSearch Search (10ms / took 5ms)
-=> #<Caoutsearch::Response::Aggregations view_count_2020=#<Caoutsearch::Response::Response …
-````
-
-#### Transform aggregations
-
-When using [buckets aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket.html) and/or [pipeline aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-pipeline.html), the path to the expected values can get complicated and become subject to unexpected changes for a public API.
-
-````ruby
-ArticleSearch.aggregate(popular_tags_since: 1.month.ago).aggregations.popular_tags_since.published.buckets.pluck(:key)
-=> ["Blog", "Tech", …]
-````
-
-Instead, you can define transformations to provide simpler access to aggregated data:
-
-````ruby
-class ArticleSearch < Caoutsearch::Search::Base
-  has_aggregation :popular_tags_since do |since|
-    # …
-  end
-
-  transform_aggregation :popular_tags_since do |aggs|
-    aggs.dig(:popular_tags_since, :published, :buckets).pluck(:key)
-  end
-end
-
-ArticleSearch.aggregate(popular_tags_since: 1.month.ago).aggregations.popular_tags_since
-=> ["Blog", "Tech", …]
-````
-
-You can also use transformations to combine multiple aggregations:
-
-````ruby
-class ArticleSearch < Caoutsearch::Search::Base
-  has_aggregation :blog_count,     { filter: { term: { category: "blog" } } }
-  has_aggregation :archives_count, { filter: { term: { archived: true } } }
-
-  transform_aggregation :stats, from: %i[blog_count archives_count] do |aggs|
-    {
-      blog_count:     aggs.dig(:blog_count, :doc_count),
-      archives_count: aggs.dig(:archives, :doc_count)
-    }
-  end
-end
-
-ArticleSearch.aggregate(:stats).aggregations.stats
-# ArticleSearch Search { "body": { "aggs": { "blog_count": {…}, "archives_count": {…}}}}
-# ArticleSearch Search (10ms / took 5ms)
-=> { blog_count: 124, archives_count: 2452 }
-````
-
-This is also usefull to unify the API between different search engines:
-
-````ruby
-class ArticleSearch < Caoutsearch::Search::Base
-  has_aggregation :popular_tags, {
-    filter: { term: { published: true } },
-    aggs: { published: { terms: { field: :tags, size: 10 } } }
-  }
-
-  transform_aggregation :popular_tags do |aggs|
-    aggs.dig(:popular_tags, :published, :buckets).pluck(:key)
-  end
-end
-
-class TagSearch < Caoutsearch::Search::Base
-  has_aggregation :popular_tags, {
-    terms: { field: "label", size: 20, order: { used_count: "desc" } }
-  }
-
-  transform_aggregation :popular_tags do |aggs|
-    aggs.dig(:popular_tags, :buckets).pluck(:key)
-  end
-end
-
-ArticleSearch.aggregate(:popular_tags).aggregations.popular_tags
-=> ["Blog", "Tech", …]
-
-TagSearch.aggregate(:popular_tags).aggregations.popular_tags
-=> ["Tech", "Blog", …]
-````
-
-Transformations are performed on demand and result is memorized. That means:
-- the result of transformation is not visible in the [Response::Aggregations](#responses) output.
-- the block is called only once for the same search instance.
-
-````ruby
-class ArticleSearch < Caoutsearch::Search::Base
-  has_aggregation :popular_tags, {…}
-
-  transform_aggregation :popular_tags do |aggs|
-    tags       = aggs.dig(:popular_tags, :published, :buckets).pluck(:key)
-    authorized = Tag.where(title: tags, authorize: true).pluck(:title)
-    tags & authorized
-  end
-end
-
-article_search = ArticleSearch.aggregate(:popular_tags)
-=> #<ArticleSearch current_aggregations: [:popular_tags]>
-
-article_search.aggregations
-# ArticleSearch Search (10ms / took 5ms)
-=> #<Caoutsearch::Response::Aggregations popular_tags=#<Caoutsearch::Response::Response doc_count=100 …
-
-article_search.aggregations.popular_tags
-# (10.2ms)  SELECT "tags"."title" FROM "tags" WHERE "tags"."title" IN …
-=> ["Blog", "Tech", …]
-
-article_search.aggregations.popular_tags
-=> ["Blog", "Tech", …]
-
-article_search.search("Tech").aggregations.popular_tags
-# ArticleSearch Search (10ms / took 5ms)
-# (10.2ms)  SELECT "tags"."title" FROM "tags" WHERE "tags"."title" IN …
-=> ["Blog", "Tech", …]
-````
-
-Be careful to avoid using `aggregations.<aggregation_name>` inside a transformation block: it can lead to an infinite recursion.
-
-````ruby
-class ArticleSearch < Caoutsearch::Search::Base
-  transform_aggregation :popular_tags do
-    aggregations.popular_tags.buckets.pluck("key")
-  end
-end
-
-ArticleSearch.aggregate(:popular_tags).aggregations.popular_tags
-Traceback (most recent call last):
-      4: from app/searches/article_search.rb:3:in `block in <class:ArticleSearch>'
-      3: from app/searches/article_search.rb:3:in `block in <class:ArticleSearch>'
-      2: from app/searches/article_search.rb:3:in `block in <class:ArticleSearch>'
-      1: from app/searches/article_search.rb:3:in `block in <class:ArticleSearch>'
-SystemStackError (stack level too deep)
-````
-
-Instead, use the argument passed to the block: it's is a shortcut for `response.aggregations` which is a [Response::Reponse](#responses) and not a [Response::Aggregations](#responses).
-
-````ruby
-class ArticleSearch < Caoutsearch::Search::Base
-  transform_aggregation :popular_tags do |aggs|
-    aggs.popular_tags.buckets.pluck("key")
-  end
-end
-
-ArticleSearch.aggregate(:popular_tags).aggregations.popular_tags
-=> ["Blog", "Tech", …]
-````
-
-One last helpful argument is `track_total_hits` which allows to perform calculations over aggregations using the `total_count` method without sending a second request.  
-Take a look at [Total count](#total-count) to understand why a second request could be performed.
-
-````ruby
-class ArticleSearch < Caoutsearch::Search::Base
-  aggregation :tagged, filter: { exist: "tag" }
 
-  transform_aggregation :tagged_rate, from: :tagged, track_total_hits: true do |aggs|
-    count = aggs.dig(:tagged, :doc_count)
-    count.to_f / total_count
-  end
-
-  transform_aggregation :tagged_rate_without_track_total_hits, from: :tagged do |aggs|
-    count = aggs.dig(:tagged, :doc_count)
-    count.to_f / total_count
-  end
-end
-
-ArticleSearch.aggregate(:tagged_rate).aggregations.tagged_rate
-# ArticleSearch Search { "body": { "track_total_hits": true, "aggs": { "blog_count": {…}, "archives_count": {…}}}}
-# ArticleSearch Search (10ms / took 5ms)
-=> 0.95
-
-ArticleSearch.aggregate(:tagged_rate_without_track_total_hits).aggregations.tagged_rate
-# ArticleSearch Search { "body": { "aggs": { "blog_count": {…}, "archives_count": {…}}}}
-# ArticleSearch Search (10ms / took 5ms)
-# ArticleSearch Search { "body": { "track_total_hits": true, "aggs": { "blog_count": {…}, "archives_count": 
-# ArticleSearch Search (10ms / took 5ms)
-=> 0.95
-````
-
-#### Responses
-
-After the request has been sent by calling a method such as `load`, `response` or `hits`, the results is wrapped in a `Response::Response` class which provides method access to its properties via [Hashie::Mash](http://github.com/intridea/hashie).
-
-Aggregations and suggestions are wrapped in their own respective subclass of `Response::Response`
-
-````ruby
-results.response
-=> #<Caoutsearch::Response::Response _shards=#<Caoutsearch::Response::Response failed=0 skipped=0 successful=5 total=5> hits=…
-
-search.hits
-=> #<Hashie::Array [#<Caoutsearch::Response::Response _id="2"…
-
-search.aggregations
-=> #<Caoutsearch::Response::Aggregations view_count=#<Caoutsearch::Response::Response…
-
-search.suggestions
-=> #<Caoutsearch::Response::Suggestions tags=#<Caoutsearch::Response::Response…
-````
-
-##### Loading records
-
-When calling `records`, the search engine will try to load records from a model using the same class name without `Search` the suffix:  
-* `ArticleSearch` > `Article`
-* `Blog::ArticleSearch` > `Blog::Article`
-
-````ruby
-ArticleSearch.new.records.first
-# ArticleSearch Search (10ms / took 5ms)
-# Article Load (9.6ms)  SELECT "articles".* FROM "articles" WHERE "articles"."id" IN (1, …
-=> #<Article id: 1, …>
-````
-
-However, you can define an alternative model to load records. This might be helpful when using [single table inheritance](https://api.rubyonrails.org/classes/ActiveRecord/Inheritance.html).
-
-````ruby
-ArticleSearch.new.records(use: BlogArticle).first
-# ArticleSearch Search (10ms / took 5ms)
-# BlogArticle Load (9.6ms)  SELECT "articles".* FROM "articles" WHERE "articles"."id" IN (1, …
-=> #<BlogArticle id: 1, …>
-````
-
-You can also define an alternative model at class level:
-
-````ruby
-class BlogArticleSearch < Caoutsearch::Search::Base
-  self.model_name = "Article"
-
-  default do
-    query.filters << { term: { category: "blog" } }
-  end
-end
-
-BlogArticleSearch.new.records.first
-# BlogArticleSearch Search (10ms / took 5ms)
-# Article Load (9.6ms)  SELECT "articles".* FROM "articles" WHERE "articles"."id" IN (1, …
-=> #<Article id: 1, …>
-````
-
-### Model integration
-
-#### Add Caoutsearch to your models
-
-The simplest solution is to add `Caoutsearch::Model` to your model and the link the appropriate `Index` and/or `Search` engines:
-
-```ruby
-class Article < ActiveRecord::Base
-  include Caoutsearch::Model
-
-  index_with ArticleIndex
-  search_with ArticleSearch
-end
-```
-
-If you don't need your models to be `Indexable` and `Searchable`, you can include only one of the following two modules:
-
-````ruby
-class Article < ActiveRecord::Base
-  include Caoutsearch::Model::Indexable
-
-  index_with ArticleIndex
-end
-````
-or
-````ruby
-class Article < ActiveRecord::Base
-  include Caoutsearch::Model::Searchable
-
-  search_with ArticleSearch
-end
-````
-
-The modules can be safely included in the meta model `ApplicationRecord`.
-Indexing & searching features are not available until you call `index_with` or `search_with`:
-
-````ruby
-class ApplicationRecord < ActiveRecord::Base
-  include Caoutsearch::Model
-end
-````
-
-#### Index records
-
-##### Index multiple records
-
-Import all your records or a restricted scope of records to Elastcisearch.
-
-````ruby
-Article.reindex
-Article.where(published: true).reindex
-````
-
-You can update one or more properties. (see [Indexation Engines](#indexation-engines) to read more about properties):
-
-````ruby
-Article.reindex(:category)
-Article.reindex(%i[category published_on])
-````
-
-When `reindex` is called without properties, it'll import the full document to ES.  
-On the contrary, when properties are passed, it'll only update existing documents.  
-You can control this behavior with the `method` argument.
-
-````ruby
-Article.where(id: 123).reindex(:category)
-# ArticleIndex Reindex {"index":"articles","body":[{"update":{"_id":123}},{"doc":{"category":"blog"}}]}
-# [Error] {"update"=>{"_index"=>"articles", "_id"=>"123", "status"=>404, "error"=>{"type"=>"document_missing_exception", …}}
-
-Article.where(id: 123).reindex(:category, method: :index)
-# ArticleIndex Reindex {"index":"articles","body":[{"index":{"_id":123}},{"category":"blog"}]}
-
-Article.where(id: 123).reindex(method: :update)
-# ArticleIndex Reindex {"index":"articles","body":[{"update":{"_id":123}},{"doc":{…}}]}
-````
-
-##### Index single records
-
-Import a single record.
-
-````ruby
-Article.find(123).update_index
-````
-
-You can update one or more properties. (see [Indexation Engines](#indexation-engines) to read more about properties):
-
-````ruby
-Article.find(123).update_index(:category)
-Article.find(123).update_index(%i[category published_on])
-````
-
-You can verify if and how documents are indexed.  
-If the document is missing in ES, it'll raise a `Elastic::Transport::Transport::Errors::NotFound`.
-
-````ruby
-Article.find(123).indexed_document
-# Traceback (most recent call last):
-#         1: from (irb):1
-# Elastic::Transport::Transport::Errors::NotFound ([404] {"_index":"articles","_id":"123","found":false})
-
-Article.find(123).update_index
-Article.find(123).indexed_document
-=> {"_index"=>"articles", "_id"=>"123", "_version"=>1"found"=>true, "_source"=>{…}}
-````
-
-##### Delete documents
-
-You can delete one or more documents.  
-**Note**: it won't delete records from database, only from the ES indice.
-
-````ruby
-Article.delete_indexes
-Article.where(id: 123).delete_indexed_documents
-Article.find(123).delete_index
-````
-
-If a record is already deleted from the database, you can still delete its document.
-
-````ruby
-Article.delete_index(123)
-````
-
-##### Automatic Callbacks
-
-Callbacks are not provided by Caoutsearch but they are very easy to add:
-
-````ruby
-class Article < ApplicationRecord
-  index_with ArticleIndex
-  
-  after_commit :update_index, on: %i[create update]
-  after_commit :delete_index, on: %i[destroy]
-end
-````
-
-##### Asynchronous methods
-
-TODO
-
-#### Search for records
-
-##### Search API
-Searching is pretty simple.
-
-````ruby
-Article.search("Quick brown fox")
-=> #<ArticleSearch current_criteria: ["Quick brown fox"]>
-````
-
-You can chain criteria and many other parameters:
-````ruby
-Article.search("Quick brown fox").search(published: true)
-=> #<ArticleSearch current_criteria: ["Quick brown fox", {"published"=>true}]>
-
-Article.search("Quick brown fox").order(:publication_date)
-=> #<ArticleSearch current_criteria: ["Quick brown fox"], current_order: :publication_date>
-
-Article.search("Quick brown fox").limit(100).offset(100)
-=> #<ArticleSearch current_criteria: ["Quick brown fox"], current_limit: 100, current_offset: 100>
-
-Article.search("Quick brown fox").page(1).per(100)
-=> #<ArticleSearch current_criteria: ["Quick brown fox"], current_page: 1, current_limit: 100>
-
-Article.search("Quick brown fox").aggregate(:tags).aggregate(:dates)
-=> #<ArticleSearch current_criteria: ["Quick brown fox"], current_aggregations: [:tags, :dates]>>
-````
-
-##### Pagination
-
-Search results can be paginated.
-````ruby
-search = Article.search("Quick brown fox").page(1).per(100)
-search.current_page
-=> 1
-
-search.total_pages
-=> 2546
-
-> search.total_count
-=> 254514
-````
-
-##### Total count
-
-By default [ES doesn't return the total number of hits](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-your-data.html#track-total-hits). So, when calling `total_count` or `total_pages` a second request might be sent to ES.  
-To avoid a second roundtrip, use `track_total_hits`:
-
-````ruby 
-search = Article.search("Quick brown fox")
-search.hits
-# ArticleSearch Search {…}
-# ArticleSearch Search (81.8ms / took 16ms)
-=> […]
-
-search.total_count
-# ArticleSearch Search {…, track_total_hits: true }
-# ArticleSearch Search (135.3ms / took 76ms)
-=> 276
-
-search = Article.search("Quick brown fox").track_total_hits
-search.hits
-# ArticleSearch Search {…, track_total_hits: true }
-# ArticleSearch Search (120.2ms / took 56ms)
-=> […]
-
-search.total_count
-=> 276
-````
-
-##### Iterating results
-
-Several methods are provided to loop through a collection or hits or records.  
-These methods are processing batches in the most efficient way: [PIT search_after](https://www.elastic.co/guide/en/elasticsearch/reference/current/paginate-search-results.html#search-after).
-
-* `find_each_hit` to yield each hit returned by Elasticsearch.
-* `find_each_record` to yield each record from your database.
-* `find_hits_in_batches` to yield each batch of hits as returned by Elasticsearch.
-* `find_records_in_batches` to yield each batch of records from the database.
-
-Example:
-
-```ruby
-Article.search(published: true).find_each_record do |record|
-  record.inspect
-end
-```
-
-The `keep_alive` parameter tells Elasticsearch how long it should keep the point in time alive. Defaults to 1 minute.
-
-```ruby
-Article.search(published: true).find_each_record(keep_alive: "2h")
-```
-
-To specifies the size of the batch, use `per` chainable method or `batch_size` parameter. Defaults to 1000.
-
-```ruby
-Article.search(published: true).find_records_in_batches(batch_size: 500)
-Article.search(published: true).per(500).find_records_in_batches
-```
-
-## Testing with Caoutsearch
-
-Caoutsearch offers few methods to stub Elasticsearch requests.  
-You first need to add [webmock](https://github.com/bblimke/webmock) to your Gemfile.
-
-```bash
-bundle add webmock
-```
-
-Then, add `Caoutsearch::Testing::MockRequests` to your test suite.  
-The examples below uses RSpec, but it should be compatible with other test framework.
-
-```ruby
-# spec/spec_helper.rb
-
-require "caoutsearch/testing"
-
-RSpec.configure do |config|
-  config.include Caoutsearch::Testing::MockRequests
-end
-```
-
-You can then call the following methods:
-
-```ruby
-RSpec.describe SomeClass do
-  before do
-    stub_elasticsearch_request(:head, "articles").to_return(status: 200)
-
-    stub_elasticsearch_request(:get, "_cat/indices?format=json&h=index").to_return_json, [
-      { index: "ca_locals_v14" }
-    ])
-
-    stub_elasticsearch_reindex_request("articles")
-    stub_elasticsearch_search_request("articles", [
-      {"_id" => "135", "_source" => {"name" => "Hello World"}},
-      {"_id" => "137", "_source" => {"name" => "Hello World"}}
-    ])
-  end
-
-  # ... do your tests...
-end
+ArticleSearch.search(published_on: [["now-1y", nil]]).aggregate(:popular_tags)
 ```
 
-`stub_elasticsearch_search_request` accepts an array or records:
 
-```ruby
-RSpec.describe SomeClass do
-  let(:articles) { create_list(:article, 5) }
-
-  before do
-    stub_elasticsearch_search_request("articles", articles)
-  end
+## Documentation
 
-  # ... do your tests...
-end
-```
-
-It allows to shim the total number of hits returned.
-
-```ruby
-RSpec.describe SomeClass do
-  before do
-    stub_elasticsearch_search_request("articles", [], total: 250)
-  end
-
-  # ... do your tests...
-end
-```
+Visit our [offical documentation](https://mon-territoire.github.io/caoutsearch) to understand how to use Caoutsearch.
 
 ## Contributing
 

data/lib/caoutsearch/search/inspect.rb

@@ -5,7 +5,7 @@ module Caoutsearch
     module Inspect
       PROPERTIES_TO_INSPECT = %i[
         search_criteria
-        current_context
+        current_contexts
         current_order
         current_page
         current_limit

data/lib/caoutsearch/search/internal_dsl.rb

@@ -15,13 +15,13 @@ module Caoutsearch
         #   self.config[:filter][key] = ...
         #
         class_attribute :config, default: {
-          contexts: ActiveSupport::HashWithIndifferentAccess.new,
           filters: ActiveSupport::HashWithIndifferentAccess.new,
           defaults: ActiveSupport::HashWithIndifferentAccess.new,
           suggestions: ActiveSupport::HashWithIndifferentAccess.new,
           sorts: ActiveSupport::HashWithIndifferentAccess.new
         }
 
+        class_attribute :contexts, instance_accessor: false, default: {}
         class_attribute :aggregations, instance_accessor: false, default: {}
         class_attribute :transformations, instance_accessor: false, default: {}
       end
@@ -32,7 +32,7 @@ module Caoutsearch
           config[:match_all] = block
         end
 
-        %w[context default].each do |method|
+        %w[default].each do |method|
           config_attribute = method.pluralize.to_sym
 
           define_method method do |name = nil, &block|
@@ -68,6 +68,11 @@ module Caoutsearch
           sort(new_name) { |direction| sort_by(old_name, direction) }
         end
 
+        def has_context(name, &block)
+          self.contexts = contexts.dup
+          contexts[name.to_s] = Caoutsearch::Search::DSL::Item.new(name, &block)
+        end
+
         def has_aggregation(name, definition = {}, &block)
           raise ArgumentError, "has_aggregation accepts Hash definition or block but not both" if block && definition.any?
 

data/lib/caoutsearch/search/query_builder/contexts.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Caoutsearch
+  module Search
+    module QueryBuilder
+      module Contexts
+        private
+
+        def build_contexts
+          call_contexts(*current_contexts) if current_contexts
+        end
+
+        def call_contexts(*args)
+          args.each do |arg|
+            call_context(arg)
+          end
+        end
+
+        def call_context(name)
+          name = name.to_s
+
+          if self.class.contexts.include?(name)
+            item = self.class.contexts[name]
+            call_context_item(item)
+          end
+        end
+
+        def call_context_item(item)
+          instance_exec(&item.block)
+        end
+      end
+    end
+  end
+end

data/lib/caoutsearch/search/query_builder.rb

@@ -5,6 +5,7 @@ module Caoutsearch
     module QueryBuilder
       extend ActiveSupport::Concern
       include QueryBuilder::Aggregations
+      include QueryBuilder::Contexts
 
       def build
         reset_variable(:@elasticsearch_query)
@@ -13,7 +14,7 @@ module Caoutsearch
         run_callbacks :build do
           build_prepend_hash
           build_search_criteria
-          build_context
+          build_contexts
           build_defaults
           build_limits
           build_orders
@@ -35,13 +36,6 @@ module Caoutsearch
         search_by(search_criteria)
       end
 
-      def build_context
-        return unless current_context
-
-        item = config[:contexts][current_context.to_s]
-        instance_exec(&item.block) if item
-      end
-
       def build_defaults
         keys = search_criteria_keys.map(&:to_s)
 

data/lib/caoutsearch/search/search_methods.rb

@@ -5,7 +5,7 @@ module Caoutsearch
     module SearchMethods
       extend ActiveSupport::Concern
 
-      attr_reader :current_context, :current_order, :current_aggregations,
+      attr_reader :current_contexts, :current_order, :current_aggregations,
         :current_suggestions, :current_fields, :current_source
 
       # Public API
@@ -97,8 +97,9 @@ module Caoutsearch
         self
       end
 
-      def context!(value)
-        @current_context = value
+      def context!(*values)
+        @current_contexts ||= []
+        @current_contexts += values.flatten
         self
       end
 
@@ -173,7 +174,7 @@ module Caoutsearch
         "aggregations"    => :@current_aggregations,
         "suggest"         => :@current_suggestions,
         "suggestions"     => :@current_suggestions,
-        "context"         => :@current_context,
+        "context"         => :@current_contexts,
         "order"           => :@current_order,
         "page"            => :@current_page,
         "offset"          => :@current_offset,
@@ -189,7 +190,7 @@ module Caoutsearch
         self
       end
 
-      # Getters
+      # Getters and predicates
       # ------------------------------------------------------------------------
       def search_criteria
         @search_criteria ||= []
@@ -213,6 +214,10 @@ module Caoutsearch
         end
       end
 
+      def current_context?(name)
+        @current_contexts&.map(&:to_s)&.include?(name.to_s)
+      end
+
       # Criteria handlers
       # ------------------------------------------------------------------------
       def find_criterion(key)

data/lib/caoutsearch/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Caoutsearch
-  VERSION = "0.0.5"
+  VERSION = "0.0.6"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: caoutsearch
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.6
 platform: ruby
 authors:
 - Savater Sebastien
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-01-30 00:00:00.000000000 Z
+date: 2023-03-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -147,6 +147,7 @@ files:
 - lib/caoutsearch/search/query/setters.rb
 - lib/caoutsearch/search/query_builder.rb
 - lib/caoutsearch/search/query_builder/aggregations.rb
+- lib/caoutsearch/search/query_builder/contexts.rb
 - lib/caoutsearch/search/query_methods.rb
 - lib/caoutsearch/search/records.rb
 - lib/caoutsearch/search/resettable.rb
@@ -179,7 +180,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
+rubygems_version: 3.4.8
 signing_key:
 specification_version: 4
 summary: An alternative approach to index & search with Elasticsearch & Ruby on Rails