gcloud 0.5.0 → 0.6.0

data/lib/gcloud/search/fields.rb

@@ -0,0 +1,267 @@
+#--
+# Copyright 2015 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require "gcloud/search/field_values"
+require "gcloud/search/field_value"
+
+module Gcloud
+  module Search
+    ##
+    # = Fields
+    #
+    # Fields is the object that provides access to a document's fields.
+    #
+    # Each field has a name (String) and a list of values. Each field name
+    # consists of only ASCII characters, must be unique within the document and
+    # is case sensitive. A field name must start with a letter and can contain
+    # letters, digits, or underscore, with a maximum of 500 characters.
+    #
+    # A field can have multiple values with same or different types; however, it
+    # cannot have multiple datetime (DateTime) or number (Float) values. (See
+    # FieldValues and FieldValue)
+    #
+    #   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}:"
+    #     document[name].each do |value|
+    #       puts "  * #{value} (#{value.type})"
+    #     end
+    #   end
+    #
+    # For more information see {Documents and
+    # fields}[https://cloud.google.com/search/documents_indexes].
+    #
+    class Fields
+      include Enumerable
+
+      ##
+      # Create a new empty fields object.
+      def initialize #:nodoc:
+        @hash = {}
+      end
+
+      ##
+      # Retrieve the field values associated to a field name.
+      #
+      # === Parameters
+      #
+      # +name+::
+      #   The name of the field. New values will be configured with this name.
+      #   (+String+)
+      #
+      # === Returns
+      #
+      # FieldValues
+      #
+      # === Example
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   search = gcloud.search
+      #   index = search.index "products"
+      #
+      #   document = index.document "product-sku-000001"
+      #   puts "The document description is:"
+      #   document.fields["description"].each do |value|
+      #     puts "* #{value} (#{value.type}) [#{value.lang}]"
+      #   end
+      #
+      def [] name
+        @hash[name] ||= FieldValues.new name
+      end
+
+      # rubocop:disable Metrics/LineLength
+      # Disabled because there are links in the docs that are long.
+
+      ##
+      # 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).
+      #
+      # === Parameters
+      #
+      # +name+::
+      #   The name of the field. (+String+)
+      # +value+::
+      #   The value to add to the field. (+String+ or +Datetime+ or +Float+)
+      # +type+::
+      #   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. (+Symbol+)
+      #
+      #   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}[http://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+::
+      #   The language of a string value. Must be a valid {ISO 639-1
+      #   code}[https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes].
+      #   (+String+)
+      #
+      # === Example
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   search = gcloud.search
+      #   index = search.index "products"
+      #
+      #   document = index.document "product-sku-000001"
+      #   document.fields.add "sku", "product-sku-000001", type: :atom
+      #   document.fields.add "description", "The best T-shirt ever.",
+      #                       type: :text, lang: "en"
+      #   document.fields.add "description", "<p>The best T-shirt ever.</p>",
+      #                       type: :html, lang: "en"
+      #   document.fields.add "price", 24.95
+      #
+      def add name, value, type: nil, lang: nil
+        @hash[name] ||= FieldValues.new name
+        @hash[name].add value, type: type, lang: lang
+      end
+
+      # rubocop:enable Metrics/LineLength
+
+      ##
+      # Deletes a field and all values.
+      #
+      # === Parameters
+      #
+      # +name+::
+      #   The name of the field. (+String+)
+      #
+      # === Example
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   search = gcloud.search
+      #   index = search.index "products"
+      #
+      #   document = index.document "product-sku-000001"
+      #   document.fields.delete "description"
+      #
+      def delete name, &block
+        @hash.delete name, &block
+      end
+
+      ##
+      # 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.
+      #
+      # === Example
+      #
+      #   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.fields.each do |name, values|
+      #     puts "* #{name}:"
+      #     values.each do |value|
+      #       puts "  * #{value} (#{value.type})"
+      #     end
+      #   end
+      #
+      def each &block
+        # Only yield fields that have values.
+        fields_with_values.each(&block)
+      end
+
+      ##
+      # Returns a new array populated with all the field names.
+      #
+      #   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.fields.names.each do |name|
+      #     puts "* #{name}:"
+      #   end
+      #
+      def names
+        # Only return fields that have values.
+        fields_with_values.keys
+      end
+
+      ##
+      # Create a new Fields instance from a raw Hash.
+      def self.from_raw raw #:nodoc:
+        hsh = {}
+        raw.each do |k, v|
+          hsh[k] = FieldValues.from_raw k, v["values"]
+        end unless raw.nil?
+        fields = new
+        fields.instance_variable_set "@hash", hsh
+        fields
+      end
+
+      ##
+      # Create a raw Hash object containing all the field names and values.
+      def to_raw #:nodoc:
+        hsh = {}
+        @hash.each do |k, v|
+          hsh[k] = v.to_raw unless v.empty?
+        end
+        hsh
+      end
+
+      protected
+
+      ##
+      # Find all the fields that have values. This is needed because a field is
+      # required to have at least one value.
+      #
+      # Users can remove all values, and the empty FieldValues object will
+      # remain in the internal hash. This is the same as not having that field.
+      #
+      # Users can also reference the field by name before adding a value. So we
+      # have multiple valid use cases which add an empty FieldValues object to
+      # the hash.
+      def fields_with_values #:nodoc:
+        @hash.select { |_name, values| values.any? }
+      end
+    end
+  end
+end

data/lib/gcloud/search/index.rb

@@ -0,0 +1,613 @@
+#--
+# Copyright 2015 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require "gcloud/search/document"
+require "gcloud/search/index/list"
+require "gcloud/search/result"
+
+module Gcloud
+  module Search
+    ##
+    # = Index
+    #
+    # An index manages Document instances for retrieval. Indexes cannot be
+    # created, updated, or deleted directly on the server: They are derived from
+    # the documents that reference them. You can manage groups of documents by
+    # putting them into separate indexes.
+    #
+    # With an index, you can retrieve documents with #find and #documents;
+    # manage them with #document, #save, and #remove; and perform searches over
+    # their fields with #search.
+    #
+    #   require "gcloud"
+    #
+    #   gcloud = Gcloud.new
+    #   search = gcloud.search
+    #   index = search.index "books"
+    #
+    #   results = index.search "dark stormy"
+    #   results.each do |result|
+    #     puts result.doc_id
+    #   end
+    #
+    # For more information, see {Documents and
+    # Indexes}[https://cloud.google.com/search/documents_indexes].
+    #
+    class Index
+      ##
+      # The Connection object.
+      attr_accessor :connection #:nodoc:
+
+      ##
+      # The raw data object.
+      attr_accessor :raw #:nodoc:
+
+      ##
+      # Creates a new Index instance.
+      #
+      def initialize #:nodoc:
+        @connection = nil
+        @raw = nil
+      end
+
+      ##
+      # The index identifier. May be defined by the server or by the client.
+      # Must be unique within the project. It cannot be an empty string. It must
+      # contain only visible, printable ASCII characters (ASCII codes 33 through
+      # 126 inclusive) and be no longer than 100 characters. It cannot begin
+      # with an exclamation point (<code>!</code>), and it cannot begin and end
+      # with double underscores (<code>__</code>).
+      def index_id
+        @raw["indexId"]
+      end
+
+      ##
+      # The names of fields in which TEXT values are stored. See {Index schemas
+      # }[https://cloud.google.com/search/documents_indexes#index_schemas].
+      def text_fields
+        return @raw["indexedField"]["textFields"] if @raw["indexedField"]
+        []
+      end
+
+      ##
+      # The names of fields in which HTML values are stored. See {Index schemas
+      # }[https://cloud.google.com/search/documents_indexes#index_schemas].
+      def html_fields
+        return @raw["indexedField"]["htmlFields"] if @raw["indexedField"]
+        []
+      end
+
+      ##
+      # The names of fields in which ATOM values are stored. See {Index schemas
+      # }[https://cloud.google.com/search/documents_indexes#index_schemas].
+      def atom_fields
+        return @raw["indexedField"]["atomFields"] if @raw["indexedField"]
+        []
+      end
+
+      ##
+      # The names of fields in which DATE values are stored. See {Index schemas
+      # }[https://cloud.google.com/search/documents_indexes#index_schemas].
+      def datetime_fields
+        return @raw["indexedField"]["dateFields"] if @raw["indexedField"]
+        []
+      end
+
+      ##
+      # The names of fields in which NUMBER values are stored. See {Indexschemas
+      # }[https://cloud.google.com/search/documents_indexes#index_schemas].
+      def number_fields
+        return @raw["indexedField"]["numberFields"] if @raw["indexedField"]
+        []
+      end
+
+      ##
+      # The names of fields in which GEO values are stored. See {Index
+      # }[https://cloud.google.com/search/documents_indexes#index_schemas].
+      def geo_fields
+        return @raw["indexedField"]["geoFields"] if @raw["indexedField"]
+        []
+      end
+
+      ##
+      # The names of all the fields that are stored on the index.
+      def field_names
+        (text_fields + html_fields + atom_fields + datetime_fields +
+          number_fields + geo_fields).uniq
+      end
+
+      ##
+      # The field value types that are stored on the field name.
+      def field_types_for name
+        {
+          text: text_fields.include?(name),
+          html: html_fields.include?(name),
+          atom: atom_fields.include?(name),
+          datetime: datetime_fields.include?(name),
+          number: number_fields.include?(name),
+          geo: geo_fields.include?(name)
+        }.delete_if { |_k, v| !v }.keys
+      end
+
+      ##
+      # Retrieves an existing document by id.
+      #
+      # === Parameters
+      #
+      # +doc_id+::
+      #   The id of a document or a Document instance. (+String+ or Document)
+      #
+      # === Returns
+      #
+      # Gcloud::Search::Document or +nil+ if the document does not exist
+      #
+      # === Example
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   search = gcloud.search
+      #   index = search.index "products"
+      #
+      #   document = index.find "product-sku-000001"
+      #   puts document.doc_id
+      #
+      def find doc_id
+        # Get the id if passes a Document object
+        doc_id = doc_id.doc_id if doc_id.respond_to? :doc_id
+        ensure_connection!
+        resp = connection.get_doc index_id, doc_id
+        return Document.from_hash(JSON.parse(resp.body)) if resp.success?
+        return nil if resp.status == 404
+        fail ApiError.from_response(resp)
+      rescue JSON::ParserError
+        raise ApiError.from_response(resp)
+      end
+      alias_method :get, :find
+
+      ##
+      # Helper for creating a new Document instance. The returned instance is
+      # local: It is either not yet saved to the service (see #save), or if it
+      # has been given the id of an existing document, it is not yet populated
+      # with the document's data (see #find).
+      #
+      # === Parameters
+      #
+      # +doc_id+::
+      #   The unique identifier of the new document. This is optional. When the
+      #   document is saved, this value 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
+      #   (<code>!</code>), and it cannot begin and end with double underscores
+      #   (<code>__</code>). (+String+)
+      # +rank+::
+      #   The rank of the new document. This is optional. A positive integer
+      #   which determines the default ordering of documents returned from a
+      #   search. It is a bad idea to assign the same rank to many documents,
+      #   and the same rank 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 saved to the number of seconds since
+      #   January 1, 2011. The rank can be used in the +expressions+, +order+,
+      #   and +fields+ options in #search, where it should referenced as
+      #   +rank+. (+Integer+)
+      #
+      # === Returns
+      #
+      # Gcloud::Search::Document
+      #
+      # === Example
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   search = gcloud.search
+      #   index = search.index "products"
+      #
+      #   document = index.document "product-sku-000001"
+      #   document.doc_id #=> nil
+      #   document.rank #=> nil
+      #
+      # To check if an index already contains a document with the same id, pass
+      # the instance to #find:
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   search = gcloud.search
+      #   index = search.index "products"
+      #
+      #   document = index.document "product-sku-000001"
+      #   document = index.find document # returns nil if not present
+      #
+      def document doc_id = nil, rank = nil
+        Document.new.tap do |d|
+          d.doc_id = doc_id
+          d.rank = rank
+        end
+      end
+
+      ##
+      # Retrieves the list of documents belonging to the index.
+      #
+      # === Parameters
+      #
+      # +token+::
+      #   A previously-returned page token representing part of the larger set
+      #   of results to view. (+String+)
+      # +max+::
+      #   Maximum number of documents to return. The default is +100+.
+      #   (+Integer+)
+      #
+      # === Returns
+      #
+      # Array of Gcloud::Search::Document (See Gcloud::Search::Document::List)
+      #
+      # === Examples
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   search = gcloud.search
+      #   index = search.index "products"
+      #
+      #   documents = index.documents
+      #   documents.each do |index|
+      #     puts index.index_id
+      #   end
+      #
+      # If you have a significant number of documents, you may need to paginate
+      # through them: (See Gcloud::Search::Document::List)
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   search = gcloud.search
+      #   index = search.index "products"
+      #
+      #   documents = index.documents
+      #   loop do
+      #     documents.each do |index|
+      #       puts index.index_id
+      #     end
+      #     break unless documents.next?
+      #     documents = documents.next
+      #   end
+      #
+      def documents token: nil, max: nil, view: nil
+        ensure_connection!
+        options = { token: token, max: max, view: view }
+        resp = connection.list_docs index_id, options
+        return Document::List.from_response(resp, self) if resp.success?
+        fail ApiError.from_response(resp)
+      end
+
+      ##
+      # Saves a new or existing document to the index. If the document instance
+      # is new and has been given an id (see #document), it will replace an
+      # existing document in the index that has the same unique id.
+      #
+      # === Parameters
+      #
+      # +document+::
+      #   A Document instance, either new (see #document) or existing (see
+      #   #find).
+      #
+      # === Returns
+      #
+      # Gcloud::Search::Document
+      #
+      # === Example
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   search = gcloud.search
+      #   index = search.index "products"
+      #
+      #   document = index.document "product-sku-000001"
+      #   document.doc_id #=> nil
+      #   document.rank #=> nil
+      #
+      #   document = index.save document
+      #   document.doc_id #=> "-2486020449015432113"
+      #   document.rank #=> 154223228
+      #
+      def save document
+        ensure_connection!
+        resp = connection.create_doc index_id, document.to_hash
+        if resp.success?
+          raw = document.instance_variable_get "@raw"
+          raw.merge! JSON.parse(resp.body)
+          return document
+        end
+        fail ApiError.from_response(resp)
+      rescue JSON::ParserError
+        raise ApiError.from_response(resp)
+      end
+
+      ##
+      # Permanently deletes the document from the index.
+      #
+      # === Parameters
+      #
+      # +doc_id+::
+      #   The id of the document. (+String+)
+      #
+      # === Returns
+      #
+      # +true+ if successful
+      #
+      # === Example
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   search = gcloud.search
+      #   index = search.index "products"
+      #
+      #   index.remove "product-sku-000001"
+      #
+      def remove doc_id
+        # Get the id if passes a Document object
+        doc_id = doc_id.doc_id if doc_id.respond_to? :doc_id
+        ensure_connection!
+        resp = connection.delete_doc index_id, doc_id
+        return true if resp.success?
+        fail ApiError.from_response(resp)
+      end
+
+      ##
+      # Permanently deletes the index by deleting its documents. (Indexes cannot
+      # be created, updated, or deleted directly on the server: They are derived
+      # from the documents that reference them.)
+      #
+      # === Parameters
+      #
+      # +force+::
+      #   If +true+, ensures the deletion of the index by first deleting all
+      #   documents. If +false+ and the index contains documents, the request
+      #   will fail. Default is +false+. (+Boolean+)
+      #
+      # === Examples
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   search = gcloud.search
+      #   index = search.index "books"
+      #
+      # An index containing documents can be forcefully deleted with the +force+
+      # option:
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   search = gcloud.search
+      #   index = search.index "books"
+      #   index.delete force: true
+      #
+      def delete force: false
+        ensure_connection!
+        docs_to_be_removed = documents view: "ID_ONLY"
+        return if docs_to_be_removed.empty?
+        unless force
+          fail "Unable to delete because documents exist. Use force option."
+        end
+        while docs_to_be_removed
+          docs_to_be_removed.each { |d| remove d }
+          if docs_to_be_removed.next?
+            docs_to_be_removed = documents token: docs_to_be_removed.token,
+                                           view: "ID_ONLY"
+          else
+            docs_to_be_removed = nil
+          end
+        end
+      end
+
+      ##
+      # New Index from a raw data object.
+      def self.from_raw raw, conn #:nodoc:
+        new.tap do |f|
+          f.raw = raw
+          f.connection = conn
+        end
+      end
+
+      # rubocop:disable Metrics/LineLength
+      # Disabled because there are links in the docs that are long.
+
+      ##
+      # Runs a search against the documents in the index using the provided
+      # query. For more information see the REST API documentation for
+      # {indexes.search}[https://cloud.google.com/search/reference/rest/v1/projects/indexes/search].
+      #
+      # === Parameters
+      #
+      # +query+::
+      #   The query string in search query syntax. If the query is +nil+ or
+      #   empty, all documents are returned. For more information see {Query
+      #   Strings}[https://cloud.google.com/search/query]. (+String+)
+      # +expressions+::
+      #   Customized expressions used in +order+ or +fields+. The expression can
+      #   contain fields in Document, the built-in fields ( +rank+, the document
+      #   +rank+, and +score+ if scoring is enabled) and fields defined in
+      #   +expressions+. All field expressions expressed as a +Hash+ with the
+      #   keys as the +name+ and the values as the +expression+. The expression
+      #   value can be a combination of supported functions encoded in the
+      #   string. Expressions involving number fields can use the arithmetical
+      #   operators (+, -, *, /) and the built-in numeric functions (+max+,
+      #   +min+, +pow+, +count+, +log+, +abs+). Expressions involving geopoint
+      #   fields can use the +geopoint+ and +distance+ functions. Expressions
+      #   for text and html fields can use the +snippet+ function. (+Hash+)
+      # +matched_count_accuracy+::
+      #   Minimum accuracy requirement for Result::List#matched_count. If
+      #   specified, +matched_count+ will be accurate to at least that number.
+      #   For example, when set to 100, any <code>matched_count <= 100</code> is
+      #   accurate. This option may add considerable latency/expense. By default
+      #   (when it is not specified or set to 0), the accuracy is the same as
+      #   +max+. (+Integer+)
+      # +offset+::
+      #   Used to advance pagination to an arbitrary result, independent of the
+      #   previous results. Offsets are an inefficient alternative to using
+      #   +token+. (Both cannot be both set.) The default is 0.
+      #   (+Integer+)
+      # +order+::
+      #   A comma-separated list of fields for sorting on the search result,
+      #   including fields from Document, the built-in fields (+rank+ and
+      #   +score+), and fields defined in expressions. The default sorting
+      #   order is ascending. To specify descending order for a field, a suffix
+      #   <code>" desc"</code> should be appended to the field name. For
+      #   example: <code>orderBy="foo desc,bar"</code>. The default value for
+      #   text sort is the empty string, and the default value for numeric sort
+      #   is 0. If not specified, the search results are automatically sorted by
+      #   descending +rank+. Sorting by ascending +rank+ is not allowed.
+      #   (+String+)
+      # +fields+::
+      #   The fields to return in the Search::Result objects. These can be
+      #   fields from Document, the built-in fields +rank+ and +score+, and
+      #   fields defined in expressions. The default is to return all fields.
+      #   (+String+ or +Array+ of +String+)
+      # +scorer+::
+      #   The scoring function to invoke on a search result for this query. If
+      #   scorer is not set, scoring is disabled and +score+ is 0 for all
+      #   documents in the search result. To enable document relevancy score
+      #   based on term frequency, set +scorer+ to +:generic+.
+      #   (+String+ or +Symbol+)
+      # +scorer_size+::
+      #   Maximum number of top retrieved results to score. It is valid only
+      #   when +scorer+ is set. The default is 100. (+Integer+)
+      # +token+::
+      #   A previously-returned page token representing part of the larger set
+      #   of results to view. (+String+)
+      # +max+::
+      #   Maximum number of results to return per page. (+Integer+)
+      #
+      # === Returns
+      #
+      # Array of Gcloud::Search::Result (See Gcloud::Search::Result::List)
+      #
+      # === Examples
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   search = gcloud.search
+      #   index = search.index "books"
+      #
+      #   results = index.search "dark stormy"
+      #   results.each do |result|
+      #     puts result.doc_id
+      #   end
+      #
+      # If you have a significant number of search results, you may need to
+      # paginate through them: (See Gcloud::Search::Result::List)
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   search = gcloud.search
+      #   index = search.index "books"
+      #
+      #   results = index.results
+      #   loop do
+      #     results.each do |result|
+      #       puts result.doc_id
+      #     end
+      #     break unless results.next?
+      #     results = results.next
+      #   end
+      #
+      # By default, Result objects are sorted by document rank. For more information
+      # see the {REST API documentation for Document.rank}[https://cloud.google.com/search/reference/rest/v1/projects/indexes/documents#resource_representation.google.cloudsearch.v1.Document.rank].
+      #
+      # You can specify how to sort results with the +order+ option. In the example
+      # below, the <code>-</code> character before +avg_review+ means that results
+      # will be sorted in ascending order by +published+ and then in descending
+      # order by +avg_review+.
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   search = gcloud.search
+      #   index = search.index "books"
+      #
+      #   results = index.search "dark stormy", order: "published, avg_review desc"
+      #   documents = index.search query # API call
+      #
+      # You can add computed fields with the +expressions+ option, and limit the
+      # fields that are returned with the +fields+ option:
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   search = gcloud.search
+      #   index = search.index "products"
+      #
+      #   results = index.search "cotton T-shirt",
+      #                          expressions: { total_price: "(price + tax)" },
+      #                          fields: ["name", "total_price", "highlight"]
+      #
+      # Just as in documents, Result data is accessible via Fields methods:
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   search = gcloud.search
+      #   index = search.index "products"
+      #   document = index.find "product-sku-000001"
+      #   results = index.search "cotton T-shirt"
+      #   values = results[0]["description"]
+      #
+      #   values[0] #=> "100% organic cotton ruby gem T-shirt"
+      #   values[0].type #=> :text
+      #   values[0].lang #=> "en"
+      #   values[1] #=> "<p>100% organic cotton ruby gem T-shirt</p>"
+      #   values[1].type #=> :html
+      #   values[1].lang #=> "en"
+      #
+      def search query, expressions: nil, matched_count_accuracy: nil,
+                 offset: nil, order: nil, fields: nil, scorer: nil,
+                 scorer_size: nil, token: nil, max: nil
+        ensure_connection!
+        options = { expressions: format_expressions(expressions),
+                    matched_count_accuracy: matched_count_accuracy,
+                    offset: offset, order: order, fields: fields,
+                    scorer: scorer, scorer_size: scorer_size, token: token,
+                    max: max }
+        resp = connection.search index_id, query, options
+        if resp.success?
+          Result::List.from_response resp, self, query, options
+        else
+          fail ApiError.from_response(resp)
+        end
+      end
+
+      # rubocop:enable Metrics/LineLength
+
+      protected
+
+      ##
+      # Raise an error unless an active connection is available.
+      def ensure_connection!
+        fail "Must have active connection" unless connection
+      end
+
+      def format_expressions expressions
+        return nil if expressions.nil?
+        expressions.to_h.map { |k, v| { name: k, expression: v } }
+      end
+    end
+  end
+end