es_tractor 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8c7ccbb02ef8a6f0bb4b970cc28f963c55952a2e
+  data.tar.gz: ce0bd10580ac1d4adc9d4ff0c48acf21e5bfaa0c
+SHA512:
+  metadata.gz: 198ab52863d622b2fcbb9e8a9d752a72e8abe00f6846aebebd56680e7bebb707dcedc7b49629205cae656fdd8951279b115afe4a6ccdadc25b4b2e897a36b25b
+  data.tar.gz: b8e4d5d4925becc313fa08cf8eb3ebb3f42710b168ba47845646739998a6b3ac854bc2dc7f8419f99a292909e5c2a504e6a3567b2c316436dbfa4ecf51a2b7d9

data/.autotest

@@ -0,0 +1,25 @@
+# -*- ruby -*-
+
+require "autotest/restart"
+
+# Autotest.add_hook :initialize do |at|
+#   at.testlib = "minitest/unit"
+#
+#   at.extra_files << "../some/external/dependency.rb"
+#
+#   at.libs << ":../some/external"
+#
+#   at.add_exception "vendor"
+#
+#   at.add_mapping(/dependency.rb/) do |f, _|
+#     at.files_matching(/test_.*rb$/)
+#   end
+#
+#   %w(TestA TestB).each do |klass|
+#     at.extra_class_map[klass] = "test/test_misc.rb"
+#   end
+# end
+
+# Autotest.add_hook :run_command do |at|
+#   system "rake build"
+# end

data/.rubocop.yml

@@ -0,0 +1,17 @@
+Layout/EmptyLineAfterMagicComment:
+  Enabled: false
+
+AllCops:
+  TargetRubyVersion: '2.4.1'
+Metrics/AbcSize:
+  Max: 20
+Metrics/BlockLength:
+  Enabled: false
+Metrics/MethodLength:
+  Max: 20
+Style/TrailingCommaInArguments:
+  Enabled: false
+Style/TrailingCommaInLiteral:
+  Enabled: false
+Metrics/LineLength:
+  Max: 78

data/History.txt

@@ -0,0 +1,12 @@
+=== 0.0.1 / 2017-08-31
+
+* 1 major enhancement
+
+  * Birthday!
+
+=== 0.0.2 / 2017-09-04
+
+* 1 major enhancement
+
+  * Search, count, filter
+

data/Manifest.txt

@@ -0,0 +1,12 @@
+.autotest
+.rubocop.yml
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+bin/console
+lib/es_tractor.rb
+lib/es_tractor/client.rb
+test/helper.rb
+test/test_client.rb
+test/test_es_tractor.rb

data/README.txt

@@ -0,0 +1,76 @@
+# @markup markdown
+# EsTractor: Simplified data extracton from Elasticsearch
+
+[[Home]](https://github.com/utilum/es_tractor)
+
+## DESCRIPTION:
+
+Sub-set of Search APIs with DRY query building.
+
+## FEATURES/PROBLEMS:
+
+- Subset of Search APIs: count, search.
+- Minimal DRY query builder maps root elements of a Hash argument into boolean
+  filters.
+
+- TODO:
+  - Add Search APIs:
+      - Fields
+      - Sort
+      - Scroll
+  - Aggregations
+  - Report formats: CSV, JSON.
+  - Extraction: Aggregation to flat records (separate project?).
+
+## SYNOPSIS:
+
+```
+include EsTractor
+tractor = Client.new
+
+tractor.count
+  # => (Integer) number of documents on the server
+
+tractor.count(term: { my_field: 'my precise term' })
+  # => (Integer) number of documents where my_field == 'my precise term'
+```
+
+## REQUIREMENTS:
+
+Some environment variables are expected:
+- L2B_ELASTICSEARCH_HOST
+- L2B_ELASTICSEARCH_INDEX
+
+## DEVELOPERS:
+
+After checking out the source, run:
+
+  $ rake newb
+
+This task will install any missing dependencies, run the tests/specs,
+and generate the RDoc.
+
+## LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2017 FIX
+
+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/Rakefile

@@ -0,0 +1,38 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'rubygems'
+require 'hoe'
+
+Hoe.plugin :yard
+
+Hoe.spec 'es_tractor' do
+  developer('utilum', 'oz@utilum.com')
+
+  license 'MIT'
+
+  extra_deps << ['elasticsearch', '~> 5.0', '>= 5.0.4']
+
+  extra_dev_deps << ['hoe-yard', '~> 0.1', '>=0.1.3']
+  extra_dev_deps << ['minitest', '~> 5.10', '>=5.10.3']
+  extra_dev_deps << ['mocha', '~> 1.3', '>=1.3.0']
+  extra_dev_deps << ['pry', '~> 0.10.4']
+end
+
+namespace :es_tractor do
+  $LOAD_PATH.unshift File.expand_path('../lib', __FILE__)
+  require 'es_tractor'
+
+  include EsTractor
+
+  namespace :demo do
+    desc 'Count all docuements since forever'
+    task :count_all do
+      tractor = Client.new
+      r = tractor.count
+      puts "Found #{r} documents"
+    end
+  end
+end
+
+# vim: syntax=ruby

data/bin/console

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+require 'es_tractor'
+
+begin
+  require 'pry'
+  Pry.start
+rescue LoadError
+  require 'irb'
+  IRB.start
+end

data/lib/es_tractor.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+$LOAD_PATH.unshift File.dirname(__FILE__) + '/es_tractor'
+$LOAD_PATH.unshift File.dirname(__FILE__) \
+  unless $LOAD_PATH.include?(File.dirname(__FILE__))
+
+require 'client'
+
+##
+# EsTractor provides tools to query Elasticsearch
+
+module EsTractor
+  VERSION = '0.0.2'
+end

data/lib/es_tractor/client.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+require 'elasticsearch'
+
+module EsTractor
+  ##
+  # Client provides an Elasticsearch::Client with a limited subset of
+  # methods and simplified arguments.
+  class Client
+    # @example
+    #   'my_index'
+    ELASTICSEARCH_INDEX = ENV['ES_TRACTOR_ELASTICSEARCH_INDEX']
+
+    # @example
+    #   'example.com:9200'
+    ELASTICSEARCH_HOST = ENV['ES_TRACTOR_ELASTICSEARCH_HOST']
+
+    # @attr_reader [Elasticsearch::Client] client to search with.
+    attr_reader :client
+
+    # @param [true, false] log verbose output of client-server interactions
+    def initialize(log = false)
+      @client = Elasticsearch::Client.new(
+        host: ELASTICSEARCH_HOST,
+        log: log,
+      )
+    end
+
+    # Count documents, filtered by options.
+    # @return [Hash] with the result in the 'count' key.
+    # @param [Hash] opts with the following keys:
+    # @option opts [String, Array<String>] :exists
+    #   One or more field names, translated into filter boolean.
+    # @option opts [Hash, Array<Hash>] :match
+    #   One or more field: match pairs, translated into must boolean.
+    # @option opts [String] :query_string
+    #   Translated into must boolean.
+    # @option opts [Hash<Array>] :range
+    #   A hash keyed on a field name, containing an array: [min, max],
+    #   translated into filter boolean.
+    # @option opts [Hash, Array<Hash>] :term
+    #   One or more field: term pairs, translated into filter boolean.
+    #
+    # @example
+    #   opts = {
+    #     match: { color: 'strawberry black' },
+    #     exists: ['flavor', 'spicy'],
+    #     term: [
+    #       { flavor: 'vanilla' },
+    #       { spicy: 3 },
+    #     ],
+    #   }
+    #
+    #   Client.new.count(opts) # => { 'count' => 7 }
+    #
+    #   # Tranforms opts into the following hash, passed to Elasticsearch:
+    #     {
+    #       body:  {
+    #         query: {
+    #           bool: {
+    #             must: {
+    #               match: { flavor: 'vanilla' },
+    #             },
+    #             filter: [
+    #               { term: { flavor: 'vanilla' } },
+    #               { term: { spicy: 3 } },
+    #             ],
+    #           },
+    #         },
+    #       },
+    #     }
+    def count(opts = {})
+      args = { body: body(opts) }
+      @client.count(args)
+    end
+
+    # @return [Hash] with the actual result in the 'hits'['hits'] key.
+    # @param (see #count)
+    # @option (see #count)
+    # @option opts [Integer] :from
+    # @option opts [Integer] :size
+    def search(opts)
+      args = {
+        from: opts[:from] ? opts[:from] : 0,
+        size: opts[:size] ? opts[:size] : 0,
+        body: body(opts),
+      }
+      @client.search(args)
+    end
+
+    private
+
+    def array_or_hash(name, filter)
+      case filter
+      when Array
+        filter.map { |f| { name => f } }
+      when Hash
+        [name => filter]
+      else
+        []
+      end
+    end
+
+    def body(opts = {})
+      { query: query(opts) }
+    end
+
+    def query(opts = {})
+      bool = { filter: [], must: [] }
+
+      (%i[exists match query_string range term] & opts.keys)
+        .each do |qualifier|
+        case qualifier
+        when :exists
+          bool[:filter].push(exists: { field: opts[qualifier] })
+        when :match
+          bool[:must] += array_or_hash(qualifier, opts[:match])
+        when :query_string
+          bool[:must].push(query_string: { query: opts[:query_string] })
+        when :range
+          bool[:filter].push(range: range(opts[:range]))
+        when :term
+          bool[:filter] += array_or_hash(qualifier, opts[:term])
+        end
+      end
+
+      { bool: bool }
+    end
+
+    def range(range_opt)
+      {
+        range_opt.keys.first => {
+          gte: range_opt.values.first.first,
+          lte: range_opt.values.first.last,
+        },
+      }
+    end
+  end
+end

data/test/helper.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+ENV['ESTRACTOR_ENV'] = 'test'
+$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+
+require 'es_tractor'
+require 'minitest/autorun'
+require 'mocha/setup'
+
+class Test < Minitest::Test
+  include EsTractor
+end

data/test/test_client.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+require 'helper'
+
+module EsTractor
+  class TestClient < Test
+    def setup
+      @tractor = Client.new
+    end
+
+    %w[count search].each do |action|
+      exp = action == 'search' ? { from: 0, size: 0 } : {}
+
+      define_method "test_#{action}_with_term_hash" do
+        opts = { term: { my_field: 'my precise term' } }
+        exp[:body] = { query: { bool: {
+          must: [],
+          filter: [
+            term: { my_field: 'my precise term' }
+          ],
+        } } }
+
+        @tractor.client.expects(action).with(exp)
+
+        @tractor.send(action, opts)
+      end
+
+      define_method "test_#{action}_with_term_array" do
+        opts = { term: [
+          { my_field: 'my precise term' },
+          { my_other_field: 'my other term' },
+        ] }
+        exp[:body] = { query: { bool: {
+          must: [],
+          filter: [
+            { term: { my_field: 'my precise term' } },
+            { term: { my_other_field: 'my other term' } },
+          ],
+        } } }
+
+        @tractor.client.expects(action).with(exp)
+
+        @tractor.send(action, opts)
+      end
+
+      define_method "test_#{action}_with_match_hash" do
+        opts = { match: { my_field: 'my match' } }
+        exp[:body] = { query: { bool: {
+          must: [{ match: { my_field: 'my match' } }],
+          filter: [],
+        } } }
+
+        @tractor.client.expects(action).with(exp)
+
+        @tractor.send(action, opts)
+      end
+
+      define_method "test_#{action}_with_range_hash" do
+        min = 1
+        max = 2
+        opts = { range: { my_field: [min, max] } }
+        exp[:body] = { query: {
+          bool: {
+            must: [],
+            filter: [
+              range: {
+                my_field: {
+                  gte: min,
+                  lte: max,
+                },
+              },
+            ],
+          },
+        } }
+
+        @tractor.client.expects(action).with(exp)
+
+        @tractor.send(action, opts)
+      end
+
+      define_method "test_#{action}_with_exists_fieldname_value" do
+        opts = { exists: 'my_field' }
+        exp[:body] = { query: {
+          bool: {
+            must: [],
+            filter: [
+              { exists: { field: 'my_field' } },
+            ],
+          },
+        } }
+
+        @tractor.client.expects(action).with(exp)
+
+        @tractor.send(action, opts)
+      end
+
+      define_method "test_#{action}_with_exists_fieldname_array" do
+        opts = { exists: %w[my_field my_other_field] }
+        exp[:body] = { query: {
+          bool: {
+            must: [],
+            filter: [
+              {
+                exists: {
+                  field: %w[my_field my_other_field],
+                },
+              },
+            ],
+          },
+        } }
+
+        @tractor.client.expects(action).with(exp)
+
+        @tractor.send(action, opts)
+      end
+
+      define_method "test_#{action}_with_query_string" do
+        opts = { query_string: 'My query string' }
+        exp[:body] = { query: {
+          bool: {
+            must: [query_string: { query: 'My query string' }],
+            filter: [],
+          },
+        } }
+
+        @tractor.client.expects(action).with(exp)
+
+        @tractor.send(action, opts)
+      end
+    end
+  end
+end

data/test/test_es_tractor.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+require 'helper'
+
+class TestEsTractor < Test
+  def test_client
+    assert Elasticsearch::Transport::Client, Client.new
+  end
+end

metadata

@@ -0,0 +1,165 @@
+--- !ruby/object:Gem::Specification
+name: es_tractor
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+platform: ruby
+authors:
+- utilum
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-09-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: elasticsearch
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.0.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.0.4
+- !ruby/object:Gem::Dependency
+  name: hoe-yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.3
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.10'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.10.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.10'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.10.3
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.0
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.10.4
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.10.4
+- !ruby/object:Gem::Dependency
+  name: hoe
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.16'
+description: Sub-set of Search APIs with DRY query building.
+email:
+- oz@utilum.com
+executables:
+- console
+extensions: []
+extra_rdoc_files:
+- History.txt
+- Manifest.txt
+- README.txt
+files:
+- ".autotest"
+- ".rubocop.yml"
+- History.txt
+- Manifest.txt
+- README.txt
+- Rakefile
+- bin/console
+- lib/es_tractor.rb
+- lib/es_tractor/client.rb
+- test/helper.rb
+- test/test_client.rb
+- test/test_es_tractor.rb
+homepage: 
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options:
+- "--title"
+- TestEsTractor Documentation
+- "--quiet"
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.13
+signing_key: 
+specification_version: 4
+summary: Sub-set of Search APIs with DRY query building.
+test_files: []