swiftype 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ec1df142277966dde94c63225c977056242a5d70
-  data.tar.gz: e4decec856f184b9c8d1ad9a5774bde8e90cdb04
+  metadata.gz: 54e1e3d18b1ef0d4ac96736071a83904c332fa62
+  data.tar.gz: 7c387aedb4ccca99caef021296dc6f9f2adad14f
 SHA512:
-  metadata.gz: 46250d369963f704a41c0911d228835e89696ffabdf3d0c60c4e81de1cb90e314202d844d58882f199aef34bd42cfed52cef1b4a904958891bbc0fec9bed2188
-  data.tar.gz: d36c10b224eed2d6281ab2073bc6c849d98659952015d7da9c18cb0952dd937f74f26a8e00c06b305a25c3c87c75d869279fd6f630adad9b1a237b6c3172e5a3
+  metadata.gz: 380b9b2cd117f33f243386e1b5dac701ceb460d6ffd4f5f898bdedd5717d77585f1049f07b396613ce18dbc5add22487f6444d07f062f069cceedce02e717576
+  data.tar.gz: ccf234d1156a1338b9c11f12c2e68b06fb7b0b58b94118c8c60c9fb80d67f5e994c7f138fdbc914ced223351c73e3945aa8d07559917ec7d382dc938fd258318

data/README.md

@@ -24,7 +24,7 @@ To install the gem, execute:
 
     gem install swiftype
 
-Or place `gem 'swiftype', '~> 1.0.1` in your `Gemfile` and run `bundle install`.
+Or place `gem 'swiftype', '~> 1.2.0` in your `Gemfile` and run `bundle install`.
 
 ## Usage
 
@@ -36,6 +36,10 @@ Before issuing commands to the API, configure the client with your API key:
 
 You can find your API key in your [Account Settings](https://swiftype.com/settings/account).
 
+If you're using Heroku, you can configure the client with the `SWIFTYPE_URL` configuration variable:
+
+    Swiftype.authenticated_url = ENV['SWIFTYPE_URL']
+
 ### Create a client
 
     client = Swiftype::Client.new
@@ -137,9 +141,11 @@ Retrieve a specific Document using its `id` or `external_id`:
 
     document = client.document('swiftype-api-example', 'videos', 'FHtvDA0W34I')
 
+To create or update. single or multiple documents, we use the method `index_documents`.
+
 Create a new Document with mandatory `external_id` and user-defined fields:
 
-    document = client.create_document('swiftype-api-example', 'videos', {
+    document = client.index_documents('swiftype-api-example', 'videos', {
         :external_id => 'FHtvDA0W34I',
         :fields => [
             {:name => 'title', :value => "Felix Baumgartner's supersonic freefall from 128k' - Mission Highlights", :type => 'string'},
@@ -149,7 +155,7 @@ Create a new Document with mandatory `external_id` and user-defined fields:
 
 Create multiple Documents at once and return status for each Document creation:
 
-    response = client.create_documents('swiftype-api-example', 'videos', [{
+    response = client.index_documents('swiftype-api-example', 'videos', [{
         :external_id => 'FHtvDA0W34I',
         :fields => [
             {:name => 'title', :value => "Felix Baumgartner's supersonic freefall from 128k' - Mission Highlights", :type => 'string'},
@@ -162,35 +168,50 @@ Create multiple Documents at once and return status for each Document creation:
             {:name => 'url', :value => 'http://www.youtube.com/watch?v='dMH0bHeiRNg', :type => 'enum'},
             {:name => 'chanel_id', :value => UC5B9H4l2vtgo7cAoExcFh-w', :type => 'enum'}
         ]}])
-        #=> [true, true]
 
 Update fields of an existing Document specified by `id` or `external_id`:
 
-    client.update_document('swiftype-api-example', 'videos', 'FHtvDA0W34I', {:title =>'New Title'})
+    client.index_documents('swiftype-api-example', 'videos', 'FHtvDA0W34I', {:title =>'New Title'})
 
 **NOTE:** A field must already exist on a Document in order to update it.
 
 Update multiple Documents at once:
 
-    response = client.update_documents('swiftype-api-example','videos', [
+    response = client.index_documents('swiftype-api-example','videos', [
         {:external_id => 'FHtvDA0W34I', :fields => {:view_count => 32874417}},
         {:external_id => 'dMH0bHeiRNg', :fields => {:view_count => 98323493}}
     ])
-        #=> [true, true]
-
-Create or update a Document:
 
-    document = client.create_or_update_document('swiftype-api-example', 'videos', {
-        :external_id => 'FHtvDA0W34I',
-        :fields => [
-            {:name => 'title', :value => "Felix Baumgartner's supersonic freefall from 128k' - Mission Highlights", :type => 'string'},
-            {:name => 'url', :value => 'http://www.youtube.com/watch?v=FHtvDA0W34I', :type => 'enum'},
-            {:name => 'chanel_id', :value => 'UCblfuW_4rakIf2h6aqANefA', :type => 'enum'}
-        ]})
-
-Create or update multiple `Documents` at once:
-
-    response = client.create_or_update_documents('swiftype-api-example', 'videos', [{
+All methods above will have a return in the following format:
+    
+    [
+      {
+        "id": "5473d6142ed96065a9000001",
+        "external_id": "FHtvDA0W34I",
+        "status": "complete",
+        "errors": [],
+        "links": {
+          "receipt": "https://api.swiftype.com/api/v1/document_receipts/5473d6142ed96065a9000001.json",
+          "document": "https://api.swiftype.com/api/v1/engine/xyz/document_type/abc/document/5473d6142ed96065a9000001.json"
+        }
+      },
+      {
+        "id": "5473d6142ed96065a9000002",
+        "external_id": "dMH0bHeiRNg",
+        "status": "complete",
+        "errors": [],
+        "links": {
+          "receipt": "https://api.swiftype.com/api/v1/document_receipts/5473d6142ed96065a9000001.json",
+          "document": "https://api.swiftype.com/api/v1/engine/xyz/document_type/abc/document/5473d6142ed96065a9000002.json"
+        }
+      }
+    ]
+
+**NOTE:** If you'd like to create or update documents asynchronously, simply pass the option `:async => true` as the last argument.
+
+For instance, to Create multiple Documents at once:
+
+    response = client.index_documents('swiftype-api-example', 'videos', [{
         :external_id => 'FHtvDA0W34I',
         :fields => [
             {:name => 'title', :value => "Felix Baumgartner's supersonic freefall from 128k' - Mission Highlights", :type => 'string'},
@@ -202,7 +223,59 @@ Create or update multiple `Documents` at once:
             {:name => 'title', :value => 'Evolution of Dance - By Judson Laipply', :type => 'string'},
             {:name => 'url', :value => 'http://www.youtube.com/watch?v='dMH0bHeiRNg', :type => 'enum'},
             {:name => 'chanel_id', :value => UC5B9H4l2vtgo7cAoExcFh-w', :type => 'enum'}
-        ]}])
+        ]}],
+        :async => true )
+        #=> {
+          "batch_link": "https://api.swiftype.com/api/v1/document_receipts.json?ids=5473d6142ed96065a9000001,5473d6142ed96065a9000002",
+          "document_receipts": [
+            {
+              "id": "5473d6142ed96065a9000001",
+              "external_id": "FHtvDA0W34I",
+              "status": "pending",
+              "errors": [],
+              "links": {
+                "receipt": "https://api.swiftype.com/api/v1/document_receipts/5473d6142ed96065a9000001.json",
+                "document": null
+              }
+            },
+            {
+              "id": "5473d6342ed96065a9000002",
+              "external_id": "dMH0bHeiRNg",
+              "status": "pending",
+              "errors": [],
+              "links": {
+                "receipt": "https://api.swiftype.com/api/v1/document_receipts/5473d6142ed96065a9000002.json",
+                "document": null
+              }
+            }
+          ]
+        }
+
+To check the status of documents with their document_receipt ids:
+
+    response = client.document_receipts(["5473d6142ed96065a9000001", "5473d6342ed96065a9000002"])
+    #=> [
+      {
+        "id": "5473d6142ed96065a9000001",
+        "external_id": "FHtvDA0W34I",
+        "status": "complete",
+        "errors": [],
+        "links": {
+          "receipt": "https://api.swiftype.com/api/v1/document_receipts/5473d6142ed96065a9000001.json",
+          "document": "https://api.swiftype.com/api/v1/engine/xyz/document_type/abc/document/5473d6142ed96065a9000001.json"
+        }
+      },
+      {
+        "id": "5473d6142ed96065a9000002",
+        "external_id": "dMH0bHeiRNg",
+        "status": "complete",
+        "errors": [],
+        "links": {
+          "receipt": "https://api.swiftype.com/api/v1/document_receipts/5473d6142ed96065a9000001.json",
+          "document": "https://api.swiftype.com/api/v1/engine/xyz/document_type/abc/document/5473d6142ed96065a9000002.json"
+        }
+      }
+    ]
 
 Destroy a Document by external_id:
 
@@ -291,7 +364,7 @@ swiftype-rb 1.0 has been rewritten to be simpler and easier to use. However, it
 
 To upgrade from the old version of swiftype-rb:
 
-* If you previously used the `Swiftype` client, migrate your API calls to the `Swiftype::Client` format. 
+* If you previously used the `Swiftype` client, migrate your API calls to the `Swiftype::Client` format.
 * If you previously used the `Swiftype::Easy` client, change `Swiftype::Easy` to `Swiftype::Client`. Almost all method calls should be the same (there are a few minor changes).
 
 Additionally, the result object returned by search methods (for example, the old Swiftype gem's `Engine#search` or `Swiftype::Easy#search` methods) returns results in a different way. Instead of being an array of `Swiftype::Document` objects, it will be an array of Hashes.

data/lib/swiftype/client.rb

@@ -14,9 +14,12 @@ module Swiftype
 
     # Create a new Swiftype::Client client
     #
-    # @param options [Hash] a hash of configuration options that will overrided what is set on the Swiftype class.
+    # @param options [Hash] a hash of configuration options that will override what is set on the Swiftype class.
     # @option options [String] :api_key an API Key to use for this client
     # @option options [String] :platform_access_token a user's access token, will be used instead of API key for authenticating requests
+    # @option options [Fixnum] :open_timeout the number of seconds Net::HTTP
+    #   will wait while opening a connection before raising a Timeout::Error
+
     def initialize(options={})
       @options = options
     end
@@ -29,6 +32,10 @@ module Swiftype
       @options[:platform_access_token]
     end
 
+    def open_timeout
+      @options[:open_timeout]
+    end
+
     # Methods wrapping the Swiftype private search and API endpoints. Using these methods, you can perform full-text
     # and prefix searches over the Documents in your Engine, in a specific DocumentType, or any subset of DocumentTypes.
     # You can also filter results and get faceted counts for results.
@@ -312,6 +319,51 @@ module Swiftype
       def update_documents(engine_id, document_type_id, documents={})
         put("engines/#{engine_id}/document_types/#{document_type_id}/documents/bulk_update.json", { :documents => documents })
       end
+
+      def async_create_or_update_documents(engine_id, document_type_id, documents=[])
+        post("engines/#{engine_id}/document_types/#{document_type_id}/documents/async_bulk_create_or_update.json", :documents => documents)
+      end
+
+      # Retrieve Document Receipts from the API by ID
+      #
+      # @param [Array<String>] receipt_ids an Array of Document Receipt IDs
+      #
+      # @return [Array<Hash>] an Array of Document Receipt hashes
+      def document_receipts(receipt_ids)
+        post("document_receipts.json", :ids => receipt_ids)
+      end
+
+      # Index a batch of documents using the {asynchronous API}[https://swiftype.com/documentation/asynchronous_indexing].
+      # This is a good choice if you have a large number of documents.
+      #
+      # @param [String] engine_id the Engine slug or ID
+      # @param [String] document_type_id the Document Type slug or ID
+      # @param [Array] documents an Array of Document Hashes
+      # @param [Hash] options additional options
+      # @option options [Boolean] :async (false) When true, output is document receipts created. When false, poll until all receipts are no longer pending or timeout is reached.
+      # @option options [Numeric] :timeout (10) Number of seconds to wait before raising an exception
+      #
+      # @return [Array<Hash>] an Array of newly-created Document Receipt hashes if used in :async => true mode
+      # @return [Array<Hash>] an Array of processed Document Receipt hashes if used in :async => false mode
+      #
+      # @raise [Timeout::Error] when used in :async => false mode and the timeout expires
+      def index_documents(engine_id, document_type_id, documents = [], options = {})
+        documents = Array(documents)
+
+        res = async_create_or_update_documents(engine_id, document_type_id, documents)
+
+        if options[:async]
+          res
+        else
+          receipt_ids = res["document_receipts"].map { |a| a["id"] }
+
+          poll(options) do
+            receipts = document_receipts(receipt_ids)
+            flag = receipts.all? { |a| a["status"] != "pending" }
+            flag ? receipts : false
+          end
+        end
+      end
     end
 
     # The analytics API provides a way to export analytics data similar to what is found in the Swiftype Dashboard.

data/lib/swiftype/request.rb

@@ -26,11 +26,35 @@ module Swiftype
       request(:delete, path, params)
     end
 
+    # Poll a block with backoff until a timeout is reached.
+    #
+    # @param [Hash] options optional arguments
+    # @option options [Numeric] :timeout (10) Number of seconds to wait before timing out
+    #
+    # @yieldreturn a truthy value to return from poll
+    # @yieldreturn [false] to continue polling.
+    #
+    # @return the truthy value returned from the block.
+    #
+    # @raise [Timeout::Error] when the timeout expires
+    def poll(options={})
+      timeout = options[:timeout] || 10
+      delay = 0.05
+      Timeout.timeout(timeout) do
+        while true
+          res = yield
+          return res if res
+          sleep delay *= 2
+        end
+      end
+    end
+
     def request(method, path, params={})
       uri = URI.parse("#{Swiftype.endpoint}#{path}")
 
       request = build_request(method, uri, params)
       http = Net::HTTP.new(uri.host, uri.port)
+      http.open_timeout = @options[:open_timeout]
 
       if uri.scheme == 'https'
         http.use_ssl = true

data/lib/swiftype/version.rb

@@ -1,3 +1,3 @@
 module Swiftype
-  VERSION = "1.1.0"
+  VERSION = "1.2.0"
 end