amber_odm 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3fd8519f176d5e86f6ddb8307e77864de6511ee3af28e0f89873bb57a4ac51e7
+  data.tar.gz: 3684de6f1e2f52c1da8b04c55fb47b6e5e13da36fbe3eb843c0929cf5ab49dc6
+SHA512:
+  metadata.gz: e0fb595ffd51eb627493a777347636200c06713041802d65aa41968140bc0ed361e74e23a0c4d6b73cf8925d2994f4fddcdf52a1fb55541b56572d2912f53da9
+  data.tar.gz: 2f36be5406925f55a1f2329518891982da4263543526c1d01e244d853b30207a555be16201c685eeb8caa8a0e5b1faacb07b79ba094d70f77ee843edac0f98bc

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+.idea
+*.gem
+.ruby-version
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/Gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in emerald-orm.gemspec
+gemspec
+

data/Gemfile.lock

@@ -0,0 +1,86 @@
+PATH
+  remote: .
+  specs:
+    amber_odm (1.0.0)
+      elasticsearch
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    coderay (1.1.3)
+    diff-lcs (1.5.0)
+    docile (1.4.0)
+    dotenv (2.8.1)
+    elastic-transport (8.1.0)
+      faraday (< 3)
+      multi_json
+    elasticsearch (8.6.0)
+      elastic-transport (~> 8)
+      elasticsearch-api (= 8.6.0)
+    elasticsearch-api (8.6.0)
+      multi_json
+    faraday (1.10.3)
+      faraday-em_http (~> 1.0)
+      faraday-em_synchrony (~> 1.0)
+      faraday-excon (~> 1.1)
+      faraday-httpclient (~> 1.0)
+      faraday-multipart (~> 1.0)
+      faraday-net_http (~> 1.0)
+      faraday-net_http_persistent (~> 1.0)
+      faraday-patron (~> 1.0)
+      faraday-rack (~> 1.0)
+      faraday-retry (~> 1.0)
+      ruby2_keywords (>= 0.0.4)
+    faraday-em_http (1.0.0)
+    faraday-em_synchrony (1.0.0)
+    faraday-excon (1.1.0)
+    faraday-httpclient (1.0.1)
+    faraday-multipart (1.0.4)
+      multipart-post (~> 2)
+    faraday-net_http (1.0.1)
+    faraday-net_http_persistent (1.2.0)
+    faraday-patron (1.0.0)
+    faraday-rack (1.0.0)
+    faraday-retry (1.0.3)
+    method_source (1.0.0)
+    multi_json (1.15.0)
+    multipart-post (2.3.0)
+    pry (0.14.2)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    rake (13.0.6)
+    rspec (3.12.0)
+      rspec-core (~> 3.12.0)
+      rspec-expectations (~> 3.12.0)
+      rspec-mocks (~> 3.12.0)
+    rspec-core (3.12.0)
+      rspec-support (~> 3.12.0)
+    rspec-expectations (3.12.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-mocks (3.12.3)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-support (3.12.0)
+    ruby2_keywords (0.0.5)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.12.3)
+    simplecov_json_formatter (0.1.4)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  amber_odm!
+  bundler
+  dotenv
+  pry
+  rake
+  rspec
+  simplecov
+
+BUNDLED WITH
+   1.16.2

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 mikael
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,143 @@
+# AmberODM
+A Ruby gem that provides a simple Object Document Mapper (ODM) for Elasticsearch. It allows you to interact with Elasticsearch in a more organized and object-oriented way.
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'amber_odm'
+```
+
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install amber_odm 
+
+# Usage
+Here's a quick example of how to use EmeraldODM to interact with a ElasticSearch database:
+
+## 1. Configuring your Elasticsearch connection
+```ruby
+require 'amber_odm'
+
+AmberODM.databases_settings[:dev] = {
+  url: 'http://localhost:9200',
+  log: true
+}
+
+```
+
+## 2. Define your model
+```ruby
+require 'amber_odm'
+
+# Define a model for the "users" index
+class User < AmberODM::Document
+  
+  attr_accessor :name, :email, :posts, :keywords_count
+
+  def self.index_name
+    :users
+  end
+  
+  def self.db_name
+    :dev
+  end
+  
+  def self.posts=(posts)
+    @posts = posts.map { |post| Post.new(post)}
+  end
+  
+  class Post < AmberODM::AttrInitializer
+    attr_accessor :id, :title, :body, :created_at, :updated_at
+    
+    def created_at
+      Time.parse(@created_at)
+    end
+
+    def updated_at
+      Time.parse(@updated_at)
+    end
+    
+    def keywords
+      body.scan(/\w+/)
+    end
+  end
+  
+end
+
+```
+
+## 3. Use it
+```ruby
+# Find users using a query
+users = User.search(
+  {
+    bool: {
+      must: [
+        {match: {name: 'John Doe'}}
+      ]
+    }
+  }, # filter query is required
+  _source: %w[name email posts keywords_count], # optional, the default is to return all fields defined in the document
+  size: 10, # optional, the default is to return all documents
+)
+
+# users is an array of User objects like Array<User>
+bulk_users = []
+users.each do |user|
+  posts = user.posts
+  all_user_keywords = posts.map(&:keywords).flatten.uniq
+  user.keywords_count = all_user_keywords.count
+  bulk_hash = user.get_bulk_update_hash(:keywords_count) # returns a hash that can be used to update the document field ':keywords_count' in bulk
+
+  bulk_users << bulk_hash
+end
+
+# Update the documents in bulk
+User.client.bulk(body: bulk_users) unless bulk_users.empty?
+```
+
+# Advanced usage
+## Pagination
+```ruby
+# 1. Get the first page of users
+users = User.search(
+  { bool: { must: [{match: {name: 'John Doe'}}] } },
+  size: 10,
+  sort: [{name: 'asc'}],
+)
+
+# 2. Get the last sort value
+search_after = users.last&.sort
+
+# 3. Loop through the pages
+while users.any?
+  users = User.search(
+    { bool: { must: [{match: {name: 'John Doe'}}] } },
+    size: 10,
+    sort: [{name: 'asc'}],
+    search_after: search_after
+  )
+  
+  # 4. Do something with the users documents...
+  puts users.map(&:name).join(', ')
+  
+  # 5. Update the last sort value
+  search_after = users.last&.sort
+end
+```
+## Accessing the Elasticsearch client
+```ruby
+User.client # returns the Elasticsearch client from 'elasticsearch-ruby' gem
+```
+
+# Contributing
+Bug reports and pull requests are welcome on GitHub at https://github.com/MikaelSantilio/amber-odm/.
+
+# License
+The gem is available as open source under the terms of the MIT License.

data/amber_odm.gemspec

@@ -0,0 +1,41 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require_relative 'lib/amber_odm/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'amber_odm'
+  spec.version       = AmberODM::VERSION
+  spec.authors       = ['mikael']
+  spec.email         = ['mikael.santilio@gmail.com']
+
+  spec.summary       = 'ElasticSearch ODM'
+  spec.description   = 'Simple ElasticSearch ODM'
+  spec.homepage      = 'https://github.com/MikaelSantilio/amber-odm'
+  spec.required_ruby_version = Gem::Requirement.new('>= 2.5.0')
+
+  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/MikaelSantilio/amber-odm'
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'dotenv'
+  spec.add_development_dependency 'pry'
+  spec.add_development_dependency 'simplecov'
+
+  spec.add_dependency 'elasticsearch'
+
+end

data/lib/amber_odm/version.rb

@@ -0,0 +1,3 @@
+module AmberODM
+  VERSION = '1.0.0'
+end

data/lib/amber_odm.rb

@@ -0,0 +1,197 @@
+require 'amber_odm/version'
+require 'elasticsearch'
+
+module AmberODM
+
+  def self.databases_settings
+    @databases_settings ||= {}
+  end
+
+  module Connector
+
+    # @return [Elasticsearch::Client] The database client
+    def self.database(db_name)
+      if databases_instances[db_name].nil?
+        db_settings = AmberODM.databases_settings[db_name]
+        raise Exceptions::MissingDatabaseSettings.new("Database settings not found for #{db_name}") if db_settings.nil? || db_settings.empty?
+        self.databases_instances[db_name] = Elasticsearch::Client.new(db_settings)
+      end
+      databases_instances[db_name]
+    end
+
+    def self.databases_instances
+      @databases_instances ||= {}
+    end
+  end
+
+  class AttrInitializer
+    attr_reader :document
+
+    def initialize(document)
+      self.class.fields.each do |field|
+        document_value = document&.dig(field).dup
+        send("#{field}=", document_value) unless document_value.nil?
+      end
+      instance_variable_set('@document', document)
+    end
+
+    # @return [Array]
+    def self.fields
+      public_instance_methods = self.public_instance_methods(false).grep(/=$/)
+      rejected_attr_names = %w[document]
+      fields = []
+      public_instance_methods.each do |attr|
+        attr_name = attr.to_s.gsub('=', '')
+        next if rejected_attr_names.include?(attr_name)
+        fields << attr_name
+      end
+      fields
+    end
+
+    def nil?
+      document.nil? || document.empty?
+    end
+
+    def self.array_to_h(array)
+      array.map do |item|
+        if item.is_a?(AttrInitializer)
+          item.to_h
+        elsif item.is_a?(Array)
+          array_to_h(item)
+        else
+          item
+        end
+      end
+    end
+
+    def to_h
+      hash = {}
+      known_fields = self.class.fields
+      unknown_fields = document.keys - known_fields
+      unknown_fields.reject! { |field| field.start_with?('_') }
+      known_fields.each do |field|
+        value = send(field)
+        if value.is_a?(AttrInitializer)
+          hash[field] = value.to_h
+        elsif value.is_a?(Array)
+          hash[field] = self.class.array_to_h(value)
+        else
+          hash[field] = value
+        end
+      end
+      unknown_fields.each do |field|
+        value = document[field]
+        hash[field] = value
+      end
+
+      hash
+    end
+  end
+
+  class Document < AttrInitializer
+
+    attr_reader :_id, :_score, :sort
+
+    def initialize(document)
+      @_id = document&.dig('_id').dup
+      @_score = document&.dig('_score').dup
+      @sort = document&.dig('sort').dup
+      self.class.fields.each do |field|
+        document_value = document&.dig('_source')&.dig(field).dup
+        send("#{field}=", document_value) unless document_value.nil?
+      end
+      instance_variable_set('@document', document)
+    end
+
+    # @return [Symbol, nil]
+    def self.db_name
+      nil
+    end
+
+    # @return [Symbol, String, nil]
+    def self.index_name
+      nil
+    end
+
+    # @return [Elasticsearch::Client] The ES client
+    def self.client
+      Connector.database(db_name&.to_sym)
+    end
+
+    def self.is_valid_fields?(query_fields)
+      (query_fields - fields).count == 0
+    end
+
+    # @param [Hash] query The query
+    # @param [Array] _source The _source
+    # @param [Hash] sort The sort
+    # @param [Integer] size The size
+    # @return [Array<self>] The documents
+    def search(query, _source: [], sort: [], search_after: [], size: 0)
+      # self.class.validate_fields_from_stages(query, _source, sort)
+
+      if _source.empty?
+        _source = self.class.fields
+      end
+
+      if query.empty?
+        raise Exceptions::IllegalArgumentException.new
+      end
+
+      body = { _source: _source, query: query }
+      body[:sort] = sort unless sort.empty?
+      body[:search_after] = search_after unless search_after.empty?
+      body[:size] = size unless size.zero?
+      response = self.class.client.search(index: self.class.index_name.to_s, body: body)
+      response&.dig('hits', 'hits')&.map { |document| self.class.new(document) } || []
+    end
+
+    def self.search(filter, _source: [], sort: {}, search_after: [], size: 0)
+      new({}).search(filter, _source: _source, sort: sort, search_after: search_after, size: size)
+    end
+
+    def self.validate_fields(fields_to_validate)
+      fields_to_validate.map! { |field| field.to_s }
+      if (fields_to_validate - fields).count > 0
+        raise Exceptions::UnknownWriteFieldException.new "Unknown fields: #{fields_to_validate - fields}, define them in attr_accessor before using them"
+      elsif fields_to_validate.empty?
+        raise Exceptions::IllegalArgumentException.new 'Empty fields'
+      end
+    end
+
+    def get_bulk_update_hash(*fields)
+      self.class.validate_fields(fields)
+
+      aggregation_hash = {}
+      fields.each do |field|
+        value = send(field)
+        if value.is_a?(AttrInitializer)
+          aggregation_hash[field] = value.to_h
+        elsif value.is_a?(Array)
+          aggregation_hash[field] = AttrInitializer.array_to_h(value)
+        else
+          aggregation_hash[field] = value
+        end
+      end
+
+      {
+        update: {
+          _index: self.class.index_name&.to_s,
+          _id: _id,
+          data: { doc: aggregation_hash }
+        }
+      }
+    end
+
+  end
+
+  module Exceptions
+    class MissingDatabaseSettings < StandardError; end
+    class UnknownWriteFieldException < StandardError; end
+    class IllegalArgumentException < StandardError
+      def initialize(msg = 'query malformed, empty clause')
+        super
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,153 @@
+--- !ruby/object:Gem::Specification
+name: amber_odm
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- mikael
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2023-01-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: elasticsearch
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Simple ElasticSearch ODM
+email:
+- mikael.santilio@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- amber_odm.gemspec
+- lib/amber_odm.rb
+- lib/amber_odm/version.rb
+homepage: https://github.com/MikaelSantilio/amber-odm
+licenses: []
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/MikaelSantilio/amber-odm
+  source_code_uri: https://github.com/MikaelSantilio/amber-odm
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.7
+signing_key: 
+specification_version: 4
+summary: ElasticSearch ODM
+test_files: []