Class: Elastomer::Client::Docs

Inherits:
Object
  • Object
show all
Defined in:
lib/elastomer/client/docs.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client, name, type = nil) ⇒ Docs

Create a new document client for making API requests that pertain to the indexing and searching of documents in a search index.

client - Elastomer::Client used for HTTP requests to the server name - The name of the index as a String type - The document type as a String



24
25
26
27
28
 
# File 'lib/elastomer/client/docs.rb', line 24

def initialize( client, name, type = nil )
  @client = client
  @name   = @client.assert_param_presence(name, 'index name')
  @type   = @client.assert_param_presence(type, 'document type') unless type.nil?
end

Instance Attribute Details

#client ⇒ Object (readonly)

Returns the value of attribute client.



30
31
32
 
# File 'lib/elastomer/client/docs.rb', line 30

def client
  @client
end

#name ⇒ Object (readonly)

Returns the value of attribute name.



30
31
32
 
# File 'lib/elastomer/client/docs.rb', line 30

def name
  @name
end

#type ⇒ Object (readonly)

Returns the value of attribute type.



30
31
32
 
# File 'lib/elastomer/client/docs.rb', line 30

def type
  @type
end

Instance Method Details

#bulk(params = {}, &block) ⇒ Object

Perform bulk indexing and/or delete operations. The current index name and document type will be passed to the bulk API call as part of the request parameters.

params - Parameters Hash that will be passed to the bulk API call. block - Required block that is used to accumulate bulk API operations.

All the operations will be passed to the search cluster via a
single API request.

Yields a Bulk instance for building bulk API call bodies.

Examples

docs.bulk do |b|
  b.index( document1 )
  b.index( document2 )
  b.delete( document3 )
  ...
end

Returns the response body as a Hash



306
307
308
309
310
311
 
# File 'lib/elastomer/client/docs.rb', line 306

def bulk( params = {}, &block )
  raise 'a block is required' if block.nil?

  params = {:index => self.name, :type => self.type}.merge params
  client.bulk params, &block
end

#count(query, params = nil) ⇒ Object

Executes a search query, but instead of returning results, returns the number of documents matched. This method supports both the “request body” query and the “URI request” query. When using the request body semantics, the query hash must contain the :query key. Otherwise we assume a URI request is being made.

See www.elasticsearch.org/guide/reference/api/count/

query - The query body as a Hash params - Parameters Hash

Examples

# request body query
count({:match_all => {}}, :type => 'tweet')

# same thing but using the URI request method
count(:q => '*:*', :type => 'tweet')

Returns the response body as a Hash



173
174
175
176
177
178
 
# File 'lib/elastomer/client/docs.rb', line 173

def count(query, params = nil)
  query, params = extract_params(query) if params.nil?

  response = client.get '/{index}{/type}/_count', update_params(params, :body => query)
  response.body
end

#defaults ⇒ Object

Internal: Returns a Hash containing default parameters.



408
409
410
 
# File 'lib/elastomer/client/docs.rb', line 408

def defaults
  { :index => name, :type => type }
end

#delete(params = {}) ⇒ Object

Delete a document from the index based on the document ID. The :id is provided as part of the params hash.

See www.elasticsearch.org/guide/reference/api/delete/

params - Parameters Hash

Returns the response body as a Hash



65
66
67
68
 
# File 'lib/elastomer/client/docs.rb', line 65

def delete( params = {} )
  response = client.delete '/{index}/{type}/{id}', update_params(params, :action => 'docs.delete')
  response.body
end

#delete_by_query(query, params = nil) ⇒ Object

Delete documents from one or more indices and one or more types based on a query. This method supports both the “request body” query and the “URI request” query. When using the request body semantics, the query hash must contain the :query key. Otherwise we assume a URI request is being made.

See www.elasticsearch.org/guide/reference/api/delete-by-query/

query - The query body as a Hash params - Parameters Hash

Examples

# request body query
delete_by_query({:query => {:match_all => {}}}, :type => 'tweet')

# same thing but using the URI request method
delete_by_query(:q => '*:*', :type => 'tweet')

Returns the response body as a hash



200
201
202
203
204
205
 
# File 'lib/elastomer/client/docs.rb', line 200

def delete_by_query( query, params = nil )
  query, params = extract_params(query) if params.nil?

  response = client.delete '/{index}{/type}/_query', update_params(params, :body => query, :action => 'docs.delete_by_query')
  response.body
end

#explain(query, params = nil) ⇒ Object

Compute a score explanation for a query and a specific document. This can give useful feedback about why a document matched or didn’t match a query. The document :id is provided as part of the params hash.

See www.elasticsearch.org/guide/reference/api/explain/

query - The query body as a Hash params - Parameters Hash

Examples

explain({:query => {:term => {"message" => "search"}}}, :id => 1)

explain(:q => "message:search", :id => 1)

Returns the response body as a hash



253
254
255
256
257
258
 
# File 'lib/elastomer/client/docs.rb', line 253

def explain(query, params = nil)
  query, params = extract_params(query) if params.nil?

  response = client.get '/{index}/{type}/{id}/_explain', update_params(params, :body => query, :action => 'docs.explain')
  response.body
end

#extract_params(query, params = nil) ⇒ Object

Internal: Allow params to be passed as the first argument to methods that take both an optional query hash and params.

query - query hash OR params hash params - params hash OR nil if no query

Returns an array of the query (possibly nil) and params Hash.



419
420
421
422
423
424
425
426
427
428
 
# File 'lib/elastomer/client/docs.rb', line 419

def extract_params(query, params=nil)
  if params.nil?
    if query.key? :query
      params = {}
    else
      params, query = query, nil
    end
  end
  [query, params]
end

#from_document(document) ⇒ Object

Internal: Given a ‘document` generate an options hash that will override parameters based on the content of the document. The document will be returned as the value of the :body key.

We only extract information from the document if it is given as a Hash. We do not parse JSON encoded Strings.

document - A document Hash or JSON encoded String.

Returns an options Hash extracted from the document.



378
379
380
381
382
383
384
385
386
387
388
389
390
391
 
# File 'lib/elastomer/client/docs.rb', line 378

def from_document( document )
  opts = {:body => document}

  unless String === document
    %w[_id _type _routing _parent _ttl _timestamp _retry_on_conflict].each do |field|
      key = field.sub(/^_/, '').to_sym

      opts[key] = document.delete field if document.key? field
      opts[key] = document.delete field.to_sym if document.key? field.to_sym
    end
  end

  opts
end

#get(params = {}) ⇒ Object

Retrieve a document from the index based on its ID. The :id is provided as part of the params hash.

See www.elasticsearch.org/guide/reference/api/get/

params - Parameters Hash

Returns the response body as a Hash



78
79
80
81
 
# File 'lib/elastomer/client/docs.rb', line 78

def get( params = {} )
  response = client.get '/{index}/{type}/{id}', update_params(params, :action => 'docs.get')
  response.body
end

#index(document, params = {}) ⇒ Object Also known as: add

Adds or updates a document in the index, making it searchable. See www.elasticsearch.org/guide/reference/api/index_/

document - The document (as a Hash or JSON encoded String) to add to the index params - Parameters Hash

Returns the response body as a Hash



39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
 
# File 'lib/elastomer/client/docs.rb', line 39

def index( document, params = {} )
  overrides = from_document(document)
  params = update_params(params, overrides)
  params[:action] = 'docs.index'

  params.delete(:id) if params[:id].nil? || params[:id].to_s =~ /\A\s*\z/

  response =
      if params[:id]
        client.put '/{index}/{type}/{id}', params
      else
        client.post '/{index}/{type}', params
      end

  response.body
end

#more_like_this(query, params = nil) ⇒ Object

Search for documents similar to a specific document. The document :id is provided as part of the params hash. If the _all field is not enabled, :mlt_fields must be passed. A query cannot be present in the query body, but other fields like :size and :facets are allowed.

See www.elasticsearch.org/guide/reference/api/more-like-this/

params - Parameters Hash

Examples

more_like_this(:mlt_fields => "title", :min_term_freq => 1, :type => "doc1", :id => 1)

# with query hash
more_like_this({:from => 5, :size => 10}, :mlt_fields => "title",
                :min_term_freq => 1, :type => "doc1", :id => 1)

Returns the response body as a hash



230
231
232
233
234
235
 
# File 'lib/elastomer/client/docs.rb', line 230

def more_like_this(query, params = nil)
  query, params = extract_params(query) if params.nil?

  response = client.get '/{index}/{type}/{id}/_mlt', update_params(params, :body => query, :action => 'docs.more_like_this')
  response.body
end

#multi_get(docs, params = {}) ⇒ Object

Allows to get multiple documents based on an index, type, and id (and possibly routing). See www.elasticsearch.org/guide/reference/api/multi-get/

docs - The Hash describing the documents to get params - Parameters Hash

Returns the response body as a Hash



103
104
105
106
107
108
109
 
# File 'lib/elastomer/client/docs.rb', line 103

def multi_get( docs, params = {} )
  overrides = from_document(docs)
  overrides[:action] = 'docs.multi_get'

  response = client.get '{/index}{/type}{/id}/_mget', update_params(params, overrides)
  response.body
end

#multi_search(params = {}, &block) ⇒ Object

Execute an array of searches in bulk. Results are returned in an array in the order the queries were sent. The current index name and document type will be passed to the multi_search API call as part of the request parameters.

See www.elasticsearch.org/guide/reference/api/multi-search/

params - Parameters Hash that will be passed to the API call. block - Required block that is used to accumulate searches.

All the operations will be passed to the search cluster
via a single API request.

Yields a MultiSearch instance for building multi_search API call bodies.

Examples

docs.multi_search do |m|
  m.search({:query => {:match_all => {}}, :search_type => :count)
  m.search({:query => {:field => {"foo" => "bar"}}})
  ...
end

Returns the response body as a Hash



361
362
363
364
365
366
 
# File 'lib/elastomer/client/docs.rb', line 361

def multi_search(params = {}, &block)
  raise 'a block is required' if block.nil?

  params = {:index => self.name, :type => self.type}.merge params
  client.multi_search params, &block
end

#scan(query, opts = {}) ⇒ Object

Create a new Scan instance for scrolling all results from a ‘query`. The Scan will be scoped to the current index and document type.

query - The query to scan as a Hash or a JSON encoded String opts - Options Hash

:index  - the name of the index to search
:type   - the document type to search
:scroll - the keep alive time of the scrolling request (5 minutes by default)
:size   - the number of documents per shard to fetch per scroll

Examples

scan = docs.scan('{"query":{"match_all":{}}}')
scan.each_document do |document|
  document['_id']
  document['_source']
end

Returns a new Scan instance



332
333
334
335
 
# File 'lib/elastomer/client/docs.rb', line 332

def scan( query, opts = {} )
  opts = {:index => name, :type => type}.merge opts
  client.scan query, opts
end

#search(query, params = nil) ⇒ Object

Allows you to execute a search query and get back search hits that match the query. This method supports both the “request body” query and the “URI request” query. When using the request body semantics, the query hash must contain the :query key. Otherwise we assume a URI request is being made.

See www.elasticsearch.org/guide/reference/api/search/

query - The query body as a Hash params - Parameters Hash

Examples

# request body query
search({:query => {:match_all => {}}}, :type => 'tweet')

# same thing but using the URI request method
search(:q => '*:*', :type => 'tweet')

Returns the response body as a hash



146
147
148
149
150
151
 
# File 'lib/elastomer/client/docs.rb', line 146

def search( query, params = nil )
  query, params = extract_params(query) if params.nil?

  response = client.get '/{index}{/type}/_search', update_params(params, :body => query, :action => 'docs.search')
  response.body
end

#source(params = {}) ⇒ Object

Retrieve the document source from the index based on the ID and type. The :id is provided as part of the params hash.

See www.elasticsearch.org/guide/en/elasticsearch/reference/current/docs-get.html#_source

params - Parameters Hash

Returns the response body as a Hash



91
92
93
94
 
# File 'lib/elastomer/client/docs.rb', line 91

def source( params = {} )
  response = client.get '/{index}/{type}/{id}/_source', update_params(params, :action => 'docs.source')
  response.body
end

#update(script, params = {}) ⇒ Object

Update a document based on a script provided. See www.elasticsearch.org/guide/reference/api/update/

script - The script (as a Hash) used to update the document in place params - Parameters Hash

Returns the response body as a Hash



118
119
120
121
122
123
124
 
# File 'lib/elastomer/client/docs.rb', line 118

def update( script, params = {} )
  overrides = from_document(script)
  overrides[:action] = 'docs.update'

  response = client.post '/{index}/{type}/{id}/_update', update_params(params, overrides)
  response.body
end

#update_params(params, overrides = nil) ⇒ Object

Internal: Add default parameters to the ‘params` Hash and then apply `overrides` to the params if any are given.

params - Parameters Hash overrides - Optional parameter overrides as a Hash

Returns a new params Hash.



400
401
402
403
404
405
 
# File 'lib/elastomer/client/docs.rb', line 400

def update_params( params, overrides = nil )
  h = defaults.update params
  h.update overrides unless overrides.nil?
  h[:routing] = h[:routing].join(',') if Array === h[:routing]
  h
end

#validate(query, params = nil) ⇒ Object

Validate a potentially expensive query before running it. The :explain parameter can be used to get detailed information about why a query failed.

See www.elasticsearch.org/guide/reference/api/validate/

query - The query body as a Hash params - Parameters Hash

Examples

# request body query
validate(:query_string => {:query => "*:*"})

# same thing but using the URI query parameter
validate({:q => "post_date:foo"}, :explain => true)

Returns the response body as a hash



278
279
280
281
282
283
 
# File 'lib/elastomer/client/docs.rb', line 278

def validate(query, params = nil)
  query, params = extract_params(query) if params.nil?

  response = client.get '/{index}{/type}/_validate/query', update_params(params, :body => query, :action => 'docs.validate')
  response.body
end