elasticsearch_record 1.6.0 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b29c6db7894f8365eb5a5922633a4adf53a793006c3ffa2fb381dd9ae171b124
-  data.tar.gz: 72c7f4260b76be5743e061838df5051006c82a883172d29f2e0442b6215ac4ed
+  metadata.gz: 92676fe7f2327036588c1d2e3cb6756cabbc2365ee8984196f1ef1c4a23d8448
+  data.tar.gz: 8c1f329957f4a1909181dde9e9c781a86a41188ee7337a73614eb8d893cae482
 SHA512:
-  metadata.gz: 7e09f30a077c81524c800a5694947d947da7a0a9273a4304592221d2c191c8a8582fbd94e65990ddf21cdbb23d74d5e7d4e47e53e14139c362fda91468aae182
-  data.tar.gz: bb03f9c4fa2749ccd23be70de65a1480b2d0a7cfa89ef51f9a3c3c2cd7e0810708e9e1e8050d7de033bfc670d5a127c75349f1f1380578246107395746e41652
+  metadata.gz: 9cb4514641f1f26d922f5cb941a677c5cff568641ddcf7243a914481707a982440b6a8967e74734d7900c00c6441128ef69c29a5c3774455df018206932e1b85
+  data.tar.gz: 004b62c74a4b4878c2e0a982a91217beee695a8e58d4509bba4cbd8f7664fdd0a4658cfd8533e1ff5a409f5fee6bce613d46f398ac067ed474324d65ad43406c

data/.yardopts

@@ -1,6 +1,6 @@
 --embed-mixins
 --markup=markdown
---files docs/*.*
+--files docs/*
 --plugin relative_markdown_links
 --plugin activesupport-concern
 --exclude lib/elasticsearch_record/patches

data/README.md

@@ -4,7 +4,7 @@
 [![Documentation](https://img.shields.io/badge/docs-rdoc.info-blue.svg)](http://rubydoc.info/gems/elasticsearch_record)
 
 [![Gem Version](https://badge.fury.io/rb/elasticsearch_record.svg)](https://badge.fury.io/rb/elasticsearch_record)
-[![License](https://img.shields.io/github/license/ruby-smart/elasticsearch_record)](docs/LICENSE.txt)
+[![License](https://img.shields.io/github/license/ruby-smart/elasticsearch_record)](docs/LICENSE)
 
 ActiveRecord adapter for Elasticsearch
 
@@ -14,8 +14,28 @@ _ElasticsearchRecord is a ActiveRecord adapter and provides similar functionalit
 
 **PLEASE NOTE:**
 
-- Specs & documentation are still missing, but will follow.
-- Currently supports ActiveRecord ~> 7.0 + Elasticsearch >= 7.17
+- This is the `rails-7-0-stable`-branch, which only supports rails **7.0** _(see section 'Rails_Versions' for supported versions)_
+- supports ActiveRecord ~> 7.0 + Elasticsearch >= 7.17
+
+-----
+
+## Rails versions
+
+Supported rails versions:
+
+### Rails 7.1:
+_(since gem version 1.8)_
+
+https://github.com/ruby-smart/elasticsearch_record/tree/rails-7-1-stable
+
+[![rails-7-1-stable](https://img.shields.io/badge/rails-7.1.stable-orange.svg)](https://github.com/ruby-smart/elasticsearch_record/tree/rails-7-1-stable)
+
+### Rails 7.0:
+_(until gem version 1.7)_
+
+https://github.com/ruby-smart/elasticsearch_record/tree/rails-7-0-stable
+
+[![rails-7-0-stable](https://img.shields.io/badge/rails-7.0.stable-orange.svg)](https://github.com/ruby-smart/elasticsearch_record/tree/rails-7-0-stable)
 
 -----
 
@@ -24,7 +44,11 @@ _ElasticsearchRecord is a ActiveRecord adapter and provides similar functionalit
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'elasticsearch_record'
+gem 'elasticsearch_record', '~> 1.7'
+
+# alternative
+gem 'elasticsearch_record', git: 'https://github.com/ruby-smart/elasticsearch_record', branch: 'rails-7-0-stable'
+
 ```
 
 And then execute:
@@ -235,6 +259,19 @@ total = scope.total
 # > 3335
 ```
 
+### Available core query methods
+
+- find_by_sql
+- find_by_query
+- find_by_esql
+- esql
+- msearch
+- search
+
+_see simple documentation about these methods @ {ElasticsearchRecord::Querying rubydoc}_
+
+_(also see @ [github](https://github.com/ruby-smart/elasticsearch_record/blob/main/lib/elasticsearch_record/querying.rb) )_
+
 ### Available query/relation chain methods
 - kind 
 - configure
@@ -252,7 +289,9 @@ total = scope.total
 - aggs_only!
 - total_only!
 
-_see simple documentation about these methods @ [rubydoc](https://rubydoc.info/gems/elasticsearch_record/ElasticsearchRecord/Relation/QueryMethods)_
+_see simple documentation about these methods @ {ElasticsearchRecord::Relation::QueryMethods rubydoc}_
+
+_(also see @ [github](https://github.com/ruby-smart/elasticsearch_record/blob/main/lib/elasticsearch_record/relation/query_methods.rb) )_
 
 ### Available calculation methods
 - percentiles
@@ -262,9 +301,16 @@ _see simple documentation about these methods @ [rubydoc](https://rubydoc.info/g
 - minimum
 - maximum
 - sum
+- boxplot
+- stats
+- string_stats
+- matrix_stats
+- median_absolute_deviation
 - calculate
 
-_see simple documentation about these methods @ [rubydoc](https://rubydoc.info/gems/elasticsearch_record/ElasticsearchRecord/Relation/CalculationMethods)_
+_see simple documentation about these methods @ {ElasticsearchRecord::Relation::CalculationMethods rubydoc}_
+
+_(also see @ [github](https://github.com/ruby-smart/elasticsearch_record/blob/main/lib/elasticsearch_record/relation/calculation_methods.rb) )_
 
 ### Available result methods
 - aggregations
@@ -279,7 +325,9 @@ _see simple documentation about these methods @ [rubydoc](https://rubydoc.info/g
 - pit_results
 - pit_delete
 
-_see simple documentation about these methods @ [rubydoc](https://rubydoc.info/gems/elasticsearch_record/ElasticsearchRecord/Relation/ResultMethods)_
+_see simple documentation about these methods @ {ElasticsearchRecord::Relation::ResultMethods rubydoc}_
+
+_(also see @ [github](https://github.com/ruby-smart/elasticsearch_record/blob/main/lib/elasticsearch_record/relation/result_methods.rb) )_
 
 ### Additional methods 
 - to_query
@@ -620,7 +668,7 @@ This project is intended to be a safe, welcoming space for collaboration, and co
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
-A copy of the [LICENSE](docs/LICENSE.txt) can be found @ the docs.
+A copy of the [LICENSE](docs/LICENSE) can be found @ the docs.
 
 ## Code of Conduct
 

data/docs/CHANGELOG.md

@@ -1,5 +1,15 @@
 # ElasticsearchRecord - CHANGELOG
 
+## [1.7.0] - 2024-01-09
+* [add] `ElasticsearchRecord::Relation#boxplot` calculation method
+* [add] `ElasticsearchRecord::Relation#stats` calculation method
+* [add] `ElasticsearchRecord::Relation#string_stats` calculation method
+* [add] `ElasticsearchRecord::Relation#matrix_stats` calculation method
+* [add] `ElasticsearchRecord::Relation#median_absolute_deviation` calculation method
+* [add] `ElasticsearchRecord::Base#esql` + `ElasticsearchRecord::Base#find_by_esql` to support `ES|QL` queries
+* [add] new repository branch `rails-7-0-stable` to support different rails versions
+* [ref] minor code optimizations & documentation changes
+
 ## [1.6.0] - 2023-08-11
 * [add] `ElasticsearchRecord::Base#undelegate_id_attribute_with` method to support a temporary 'undelegation' (used to create a new record)
 * [add] `ElasticsearchRecord::Relation#timeout` to directly provide the timeout-parameter to the query

data/docs/{LICENSE.txt → LICENSE}

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2022 Ruby Smart
+Copyright (c) 2024 Ruby Smart
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/lib/elasticsearch_record/gem_version.rb

@@ -8,7 +8,7 @@ module ElasticsearchRecord
 
   module VERSION
     MAJOR = 1
-    MINOR = 6
+    MINOR = 7
     TINY  = 0
     PRE   = nil
 

data/lib/elasticsearch_record/query.rb

@@ -12,6 +12,7 @@ module ElasticsearchRecord
     TYPE_SEARCH  = :search
     TYPE_MSEARCH = :msearch
     TYPE_SQL     = :sql
+    TYPE_ESQL    = :esql
 
     # -- DOCUMENT TYPES ------------------------------------------------------------------------------------------------
     TYPE_CREATE          = :create
@@ -34,7 +35,7 @@ module ElasticsearchRecord
     # includes valid types only
     TYPES = [
       # -- QUERY TYPES
-      TYPE_COUNT, TYPE_SEARCH, TYPE_MSEARCH, TYPE_SQL,
+      TYPE_COUNT, TYPE_SEARCH, TYPE_MSEARCH, TYPE_SQL, TYPE_ESQL,
       # -- DOCUMENT TYPES
       TYPE_CREATE, TYPE_UPDATE, TYPE_UPDATE_BY_QUERY, TYPE_DELETE, TYPE_DELETE_BY_QUERY,
 
@@ -46,7 +47,7 @@ module ElasticsearchRecord
 
     # includes reading types only
     READ_TYPES = [
-      TYPE_COUNT, TYPE_SEARCH, TYPE_MSEARCH, TYPE_SQL
+      TYPE_COUNT, TYPE_SEARCH, TYPE_MSEARCH, TYPE_SQL, TYPE_ESQL
     ].freeze
 
     # defines a body to be executed if the query fails - +(none)+
@@ -60,6 +61,7 @@ module ElasticsearchRecord
     # if no special type is defined, it simply uses +[:core,self.type]+
     GATES = {
       TYPE_SQL                  => [:sql, :query],
+      TYPE_ESQL                 => [:esql, :query],
       TYPE_INDEX_CREATE         => [:indices, :create],
       TYPE_INDEX_CLONE          => [:indices, :clone],
       TYPE_INDEX_UPDATE_MAPPING => [:indices, :put_mapping],
@@ -118,6 +120,12 @@ module ElasticsearchRecord
       self
     end
 
+    # returns true, if the query failed
+    # @return [Boolean]
+    def failed?
+      self.status == STATUS_FAILED
+    end
+
     # returns true, if the query is valid (e.g. index & type defined)
     # @return [Boolean]
     def valid?
@@ -143,7 +151,7 @@ module ElasticsearchRecord
     # failed queried will return the related +FAILED_BODIES+ or +{}+ as fallback
     # @return [Hash, nil]
     def body
-      return (FAILED_BODIES[self.type].presence || {}) if self.status == STATUS_FAILED
+      return (FAILED_BODIES[self.type].presence || {}) if failed?
 
       @body
     end

data/lib/elasticsearch_record/querying.rb

@@ -77,7 +77,42 @@ module ElasticsearchRecord
         _load_from_sql(_query_by_sql(query), &block)
       end
 
-      # executes a msearch by provided +RAW+ queries
+      # ES|QL query API
+      # Returns search results for an ES|QL (Elasticsearch query language) query.
+      #
+      # @param [String] esql
+      # @param [Proc] block
+      def find_by_esql(esql, &block)
+        # build new query
+        query = ElasticsearchRecord::Query.new(
+          type: ElasticsearchRecord::Query::TYPE_ESQL,
+          body: { query: esql },
+          # IMPORTANT: Always provide all columns
+          columns: source_column_names)
+
+        _load_from_sql(_query_by_sql(query), &block)
+      end
+
+      # executes a +esql+ by provided *ES|SL* query
+      # Does NOT instantiate records.
+      # @param [String] esql
+      # @param [Boolean] async (default: false)
+      def esql(esql, async: false)
+        # build new query
+        query = ElasticsearchRecord::Query.new(
+          type: ElasticsearchRecord::Query::TYPE_ESQL,
+          body: { query: esql },
+          # IMPORTANT: Always provide all columns
+          columns: source_column_names)
+
+        connection.exec_query(query, "#{name} ES|QL", async: async)
+      end
+
+
+      # executes a +msearch+ by provided *RAW* queries.
+      # Does NOT instantiate records.
+      # @param [Array<String>] queries
+      # @param [Boolean] async (default: false)
       def msearch(queries, async: false)
         # build new msearch query
         query = ElasticsearchRecord::Query.new(

data/lib/elasticsearch_record/relation/calculation_methods.rb

@@ -45,6 +45,84 @@ module ElasticsearchRecord
         end
       end
 
+      # A boxplot metrics aggregation that computes boxplot of numeric values extracted from the aggregated documents.
+      # These values can be generated from specific numeric or histogram fields in the documents.
+      #
+      # The boxplot aggregation returns essential information for making a box plot:
+      # *minimum*, *maximum*, *median*, *first quartile* (25th percentile) and *third quartile* (75th percentile) values.
+      #
+      #   Person.all.boxplot(:age)
+      #   > {
+      #       "min": 0.0,
+      #       "max": 990.0,
+      #       "q1": 167.5,
+      #       "q2": 445.0,
+      #       "q3": 722.5,
+      #       "lower": 0.0,
+      #       "upper": 990.0
+      #     }
+      #
+      # @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-boxplot-aggregation.html
+      #
+      # @param [Symbol, String] column_name
+      def boxplot(column_name)
+        calculate(:boxplot, column_name)
+      end
+
+      # A multi-value metrics aggregation that computes stats over numeric values extracted from the aggregated documents.      #
+      # The stats that are returned consist of: *min*, *max*, *sum*, *count* and *avg*.
+      #
+      #   Person.all.stats(:age)
+      #   > {
+      #       "count": 10,
+      #       "min": 0.0,
+      #       "max": 990.0,
+      #       "sum": 16859,
+      #       "avg": 75.5
+      #     }
+      #
+      # @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-stats-aggregation.html
+      #
+      # @param [Symbol, String] column_name
+      def stats(column_name)
+        calculate(:stats, column_name)
+      end
+
+      # A multi-value metrics aggregation that computes statistics over string values extracted from the aggregated documents.
+      # These values can be retrieved either from specific keyword fields.
+      #
+      #   Person.all.string_stats(:name)
+      #   > {
+      #       "count": 5,
+      #       "min_length": 24,
+      #       "max_length": 30,
+      #       "avg_length": 28.8,
+      #       "entropy": 3.94617750050791
+      #     }
+      #
+      # @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-string-stats-aggregation.html
+      #
+      # @param [Symbol, String] column_name
+      def string_stats(column_name)
+        calculate(:string_stats, column_name)
+      end
+
+      # The matrix_stats aggregation is a numeric aggregation that computes the following statistics over a set of document fields:
+      # *count*        Number of per field samples included in the calculation.
+      # *mean*        The average value for each field.
+      # *variance*    Per field Measurement for how spread out the samples are from the mean.
+      # *skewness*    Per field measurement quantifying the asymmetric distribution around the mean.
+      # *kurtosis*    Per field measurement quantifying the shape of the distribution.
+      # *covariance*  A matrix that quantitatively describes how changes in one field are associated with another.
+      # *correlation* The covariance matrix scaled to a range of -1 to 1, inclusive. Describes the relationship between field distributions.
+      #
+      # @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-matrix-stats-aggregation.html
+      #
+      # @param [Array<Symbol|String>] column_names
+      def matrix_stats(*column_names)
+        calculate(:matrix_stats, *column_names)
+      end
+
       # A multi-value metrics aggregation that calculates one or more
       # percentiles over numeric values extracted from the aggregated documents.
       # Returns a hash with empty values (but keys still exists) if there is no row.
@@ -59,6 +137,9 @@ module ElasticsearchRecord
       #     "95.0" => 2021.0,
       #     "99.0" => 2022.0
       #     }
+      #
+      # @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-percentile-aggregation.html
+      #
       # @param [Symbol, String] column_name
       def percentiles(column_name)
         calculate(:percentiles, column_name, node: :values)
@@ -81,6 +162,9 @@ module ElasticsearchRecord
       #     "95.0" => 2021.0,
       #     "99.0" => 2022.0
       #     }
+      #
+      # @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-percentile-rank-aggregation.html
+      #
       # @param [Symbol, String] column_name
       # @param [Array] values
       def percentile_ranks(column_name, values)
@@ -92,6 +176,8 @@ module ElasticsearchRecord
       #   Person.all.cardinality(:age)
       #   > 12
       #
+      # @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-cardinality-aggregation.html
+      #
       # @param [Symbol, String] column_name
       def cardinality(column_name)
         calculate(:cardinality, column_name)
@@ -101,6 +187,8 @@ module ElasticsearchRecord
       #
       #   Person.all.average(:age) # => 35.8
       #
+      # @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-avg-aggregation.html
+      #
       # @param [Symbol, String] column_name
       def average(column_name)
         calculate(:avg, column_name)
@@ -112,6 +200,8 @@ module ElasticsearchRecord
       #   Person.all.minimum(:age)
       #   > 7
       #
+      # @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-min-aggregation.html
+      #
       # @param [Symbol, String] column_name
       def minimum(column_name)
         calculate(:min, column_name)
@@ -123,33 +213,58 @@ module ElasticsearchRecord
       #
       #   Person.all.maximum(:age) # => 93
       #
+      # @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-max-aggregation.html
+      #
       # @param [Symbol, String] column_name
       def maximum(column_name)
         calculate(:max, column_name)
       end
 
+      # This single-value aggregation approximates the median absolute deviation of its search results.
+      # Median absolute deviation is a measure of variability. It is a robust statistic,
+      # meaning that it is useful for describing data that may have outliers, or may not be normally distributed.
+      # For such data it can be more descriptive than standard deviation.
+      #
+      # It is calculated as the median of each data point’s deviation from the median of the entire sample.
+      # That is, for a random variable X, the median absolute deviation is median(|median(X) - Xi|).
+      #
+      #   Person.all.median_absolute_deviation(:age) # => 91
+      #
+      # @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-median-absolute-deviation-aggregation.html
+      #
+      # @param [Symbol, String] column_name
+      def median_absolute_deviation(column_name)
+        calculate(:median_absolute_deviation, column_name)
+      end
+
       # Calculates the sum of values on a given column. The value is returned
       # with the same data type of the column, +0+ if there's no row. See
       # #calculate for examples with options.
       #
       #   Person.all.sum(:age) # => 4562
       #
+      # @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-sum-aggregation.html
+      #
       # @param [Symbol, String] column_name (optional)
       def sum(column_name)
         calculate(:sum, column_name)
       end
 
-      # creates a aggregation with the provided metric (e.g. :sum) and column.
+      # creates a aggregation with the provided metric (e.g. :sum) and columns.
       # returns the metric node (default: :value) from the aggregations result.
       # @param [Symbol, String] metric
-      # @param [Symbol, String] column
+      # @param [Array<Symbol|String>] columns
       # @param [Hash] opts - additional arguments that get merged with the metric definition
       # @param [Symbol] node (default :value)
-      def calculate(metric, column, opts: {}, node: :value)
-        metric_key = "#{column}_#{metric}"
+      def calculate(metric, *columns, opts: {}, node: :value)
+        metric_key = "calculate_#{metric}"
 
         # spawn a new aggregation and return the aggs
-        response = aggregate(metric_key, { metric => { field: column }.merge(opts) }).aggregations
+        response = if columns.size == 1
+                     aggregate(metric_key, { metric => { field: columns[0] }.merge(opts) }).aggregations
+                   else
+                     aggregate(metric_key, { metric => { fields: columns }.merge(opts) }).aggregations
+                   end
 
         response[metric_key][node]
       end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: elasticsearch_record
 version: !ruby/object:Gem::Version
-  version: 1.6.0
+  version: 1.7.0
 platform: ruby
 authors:
 - Tobias Gonsior
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-08-11 00:00:00.000000000 Z
+date: 2024-01-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -125,7 +125,7 @@ files:
 - Rakefile
 - docs/CHANGELOG.md
 - docs/CODE_OF_CONDUCT.md
-- docs/LICENSE.txt
+- docs/LICENSE
 - elasticsearch_record.gemspec
 - lib/active_record/connection_adapters/elasticsearch/column.rb
 - lib/active_record/connection_adapters/elasticsearch/database_statements.rb