Class: Gcloud::Search::Document

Inherits:
Object
  • Object
show all
Defined in:
lib/gcloud/search/document.rb,
lib/gcloud/search/document/list.rb

Overview

# Document

A document is an object that stores data that can be searched. Each document has a #doc_id that is unique within its index, a #rank, and a list of #fields that contain typed data. Its field values can be accessed through hash-like methods such as #[] and #each.

Examples:

require "gcloud"

gcloud = Gcloud.new
search = gcloud.search
index = search.index "products"

document = index.document "product-sku-000001"
document.add "price", 24.95
index.save document
document.rank #=> 1443648166
document["price"] #=> 24.95

See Also:

Defined Under Namespace

Classes: List

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Document

Returns a new instance of Document.



52
53
54
55
 
# File 'lib/gcloud/search/document.rb', line 52

def initialize
  @fields = Fields.new
  @raw = {}
end

Class Method Details

.from_hash(hash) ⇒ Object 



262
263
264
265
266
267
 
# File 'lib/gcloud/search/document.rb', line 262

def self.from_hash hash
  doc = new
  doc.instance_variable_set "@raw", hash
  doc.instance_variable_set "@fields", Fields.from_raw(hash["fields"])
  doc
end

Instance Method Details

#[](name) ⇒ FieldValues

Retrieve the field values associated to a field name.

Examples:

require "gcloud"

gcloud = Gcloud.new
search = gcloud.search
index = search.index "products"

document = index.document "product-sku-000001"
puts "The document description is:"
document["description"].each do |value|
  puts "* #{value} (#{value.type}) [#{value.lang}]"
end

Parameters:

  • name (String) —

    The name of the field. New values will be configured with this name.

Returns:



121
122
123
 
# File 'lib/gcloud/search/document.rb', line 121

def [] name
  @fields[name]
end

#add(name, value, type: nil, lang: nil) ⇒ Object

Add a new value. If the field name does not exist it will be added. If the field value is a DateTime or Numeric, or the type is set to ‘:datetime` or `:number`, then the added value will replace any existing values of the same type (since there can be only one).

Examples:

require "gcloud"

gcloud = Gcloud.new
search = gcloud.search
index = search.index "products"

document = index.document "product-sku-000001"
document.add "sku", "product-sku-000001", type: :atom
document.add "description", "The best T-shirt ever.",
             type: :text, lang: "en"
document.add "description", "<p>The best T-shirt ever.</p>",
             type: :html, lang: "en"
document.add "price", 24.95

Parameters:

  • name (String) —

    The name of the field.

  • value (String, Datetime, Float) —

    The value to add to the field.

  • type (Symbol) (defaults to: nil) —

    The type of the field value. An attempt is made to set the correct type when this option is missing, although it must be provided for ‘:geo` values. A field can have multiple values with same or different types; however, it cannot have multiple `:datetime` or `:number` values.

    The following values are supported:

    • ‘:default` - The value is a string. The format will be automatically detected. This is the default value for strings.

    • ‘:text` - The value is a string with maximum length 1024**2 characters.

    • ‘:html` - The value is an HTML-formatted string with maximum length 1024**2 characters.

    • ‘:atom` - The value is a string with maximum length 500 characters.

    • ‘:geo` - The value is a point on earth described by latitude and longitude coordinates, represented in string with any of the listed [ways of writing coordinates](en.wikipedia.org/wiki/Geographic_coordinate_conversion).

    • ‘:datetime` - The value is a `DateTime`.

    • ‘:number` - The value is a `Numeric` between -2,147,483,647 and 2,147,483,647. The value will be stored as a double precision floating point value in Cloud Search.

  • lang (String) (defaults to: nil) —

    The language of a string value. Must be a valid [ISO 639-1 code](en.wikipedia.org/wiki/List_of_ISO_639-1_codes).



182
183
184
 
# File 'lib/gcloud/search/document.rb', line 182

def add name, value, type: nil, lang: nil
  @fields[name].add value, type: type, lang: lang
end

#delete(name, &block) ⇒ Object

Deletes a field and all values. (See Fields#delete)

Examples:

require "gcloud"

gcloud = Gcloud.new
search = gcloud.search
index = search.index "products"

document = index.document "product-sku-000001"
document.delete "description"

Parameters:

  • name (String) —

    The name of the field.



201
202
203
 
# File 'lib/gcloud/search/document.rb', line 201

def delete name, &block
  @fields.delete name, &block
end

#doc_id ⇒ Object

The unique identifier for the document. Can be set explicitly when the document is saved. (See Index#document and #doc_id=.) If missing, it is automatically assigned to the document when saved.



62
63
64
 
# File 'lib/gcloud/search/document.rb', line 62

def doc_id
  @raw["docId"]
end

#doc_id=(new_doc_id) ⇒ Object

Sets the unique identifier for the document.

Must contain only visible, printable ASCII characters (ASCII codes 33 through 126 inclusive) and be no longer than 500 characters. It cannot begin with an exclamation point (!), and it cannot begin and end with double underscores (__).



73
74
75
 
# File 'lib/gcloud/search/document.rb', line 73

def doc_id= new_doc_id
  @raw["docId"] = new_doc_id
end

#each(&block) ⇒ Object

Calls block once for each field, passing the field name and values pair as parameters. If no block is given an enumerator is returned instead. (See Fields#each)

Examples:

require "gcloud"

gcloud = Gcloud.new
search = gcloud.search
index = search.index "products"

document = index.document "product-sku-000001"
puts "The document #{document.doc_id} has the following fields:"
document.each do |name, values|
  puts "* #{name}:"
  values.each do |value|
    puts "  * #{value} (#{value.type})"
  end
end


226
227
228
 
# File 'lib/gcloud/search/document.rb', line 226

def each &block
  @fields.each(&block)
end

#fields ⇒ Object

The fields in the document. Each field has a name (String) and a list of values (FieldValues). (See Fields)



130
131
132
 
# File 'lib/gcloud/search/document.rb', line 130

def fields
  @fields
end

#inspect ⇒ Object 



253
254
255
256
257
258
 
# File 'lib/gcloud/search/document.rb', line 253

def inspect
  insp_rank = ""
  insp_rank = ", rank: #{rank}" if rank
  insp_fields = ", fields: (#{fields.names.map(&:inspect).join ', '})"
  "#{self.class}(doc_id: #{doc_id.inspect}#{insp_rank}#{insp_fields})"
end

#names ⇒ Object

Returns a new array populated with all the field names. (See Fields#names)

Examples:

require "gcloud"

gcloud = Gcloud.new
search = gcloud.search
index = search.index "products"

document = index.document "product-sku-000001"
puts "The document #{document.doc_id} has the following fields:"
document.names.each do |name|
  puts "* #{name}:"
end


247
248
249
 
# File 'lib/gcloud/search/document.rb', line 247

def names
  @fields.names
end

#rank ⇒ Object

A positive integer which determines the default ordering of documents returned from a search. The rank can be set explicitly when the document is saved. (See Index#document and #rank=.) If missing, it is automatically assigned to the document when saved.



83
84
85
 
# File 'lib/gcloud/search/document.rb', line 83

def rank
  @raw["rank"]
end

#rank=(new_rank) ⇒ Object

Sets the rank of the document.

The same rank should not be assigned to many documents, and should never be assigned to more than 10,000 documents. By default (when it is not specified or set to 0), it is set at the time the document is created to the number of seconds since January 1, 2011. The rank can be used in Index#search options ‘expressions`, `order`, and `fields`, where it is referenced as `rank`.



96
97
98
 
# File 'lib/gcloud/search/document.rb', line 96

def rank= new_rank
  @raw["rank"] = new_rank
end

#to_hash ⇒ Object 



271
272
273
274
275
 
# File 'lib/gcloud/search/document.rb', line 271

def to_hash
  hash = @raw.dup
  hash["fields"] = @fields.to_raw
  hash
end