module Esse::Backend::Index::InstanceMethods

Constants

DEFAULT_OPTIONS

Public Instance Methods

aliases(**options) click to toggle source

Return a list of index aliases.

@param options [Hash] Hash of paramenters that will be passed along to elasticsearch request @param options [Array] :index list of serialized documents to be indexed(Optional)

@see www.elastic.co/guide/en/elasticsearch/reference/7.5/indices-aliases.html

# File lib/esse/backend/index/aliases.rb, line 13
def aliases(**options)
  response = client.indices.get_alias({ index: index_name, name: '*' }.merge(options))
  idx_name = response.keys.find { |idx| idx.start_with?(index_name) }
  return [] unless idx_name

  response.dig(idx_name, 'aliases')&.keys || []
rescue Elasticsearch::Transport::Transport::Errors::NotFound
  []
end
close(suffix: index_version, **options) click to toggle source

Close an index (keep the data on disk, but deny operations with the index).

@option options [String, nil] :suffix The index suffix. Defaults to the index_version.

Use nil if you want to check existence of the `index_name` index or alias.

@option options [String] :expand_wildcards Whether to expand wildcard expression to concrete indices that

are open, closed or both. (options: open, closed)

@option options [String] :ignore_indices When performed on multiple indices, allows to ignore

`missing` ones (options: none, missing) @until 1.0

@option options [Boolean] :ignore_unavailable Whether specified concrete indices should be ignored when

unavailable (missing, closed, etc)

@option options [Time] :timeout Explicit operation timeout @return [Hash, false] the elasticsearch response, or false in case of failure

@see www.elastic.co/guide/en/elasticsearch/reference/master/indices-open-close.html

# File lib/esse/backend/index/close.rb, line 41
def close(suffix: index_version, **options)
  close!(suffix: suffix, **options)
rescue Elasticsearch::Transport::Transport::ServerError
  false
end
close!(suffix: index_version, **options) click to toggle source

Close an index (keep the data on disk, but deny operations with the index).

@option options [String, nil] :suffix The index suffix. Defaults to the index_version.

Use nil if you want to check existence of the `index_name` index or alias.

@option options [String] :expand_wildcards Whether to expand wildcard expression to concrete indices that

are open, closed or both. (options: open, closed)

@option options [String] :ignore_indices When performed on multiple indices, allows to ignore

`missing` ones (options: none, missing) @until 1.0

@option options [Boolean] :ignore_unavailable Whether specified concrete indices should be ignored when

unavailable (missing, closed, etc)

@option options [Time] :timeout Explicit operation timeout @raise [Elasticsearch::Transport::Transport::Errors::BadRequest, Elasticsearch::Transport::Transport::Errors::NotFound]

in case of failure

@return [Hash] the elasticsearch response

@see www.elastic.co/guide/en/elasticsearch/reference/master/indices-open-close.html

# File lib/esse/backend/index/close.rb, line 23
def close!(suffix: index_version, **options)
  client.indices.close(options.merge(index: index_name(suffix: suffix)))
end
create_index(suffix: nil, **options) click to toggle source

Creates index and applies mappings and settings.

UsersIndex.backend.create_index # creates index named `<prefix_>users_<suffix|index_version|timestamp>`

@param options [Hash] Options hash @option options [Boolean] :alias Update `index_name` alias along with the new index @option options [String] :suffix The index suffix. Defaults to the `IndexClass#index_version` or

`Esse.timestamp`. Suffixed index names might be used for zero-downtime mapping change.

@return [Hash, false] the elasticsearch response or false in case of unsuccessful creation.

@see www.elasticsearch.org/blog/changing-mapping-with-zero-downtime/

# File lib/esse/backend/index/create.rb, line 22
def create_index(suffix: nil, **options)
  create_index!(suffix: suffix, **options)
rescue Elasticsearch::Transport::Transport::Errors::BadRequest
  false
end
create_index!(suffix: nil, **options) click to toggle source

Creates index and applies mappings and settings.

UsersIndex.backend.create_index! # creates index named `<prefix_>users_<suffix|index_version|timestamp>`

@param options [Hash] Options hash @option options [Boolean] :alias Update `index_name` alias along with the new index @option options [String] :suffix The index suffix. Defaults to the `IndexClass#index_version` or

`Esse.timestamp`. Suffixed index names might be used for zero-downtime mapping change.

@raise [Elasticsearch::Transport::Transport::Errors::NotFound] when index already exists @return [Hash] the elasticsearch response

@see www.elasticsearch.org/blog/changing-mapping-with-zero-downtime/

# File lib/esse/backend/index/create.rb, line 40
def create_index!(suffix: nil, **options)
  options = DEFAULT_OPTIONS.merge(options)
  name = build_real_index_name(suffix)
  definition = [settings_hash, mappings_hash].reduce(&:merge)

  if options[:alias] && name != index_name
    definition[:aliases] = { index_name => {} }
  end

  client.indices.create(index: name, body: definition)
end
delete_index(suffix: index_version) click to toggle source

Deletes ES index

UsersIndex.backend.delete_index # deletes `<prefix_>users<_suffix|_index_version|_timestamp>` index

@param suffix [String, nil] The index suffix Use nil if you want to delete the current index. @return [Hash, false] elasticsearch response, of false in case of error.

# File lib/esse/backend/index/delete.rb, line 24
def delete_index(suffix: index_version)
  delete_index!(suffix: suffix)
rescue Elasticsearch::Transport::Transport::Errors::NotFound
  false
end
delete_index!(suffix:) click to toggle source

Deletes ES index

UsersIndex.backend.delete_index! # deletes `<prefix_>users<_suffix|_index_version|_timestamp>` index

@param suffix [String, nil] The index suffix Use nil if you want to delete the current index. @raise [Elasticsearch::Transport::Transport::Errors::NotFound] when index does not exists @return [Hash] elasticsearch response

# File lib/esse/backend/index/delete.rb, line 14
def delete_index!(suffix:)
  client.indices.delete(index: index_name(suffix: suffix))
end
exist?(suffix: index_version) click to toggle source

Checks the index existance. Returns true or false

UsersIndex.backend.exist? #=> true

@param options [Hash] Options hash @option options [String, nil] :suffix The index suffix. Defaults to the index_version.

Use nil if you want to check existence of the `index_name` index or alias.
# File lib/esse/backend/index/existance.rb, line 14
def exist?(suffix: index_version)
  client.indices.exists(index: index_name(suffix: suffix))
end
import(**options) click to toggle source
# File lib/esse/backend/index/documents.rb, line 13
def import(**options)
  type_hash.each_value do |type|
    type.backend.import(**options)
  end
end
import!(**options) click to toggle source
# File lib/esse/backend/index/documents.rb, line 7
def import!(**options)
  type_hash.each_value do |type|
    type.backend.import!(**options)
  end
end
indices(**options) click to toggle source

Returns a list of indices.

@param options [Hash] Hash of paramenters that will be passed along to elasticsearch request @return [Array] list of indices that match with `index_name`.

# File lib/esse/backend/index/aliases.rb, line 27
def indices(**options)
  client.indices.get_alias({ name: index_name }.merge(options)).keys
rescue Elasticsearch::Transport::Transport::Errors::NotFound
  []
end
open(suffix: index_version, **options) click to toggle source

Open a previously closed index

@option options [String, nil] :suffix The index suffix. Defaults to the index_version.

Use nil if you want to check existence of the `index_name` index or alias.

@option options [String] :expand_wildcards Whether to expand wildcard expression to concrete indices that

are open, closed or both. (options: open, closed)

@option options [String] :ignore_indices When performed on multiple indices, allows to ignore

`missing` ones (options: none, missing) @until 1.0

@option options [Boolean] :ignore_unavailable Whether specified concrete indices should be ignored when

unavailable (missing, closed, etc)

@option options [Time] :timeout Explicit operation timeout @return [Hash, false] the elasticsearch response, or false in case of failure

@see www.elastic.co/guide/en/elasticsearch/reference/master/indices-open-open.html

# File lib/esse/backend/index/open.rb, line 41
def open(suffix: index_version, **options)
  open!(suffix: suffix, **options)
rescue Elasticsearch::Transport::Transport::ServerError
  false
end
open!(suffix: index_version, **options) click to toggle source

Open a previously closed index

@option options [String, nil] :suffix The index suffix. Defaults to the index_version.

Use nil if you want to check existence of the `index_name` index or alias.

@option options [String] :expand_wildcards Whether to expand wildcard expression to concrete indices that

are open, closed or both. (options: open, closed)

@option options [String] :ignore_indices When performed on multiple indices, allows to ignore

`missing` ones (options: none, missing) @until 1.0

@option options [Boolean] :ignore_unavailable Whether specified concrete indices should be ignored when

unavailable (missing, closed, etc)

@option options [Time] :timeout Explicit operation timeout @raise [Elasticsearch::Transport::Transport::Errors::BadRequest, Elasticsearch::Transport::Transport::Errors::NotFound]

in case of failure

@return [Hash] the elasticsearch response

@see www.elastic.co/guide/en/elasticsearch/reference/master/indices-open-open.html

# File lib/esse/backend/index/open.rb, line 23
def open!(suffix: index_version, **options)
  client.indices.open(options.merge(index: index_name(suffix: suffix)))
end
refresh(suffix: index_version, **options) click to toggle source

Performs the refresh operation in one or more indices.

@note The refresh operation can adversely affect indexing throughput when used too frequently. @param :suffix [String, nil] :suffix The index suffix. Defaults to the index_version.

A uniq index name will be generated if one index already exist with the given alias.

@param options [Hash] Options hash @return [Hash, false] the elasticsearch response, or false in case of failure

@see www.elastic.co/guide/en/elasticsearch/reference/master/indices-refresh.html

# File lib/esse/backend/index/refresh.rb, line 33
def refresh(suffix: index_version, **options)
  refresh!(suffix: suffix, **options)
rescue Elasticsearch::Transport::Transport::ServerError
  false
end
refresh!(suffix: index_version, **options) click to toggle source

Performs the refresh operation in one or more indices.

@note The refresh operation can adversely affect indexing throughput when used too frequently. @param :suffix [String, nil] :suffix The index suffix. Defaults to the index_version.

A uniq index name will be generated if one index already exist with the given alias.

@param options [Hash] Options hash @raise [Elasticsearch::Transport::Transport::Errors::BadRequest, Elasticsearch::Transport::Transport::Errors::NotFound]

in case of failure

@return [Hash] the elasticsearch response

@see www.elastic.co/guide/en/elasticsearch/reference/master/indices-refresh.html

# File lib/esse/backend/index/refresh.rb, line 18
def refresh!(suffix: index_version, **options)
  client.indices.refresh(
    options.merge(index: index_name(suffix: suffix)),
  )
end
reset_index!(suffix: index_version, **options) click to toggle source

Deletes, creates and imports data to the index. Performs zero-downtime index resetting.

@option options [String, nil] :suffix The index suffix. Defaults to the index_version.

A uniq index name will be generated if one index already exist with the given alias.

@option options [Time] :timeout Explicit operation timeout @raise [Elasticsearch::Transport::Transport::Errors::BadRequest, Elasticsearch::Transport::Transport::Errors::NotFound]

in case of failure

@return [Hash] the elasticsearch response

@see www.elastic.co/guide/en/elasticsearch/reference/master/indices-open-close.html

# File lib/esse/backend/index/reset.rb, line 17
def reset_index!(suffix: index_version, **options)
  existing = []
  suffix ||= Esse.timestamp
  while exist?(suffix: suffix).tap { |exist| existing << suffix if exist }
    suffix = Esse.timestamp
  end

  create_index!(suffix: suffix, **options)
  import!(suffix: suffix, **options)
  update_aliases!(suffix: suffix)
  existing.each { |s| delete_index!(suffix: suffix, **options) }
  true
end
update_aliases(suffix:, **options) click to toggle source

Replaces all existing aliases by the respective suffixed index from argument.

@param options [Hash] Hash of paramenters that will be passed along to elasticsearch request @option [String] :suffix The suffix of the index used for versioning. @raise [Elasticsearch::Transport::Transport::Errors::NotFound] in case of failure @return [Hash, false] the elasticsearch response, or false in case of failure

# File lib/esse/backend/index/aliases.rb, line 59
def update_aliases(suffix:, **options)
  update_aliases!(suffix: suffix, **options)
rescue Elasticsearch::Transport::Transport::Errors::NotFound
  false
end
update_aliases!(suffix:, **options) click to toggle source

Replaces all existing aliases by the respective suffixed index from argument.

@param options [Hash] Hash of paramenters that will be passed along to elasticsearch request @option [String] :suffix The suffix of the index used for versioning. @raise [Elasticsearch::Transport::Transport::Errors::NotFound] in case of failure @return [Hash] the elasticsearch response

# File lib/esse/backend/index/aliases.rb, line 39
def update_aliases!(suffix:, **options)
  raise(ArgumentError, 'index suffix cannot be nil') if suffix.nil?

  options[:body] = {
    actions: [
      *indices.map do |index|
        { remove: { index: index, alias: index_name } }
      end,
      { add: {index: build_real_index_name(suffix), alias: index_name } }
    ],
  }
  client.indices.update_aliases(options)
end
update_mapping(suffix: index_version, **options) click to toggle source

Create or update a mapping

@option options [String] :type The name of the document type. This field is required for some elasticsearch versions @option options [Boolean] :ignore_conflicts Specify whether to ignore conflicts while updating the mapping

(default: false)

@option options [Boolean] :allow_no_indices Whether to ignore if a wildcard indices expression resolves into

no concrete indices. (This includes `_all` string or when no indices have been specified)

@option options [String] :expand_wildcards Whether to expand wildcard expression to concrete indices that

are open, closed or both. (options: open, closed)

@option options [String] :ignore_indices When performed on multiple indices, allows to ignore

`missing` ones (options: none, missing) @until 1.0

@option options [Boolean] :ignore_unavailable Whether specified concrete indices should be ignored when

unavailable (missing, closed, etc)

@option options [Boolean] :update_all_types Whether to update the mapping for all fields

with the same name across all types

@option options [Time] :timeout Explicit operation timeout @option options [Boolean] :master_timeout Timeout for connection to master @return [Hash, false] the elasticsearch response, or false in case of failure

@see www.elasticsearch.org/guide/reference/api/admin-indices-put-mapping/

# File lib/esse/backend/index/update.rb, line 53
def update_mapping(suffix: index_version, **options)
  update_mapping!(suffix: suffix, **options)
rescue Elasticsearch::Transport::Transport::ServerError
  false
end
update_mapping!(suffix: index_version, **options) click to toggle source

Create or update a mapping

@option options [String] :type The name of the document type. This field is required for some elasticsearch versions @option options [Boolean] :ignore_conflicts Specify whether to ignore conflicts while updating the mapping

(default: false)

@option options [Boolean] :allow_no_indices Whether to ignore if a wildcard indices expression resolves into

no concrete indices. (This includes `_all` string or when no indices have been specified)

@option options [String] :expand_wildcards Whether to expand wildcard expression to concrete indices that

are open, closed or both. (options: open, closed)

@option options [String] :ignore_indices When performed on multiple indices, allows to ignore

`missing` ones (options: none, missing) @until 1.0

@option options [Boolean] :ignore_unavailable Whether specified concrete indices should be ignored when

unavailable (missing, closed, etc)

@option options [Boolean] :update_all_types Whether to update the mapping for all fields

with the same name across all types

@option options [Time] :timeout Explicit operation timeout @option options [Boolean] :master_timeout Timeout for connection to master @raise [Elasticsearch::Transport::Transport::Errors::BadRequest, Elasticsearch::Transport::Transport::Errors::NotFound]

in case of failure

@return [Hash] the elasticsearch response

@see www.elasticsearch.org/guide/reference/api/admin-indices-put-mapping/

# File lib/esse/backend/index/update.rb, line 29
def update_mapping!(suffix: index_version, **options)
  client.indices.put_mapping(options.merge(index: index_name(suffix: suffix), body: mappings_hash.fetch(Esse::MAPPING_ROOT_KEY)))
end
update_settings(suffix: index_version, **options) click to toggle source

Closes the index for read/write operations, updates the index settings, and open it again

@option options [String] :expand_wildcards Whether to expand wildcard expression to concrete indices that

are open, closed or both. (options: open, closed)

@option options [String] :ignore_indices When performed on multiple indices, allows to ignore

`missing` ones (options: none, missing) @until 1.0

@option options [Boolean] :ignore_unavailable Whether specified concrete indices should be ignored when

unavailable (missing, closed, etc)

@option options [Boolean] :include_defaults Whether to return all default clusters setting @option options [Boolean] :preserve_existing Whether to update existing settings.

If set to `true` existing settings on an index remain unchanged, the default is `false`

@option options [Time] :master_timeout Specify timeout for connection to master @option options [Boolean] :flat_settings Return settings in flat format (default: false) @return [Hash, false] the elasticsearch response, false in case of failure

@see www.elasticsearch.org/guide/reference/api/admin-indices-update-settings/

# File lib/esse/backend/index/update.rb, line 108
def update_settings(suffix: index_version, **options)
  update_settings!(suffix: suffix, **options)
rescue Elasticsearch::Transport::Transport::ServerError
  false
end
update_settings!(suffix: index_version, **options) click to toggle source

Closes the index for read/write operations, updates the index settings, and open it again

@option options [String] :expand_wildcards Whether to expand wildcard expression to concrete indices that

are open, closed or both. (options: open, closed)

@option options [String] :ignore_indices When performed on multiple indices, allows to ignore

`missing` ones (options: none, missing) @until 1.0

@option options [Boolean] :ignore_unavailable Whether specified concrete indices should be ignored when

unavailable (missing, closed, etc)

@option options [Boolean] :include_defaults Whether to return all default clusters setting @option options [Boolean] :preserve_existing Whether to update existing settings.

If set to `true` existing settings on an index remain unchanged, the default is `false`

@option options [Time] :master_timeout Specify timeout for connection to master @option options [Boolean] :flat_settings Return settings in flat format (default: false) @raise [Elasticsearch::Transport::Transport::Errors::BadRequest, Elasticsearch::Transport::Transport::Errors::NotFound]

in case of failure

@return [Hash] the elasticsearch response

@see www.elasticsearch.org/guide/reference/api/admin-indices-update-settings/

# File lib/esse/backend/index/update.rb, line 78
def update_settings!(suffix: index_version, **options)
  response = nil

  close!(suffix: suffix)
  begin
    body = settings_hash(cluster_settings: false).fetch(Esse::SETTING_ROOT_KEY)
    response = client.indices.put_settings(options.merge(index: index_name(suffix: suffix), body: body))
  ensure
    open!(suffix: suffix)
  end

  response
end