swiftype 0.0.5 → 1.0.0

data/.gitignore

@@ -3,3 +3,8 @@
 Gemfile.lock
 pkg/*
 .DS_Store
+.rvmrc
+.ruby-version
+.ruby-gemset
+.yardoc
+doc

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+script: rspec spec/platform_spec.rb
+rvm:
+  - 1.8.7
+  - 1.9.3
+  - 2.0.0

data/Gemfile

@@ -1,4 +1,4 @@
-source "http://rubygems.org"
+source "https://rubygems.org"
 
 # Specify your gem's dependencies in swiftype-rb.gemspec
 gemspec

data/README.md

@@ -1,419 +1,338 @@
-Swiftype Ruby Client (beta)
-===
+# Swiftype Ruby API Client
 
-The official [Swiftype](http://swiftype.com) Ruby client for communicating with the Swiftype API. Learn more about Swiftype by visiting [swiftype.com](http://swiftype.com) and creating an account.
+[![Build Status](https://travis-ci.org/swiftype/swiftype-rb.png?branch=easy)](https://travis-ci.org/swiftype/swiftype-rb)
 
+This is a simple client for the [Swiftype API](https://swiftype.com/documentation/overview) with no dependencies outside core Ruby (for 1.9 and 2.0; Ruby 1.8 requires the JSON gem).
 
-Prerequisites
----
-1. A Swiftype account. Sign up at [swiftype.com](http://swiftype.com).
-2. A compatible Ruby environment.
+## Getting Started
 
+Before beginning with the Swiftype gem, you should be familar with the concepts behind the Swiftype API: **Engines**, **DocumentTypes**, and **Documents**.
 
-Installation
----
+An **Engine** is a search engine. It can contain one or more **DocumentTypes** which are collections of **Documents**. A **Document** is a collection of fields that can be queried using the Swiftype API. Documents have a special **external_id** field that ties a Document in Swiftype to a record in your system. The layout of fields of the Documents belonging to a DocumentType is called a **schema**. Fields may be strings, integers, geographic locations, and so forth.
 
-To install the gem, execute:
-
-        gem install swiftype
-
-Or place `gem 'swiftype'` in your `Gemfile` and run `bundle install`.
-
-To use the GitHub version, you may add this to your Gemfile:
+The Documents in your Engine can be searched two ways: **full-text** (`search`) or **autocomplete** (`suggest`). The difference is that autocomplete queries work on prefixes (for example, "gla" will match "glass"). This is less accurage in general, but is useful for implementing type-ahead search drop downs.
 
-	gem 'swiftype', :git => "https://github.com/swiftype/swiftype-rb.git"
+You can think of an Engine as a database, DocumentTypes as tables, and Documents as rows. Using the API, you can search an engine for all Documents containing a word. You can also search an individual DocumentType, or any subset of DocumentTypes.
 
-Overview
----
+The examples in this documentation use the schema defined in the [swiftype-api-example](https://github.com/swiftype/swiftype-api-example) project, which is based on YouTube. It has two DocumentTypes, **videos** and **channels**. Using the script found in the swiftype-api-example project, you can create your own search engine that matches the examples and try the queries for yourself.
 
-The client has a few basic methods on `Swiftype` for dealing with `Engines`.  Beyond that, you can perform standard (CRUD) operations on any of the resources.
+To learn more about the Swiftype API, read the [API overview](https://swiftype.com/documentation/overview) and our [schema design tutorial](https://swiftype.com/documentation/tutorials/schema_design).
 
-### Resources
+## Installation
 
-#### Engine
+To install the gem, execute:
 
-`Engines` are the top-level objects in Swiftype.  They have a free-form `name` field that is translated into a `slug` identifier.
+    gem install swiftype
 
-#### Document Type
+Or place `gem 'swiftype', '~> 1.0.0` in your `Gemfile` and run `bundle install`.
 
-`DocumentTypes` specify the structure of a set of documents in the `Engine` and are the entry point for searches.  There are three types of fields on a `DocumentType`: `:string`, `:text`, `:enum`, `:integer`, `:float`, and `:date`.
+## Usage
 
-`:string` is for short strings that can be matched in both prefix and full-text searches.  _Example: Chapter titles in a book._
+### Configuration:
 
-`:text` can be long strings.  They are meant for full-text searches only and will not be used for prefix queries.  _Example: Entire text of an essay._
+Before issuing commands to the API, configure the client with your API key:
 
-`:enum` are string traits of a document.  They are not analyzed in any way, and thus can be used to filter and sort queries.  _Example: Hardcover or paperback._
+    Swiftype.api_key = 'YOUR_API_KEY'
 
-`:date` are ISO 8601 compatible time strings.  They can also be used to filter and sort queries.
+You can find your API key in your [Account Settings](https://swiftype.com/settings/account).
 
+### Create a client
 
+    client = Swiftype::Client.new
 
-#### Document
+You can also provide the API key when creating the client instance:
 
-`Documents` represent all of the pieces of content in an `Engine`.  They are children of a `DocumentType` and conform to its field specification (note: you do *not* need to specify the fields ahead of time, they will be inferred by the contents of a document).  When you perform a search on a `DocumentType`, you will receive `Document` results.  `external_id` is the only required field for a `Document`. It can be any value, such as a numeric ID.
+    client = Swiftype::Client.new(:api_key => 'different_api_key')
 
+If the API key is provided as an option to constructor, it will override the globally configured Swiftype API key (if any).
 
+### Full-text search
 
-Basic Usage
-===
+If you want to search for `cat` on your engine, you can use:
 
-Configuration:
----
+    results = client.search('swiftype-api-example', 'cat')
+    results['videos']   # => [{'external_id' => 'QH2-TGUlwu4', 'title' => 'Nyan Cat [original]', ... }, ... ]
+    results['channels'] # => [{'external_id' => 'UC3VHfy8e1jbDnT5TG2pjP1w', 'title' => 'saraj00n', ... }, ... ]
 
-Before issuing commands to the API, configure the client with your API key:
+To limit the search to only the `videos` DocumentType:
 
-```ruby
-Swiftype.configure do |config|
-  config.api_key = 'YOUR_API_KEY'
-end
-```
+    results = client.search_document_type('swiftype-api-example', 'videos', 'cat')
+    results['videos']   # => [{'external_id' => 'QH2-TGUlwu4', 'title' => 'Nyan Cat [original]', ... }, ... ]
+    results['channels'] # => nil
 
-Indexing:
----
+Both search methods allow you to specify options to filter or sort on fields, boost the weight of certain fields, calculate faceted counts, and so on. For more details on these options, review the [Search Options](https://swiftype.com/documentation/searching).
 
-#### Engines:
+Here is an example for showing only videos in the "Pets & Animals" category (which has ID 23):
 
-Search engines are the top-level container for the objects you wish to search, and most sites will have a single engine. The engines themselves contain one or more document types, each of which contain the documents themselves.
+    results = client.search_document_type('swiftype-api-example', 'videos', 'cat', {:filters => {'videos' => {:category_id => '23'}}})
 
-Create a search engine:
+### Autocomplete search
 
-	engine = Swiftype::Engine.new(:name => 'bookstore')
-	engine.create!
+Autocomplete (also known as suggest, prefix, or type-ahead) searches can be used to implement autocompletion. They have the same functionality as full-text searches, but work on prefixes instead of all the text. Because of this, autocomplete queries only search string fields.
 
-Get a search engine:
+You can perform a suggest query across all of your Engine's Documents:
 
-	Swiftype::Engine.find('bookstore')
+    results = client.suggest("swiftype-api-example", "gla")
+    results['videos'] # => [{'external_id' => 'v1uyQZNg2vE', 'title' => 'How It Feels [through Glass]', ...}, ...]
 
-Delete a search engine:
+or just for one DocumentType:
 
-	engine = Swiftype::Engine.find('bookstore')
-	engine.destroy!
+    results = client.suggest_document_type("swiftype-api-example", "videos", "gla")
+    results['videos'] # => [{'external_id' => 'v1uyQZNg2vE', 'title' => 'How It Feels [through Glass]', ...}, ...]
 
+or add options to have more control over the results:
 
-#### Document Types
+    results = client.suggest('swiftype-api-example', 'glass', {:sort_field => {'videos' => 'view_count'}, :sort_direction => {'videos' => 'desc'}})
 
-Create a `document_type`:
+### Engines
 
-	engine = Swiftype::Engine.find('bookstore')
-	type = engine.create_document_type(:name => 'books')
+Retrieve every Engine:
 
-Get a `document_type`:
+    engines = client.engines
 
-	engine = Swiftype::Engine.find('bookstore')
-	type = engine.document_type('books')
+Create a new Engine with the name `swiftype-api-example`:
 
-Delete a `document_type`. Deleting a `document_type` will also delete every `document` contained within it:
+    engine = client.create_engine('swiftype-api-example')
 
-	engine = Swiftype::Engine.find('bookstore')
-	engine.destroy_document_type('books')
+Retrieve an Engine by `slug` or `id`:
 
-or, alternatively, call destroy on the `document_type` itself:
+    engine = client.engine('swiftype-api-example')
+    engine = client.engine('5230b9102ed960ba20000021')
 
-	engine = Swiftype::Engine.find('bookstore')
-	type = engine.document_type('books')
-	type.destroy!
+Delete an Engine by `slug` or the `id`:
 
+    client.destroy_engine('swiftype-api-example')
 
-#### Documents
+### Document Types
 
-Create a `document`:
+List all the
 
-	engine = Swiftype::Engine.find('bookstore')
-	type = engine.document_type('books')
-	type.create_document({
-		:external_id => '1',
-		:fields => [
-			{:name => 'title', :value => 'Information Retrieval', :type => 'string'},
-			{:name => 'genre', :value => 'non-fiction', :type => 'enum'},
-			{:name => 'author', :value => 'Stefan Buttcher', :type => 'string'},
-			{:name => 'in_stock', :value => true, :type => 'enum'},
-			{:name => 'on_sale', :value => false, :type => 'enum'}
-		]});
+Retrieve `DocumentTypes`s of the Engine with the `slug` field `swiftype-api-example`:
 
-Get a `document`:
+    document_types = client.document_types('swiftype-api-example')
 
-	engine = Swiftype::Engine.find('bookstore')
-	type = engine.document_type('books')
-	doc = type.document('1')
+Show the second batch of documents:
 
-Get every `document` within a `document_type`:
+    document_types = client.document_types('swiftype-api-example', 2)
 
-	engine = Swiftype::Engine.find('bookstore')
-	type = engine.document_type('books')
-	type.documents
+Create a new DocumentType for an Engine with the name `videos`:
 
-Update field(s) of a `document`:
+    document_type = client.create_document_type('swiftype-api-example', 'videos')
 
-	engine = Swiftype::Engine.find('bookstore')
-	type = engine.document_type('books')
-	doc = type.document('1')
-	doc.update_fields!({:in_stock => false })
+Retrieve an DocumentType by `slug` or `id`:
 
-or, alternatively, update a `document` without retrieving it first:
+    document_type = client.document_type('swiftype-api-example', 'videos')
 
-	engine = Swiftype::Engine.find('bookstore')
-	type = engine.document_type('books')
-	type.update_document(:external_id => '1', :fields => { :in_stock => false })
+Delete a DocumentType using the `slug` or `id` of it:
 
-you can also update multiple fields in the same call:
+    client.destroy_document_type('swiftype-api-example', 'videos')
 
-	doc.update_fields({:in_stock => false, :on_sale => true })
+### Documents
 
-Delete a `document`:
+Retrieve the first page of Documents of Engine `swiftype-api-example` and DocumentType `videos`:
 
-	engine = Swiftype::Engine.find('bookstore')
-	type = engine.document_type('books')
-	doc = type.document('1')
-	doc.destroy!
+    documents = client.documents('swiftype-api-example', 'videos')
 
-or, alternatively, delete a `document` without retrieving it first:
+Retrieve a specific Document using its `id` or `external_id`:
 
-	engine = Swiftype::Engine.find('bookstore')
-	type = engine.document_type('books')
-	type.destroy_document('1')
+    document = client.document('swiftype-api-example', 'videos', 'FHtvDA0W34I')
 
+Create a new Document with mandatory `external_id` and user-defined fields:
 
-#### Bulk Operations
+    document = client.create_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'}
+        ]})
 
-Bulk operations will allow you to perform rapid indexing updates and avoid the latency overhead of making repeated requests.
+Create multiple Documents at once and return status for each Document creation:
 
-Create `document`s in bulk:
+    response = client.create_documents('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'}
+        ]}, {
+        :external_id => 'dMH0bHeiRNg',
+        :fields => [
+            {: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'}
+        ]}])
+        #=> [true, true]
 
-	engine = Swiftype::Engine.find('bookstore')
-	type = engine.document_type('books')
-	type.create_documents([{
-		:external_id => '2',
-		:fields => [
-			{:name => 'title', :value => 'Lucene in Action', :type => 'string'},
-			{:name => 'genre', :value => 'non-fiction', :type => 'enum'},
-			{:name => 'author', :value => 'Michael McCandless', :type => 'string'},
-			{:name => 'in_stock', :value => true, :type => 'enum'},
-			{:name => 'on_sale', :value => false, :type => 'enum'}
-		]},{
-		:external_id => '3',
-		:fields => [
-			{:name => 'title', :value => 'MongoDB in Action', :type => 'string'},
-			{:name => 'genre', :value => 'non-fiction', :type => 'enum'},
-			{:name => 'author', :value => 'Kyle Banker', :type => 'string'},
-			{:name => 'in_stock', :value => true, :type => 'enum'},
-			{:name => 'on_sale', :value => false, :type => 'enum'}
-		]},{
-		:external_id => '4',
-		:fields => [
-			{:name => 'title', :value => 'The Great Gatsby', :type => 'string'},
-			{:name => 'genre', :value => 'fiction', :type => 'enum'},
-			{:name => 'author', :value => 'F. Scott Fitzgerald', :type => 'string'},
-			{:name => 'in_stock', :value => true, :type => 'enum'},
-			{:name => 'on_sale', :value => false, :type => 'enum'}
-		]}
-	])
+Update fields of an existing Document specified by `id` or `external_id`:
 
-Update `document`s in bulk:
+    client.update_document('swiftype-api-example', 'videos', 'FHtvDA0W34I', {:title =>'New Title'})
 
-	engine = Swiftype::Engine.find('bookstore')
-	type = engine.document_type('books')
-	type.update_documents([
-		{:external_id => '2', :fields => {:in_stock => false, :on_sale => 'false'}},
-	 	{:external_id => '3', :fields => {:in_stock => false, :on_sale => 'false'}}
-	])
+**NOTE:** A field must already exist on a Document in order to update it.
 
-Delete `document`s in bulk:
+Update multiple Documents at once:
 
-	engine = Swiftype::Engine.find('bookstore')
-	type = engine.document_type('books')
-	type.destroy_documents(['1','2','3','4'])
+    response = client.update_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:
 
-Searching:
----
+    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'}
+        ]})
 
-#### Full text search
+Create or update multiple `Documents` at once:
 
-Search a `document_type` for the query "lucene":
+    response = client.create_or_update_documents('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'}
+        ]}, {
+        :external_id => 'dMH0bHeiRNg',
+        :fields => [
+            {: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'}
+        ]}])
 
-	engine = Swiftype::Engine.find('bookstore')
-	type = engine.document_type('books')
-	results = type.search("lucene")
+Destroy a Document by external_id:
 
-Searches return a `ResultSet` object from which you retrieve the results. Results are grouped by their `DocumentType`, so you retrieve the results for a specific `DocumentType` as follows:
+    client.destroy_document('swiftype-api-example','videos','dFs9WO2B8uI')
 
-	resultset = type.search('lucene')
-	book_results = resultset['books']
-	book_results.each do |book|
-		puts book.title
-		puts book.author
-		puts book.genre
-	end
+Destroy multiple Documents at once:
 
-The `ResultSet` object also contains meta data for the search, such as pagination and facets if the user has specified them.
+    response = client.destroy_documents('swiftype-api-example', 'videos', ['QH2-TGUlwu4, 'v1uyQZNg2vE', 'ik5sdwYZ01Q'])
+    #=> [true, true, true]
 
-#### Pagination
+### Domains
 
-To get pagination information from a `ResultSet`, you call the `num_pages`, `current_page`, and `per_page` methods. For example:
+**Domains** are a feature of crawler-based engines that represent a web site to index with the Swiftype web crawler.
 
-	resultset = type.search('lucene')
-	puts "Current page of results: #{resultset.current_page}"
-	puts "Total pages in this result set: #{resultset.num_pages}"
-	puts "Number of results per page: #{resultset.per_page}"
+Retrieve all Domains of Engine `websites`:
 
-#### Search Options
+    domains = client.domains('websites')
+    #=> [{"id"=>"513fcc042ed960c186000001", "engine_id"=>"513fcc042ed960114400000d", "submitted_url"=>"http://example.com/", "start_crawl_url"=>"http://www.example.com/", "crawling"=>false, "document_count"=>337, "updated_at"=>"2013-03-13T00:48:32Z"}, ...]
 
-You can pass the following options to the search method: `page`, `per_page`, `fetch_fields`, `search_fields`, `filters`, and `facets`.
+Retrieve a specific Domain by `id`:
 
-* `page` should be an integer of the page of results you want
-* `per_page` should be an integer of the number of results you want from each page
-* `fetch_fields` is a hash containing arrays of the fields you want to have returned for each object of each  document_type
-* `search_fields` is a hash containing arrays of the fields you want to match your query against for each object of each document_type
-* `functional_boosts` is a hash containing boosts that are to be applied to numerically valued fields
-* `filters` is a hash specifying additional conditions that should be applied to your query for each document_type
-* `facets` is a hash specifying fields for faceted counts for each document type
+    domain = client.domain('websites', '513fcc042ed960c186000001'')
+    #=> {"id"=>"513fcc042ed960c186000001", "engine_id"=>"513fcc042ed960114400000d", "submitted_url"=>"http://example.com/", "start_crawl_url"=>"http://www.example.com/", "crawling"=>false, "document_count"=>337, "updated_at"=>"2013-03-13T00:48:32Z"}
 
-An example of using search options is as follows:
+Create a new Domain with the URL `https://swiftype.com` and start crawling:
 
-	resultset = type.search('lucene', :filters => { :books => { :in_stock => false, :genre => 'fiction' }}, :per_page => 10, :page => 2, :fetch_fields => {:books => ['title','genre']}, :search_fields => {:books => ['title']})
+    domain = client.create_domain('websites', 'https://swiftype.com')
 
-Filters also support datetime range queries. For example, to return only those books with an `updated_at` field between `2012-02-16` and now, use the following filter:
+Delete a Domain using its `id`:
 
-	resultset = type.search('lucene', :filters => { :books => { :updated_at => '[2012-02-16 TO *]' }})
+    client.destroy_domain('websites', '513fcc042ed960c186000001')
 
-See the (Swiftype Documentation)[http://swiftype.com/documentation/searching] for more details and examples of search options.
+Initiate a recrawl of a specific Domain using its `id`:
 
+    client.recrawl_domain('websites', '513fcc042ed960c186000001')
 
-##### Functional Boosts
+Add or update a URL for a Domain:
 
-Functional boosts allow you to boost result scores based on some numerically valued field. For example, you might want your search engine to return the most popular books first, so you would boost results on the `total_purchases` field, which contains an `integer` of the total number of purchases of that book:
+    client.crawl_url('websites', '513fcc042ed960c186000001', 'https://swiftype.com/new/path.html')
 
-	resultset = type.search('lucene', :functional_boosts => { :books => { :total_purchases => 'logarithmic' }})
+### Analytics
 
-There are 3 types of functional boosts:
+Swiftype records the number of searches, autoselects (when a user clicks a link from a suggest result), and clickthroughs (when a user clicks through to an item from a search result list. You can view this information in your Swiftype Dashboard, but you can also export it using the API.
 
-* `logarithmic` - multiplies the original score by log(numeric_value)
-* `exponential` - multiplies the original score by exp(numeric_value)
-* `linear` - multiplies the original score numeric_value
+To get the number of searches per day from an Engine in the last 14 days:
 
-Functional boosts may be applied to `integer` and `float` valued fields.
+    searches = client.analytics_searches('swiftype-api-example')
+    #=> [['2013-09-13', '123'], [2013-09-12', '94'], ... ]
 
-##### Facets
+You can also use a specific start and/or end date:
 
-You may get facets for your search results by passing the facets option when you search. For example, to get aggregate counts for the number of results in each genre, use the following:
+    searches = client.analytics_searches('swiftype-api-example', '2013-01-01', '2013-01-07')
 
-	resultset = type.search('lucene', :facets => { :books => ['genre']})
+To get the number of autoselects in the past 14 days:
 
-You can retrieve the facet counts from the `ResultSet` as follows:
+    autoselects = client.analytics_autoselects('swiftype-api-example')
 
-	resultset = type.search('lucene', :facets => { :books => ['genre']})
-	resultset.facets('books')
-	=> {"genre"=>{"fiction"=>5, "non-fiction"=>2, "political"=>1, "fantasy"=>1}}
+As with searches you can also limit by start and/or end date:
 
-#### Autocomplete
+    autoselects = client.analytics_autoselects('swiftype-api-example', '2013-01-01', '2013-01-07')
 
-Get autocomplete suggestions from a `document_type` for the prefix "act"
+If you are interested in the top queries for your Engine you can use:
 
-	engine = Swiftype::Engine.find('bookstore')
-	type = engine.document_type('books')
-	results = type.suggest("act")
+    top_queries = client.analytics_top_queries('swiftype-api-example')
+    # => [['query term', 123], ['another query', 121], ['yet another query', 92], ...]
 
-The suggest method also accepts the same options specified for the search method above.
+To see more top queries you can paginate through them using:
 
+    top_queries = client.analytics_top_queries('swiftype-api-example', {:page => 2})
 
-Simple Client:
-===
-The Simple Client is a convenience class that gives you basic, direct access to the Swiftype REST API, without mapping each call to the intermediate objects seen in the examples above. These methods will be more performant, because they avoid unnecessary round-trips to the server, but you will also have to provide more information to each call. Choose whatever suites your use-case.
+Or you can get the top queries in a specific date range:
 
-#### Create a Simple Client
+    top_queries = client.analytics_top_queries('swiftype-api-example', {:start_date => '2013-01-01', :end_date => '2013-01-07'})
 
-	client = Swiftype::Easy.new
+If you want to improve you search results, you should always have a look at search queries, that return no results and perhaps add some Documents that match for this query or use our pining feature to add Documents for this query:
 
-#### Search
+    top_no_result_queries = client.analytics_top_no_result_queries('swiftype-api-example')
 
-	results = client.search('bookstore',{SEARCH QUERY} [, OPTIONAL SEARCH OPTIONS])
+You can also specifiy a date range for queries without results:
 
-#### Autocomplete
+    top_no_result_queries = client.analytics_top_no_result_queries('swiftype-api-example', {:start_date => '2013-01-01', :end_date => '2013-01-07'})
 
-	results = client.suggest('bookstore',{AUTOCOMPLETE PREFIX QUERY} [, OPTIONAL SEARCH OPTIONS])
+## Migrating from previous versions
 
-#### Engines
+swiftype-rb 1.0.0 has been rewritten to be simpler and easier to use. However, it is not compatable with the previous version, 0.0.5.
 
-	client.engines # retrieves every engine
-	client.create_engine(:name => 'bookstore')
-	client.destroy_engine('bookstore')
+To upgrade from the old version of swiftype-rb:
 
-#### Document Types
+* 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).
 
-	client.document_types('bookstore')
-	client.create_document_type('bookstore', :name => 'books')
-	client.destroy_document_type('bookstore', 'books')
+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.
 
-#### Documents
+Code like this:
 
-	# retrieve all documents
-	client.documents('bookstore', 'books')
+    client = Swiftype::Easy.new
+    results = client.search("engine_slug", "search term")
+    results.each do |result|
+      puts result.title
+    end
 
-	# create a document
-	client.create_document('bookstore', 'books', {
-		:external_id => '1',
-		:fields => [
-			{:name => 'title', :value => 'Information Retrieval', :type => 'string'},
-			{:name => 'genre', :value => 'non-fiction', :type => 'enum'},
-			{:name => 'author', :value => 'Stefan Buttcher', :type => 'string'},
-			{:name => 'in_stock', :value => true, :type => 'enum'},
-			{:name => 'on_sale', :value => false, :type => 'enum'}
-		]})
+Should be changed to this:
 
-	# create documents in bulk
-	client.create_documents('bookstore', 'books', [{
-		:external_id => '2',
-		:fields => [
-			{:name => 'title', :value => 'Lucene in Action', :type => 'string'},
-			{:name => 'genre', :value => 'non-fiction', :type => 'enum'},
-			{:name => 'author', :value => 'Michael McCandless', :type => 'string'},
-			{:name => 'in_stock', :value => true, :type => 'enum'},
-			{:name => 'on_sale', :value => false, :type => 'enum'}
-		]},{
-		:external_id => '3',
-		:fields => [
-			{:name => 'title', :value => 'MongoDB in Action', :type => 'string'},
-			{:name => 'genre', :value => 'non-fiction', :type => 'enum'},
-			{:name => 'author', :value => 'Kyle Banker', :type => 'string'},
-			{:name => 'in_stock', :value => true, :type => 'enum'},
-			{:name => 'on_sale', :value => false, :type => 'enum'}
-		]}])
+    client = Swiftype::Client.new
+    results = client.search("engine_slug", "search term")
+    results.each do |result|
+      puts result['title']
+    end
 
-	# update a document
-	client.update_document('bookstore','books','1', { :in_stock => false })
+If you are not able to upgrade, lock your gem version to 0.0.5 by adding this to your Gemfile:
 
-	# update documents in bulk
-	client.update_documents('bookstore','books', [
-		{:external_id => '2', :fields => {:in_stock => false}},
-		{:external_id => '3', :fields => {:in_stock => true}}
-	])
+    gem 'swiftype, '= 0.0.5'
 
-	# create or update a document
-	client.create_or_update_document('bookstore', 'books', {
-		:external_id => '1',
-		:fields => [
-			{:name => 'title', :value => 'Information Retrieval', :type => 'string'},
-			{:name => 'genre', :value => 'non-fiction', :type => 'enum'},
-			{:name => 'author', :value => 'Stefan Buttcher', :type => 'string'},
-			{:name => 'in_stock', :value => false, :type => 'enum'},
-			{:name => 'on_sale', :value => true, :type => 'enum'}
-		]})
+To upgrade from the beta swiftype-easy-rb library (which was the precursor of swiftype-rb 1.0), change `Swiftype::Easy` to `Swiftype::Client` and move your configuration from the `Swiftype::Easy` module to the `Swiftype` module. For example:
 
-	# destroy a document
-	client.destroy_document('bookstore','books','1')
+    Swiftype:Easy.configure do |configure|
+      config.api_key = 'your_api_key'
+    end
 
-	# destroy documents in bulk
-	client.destroy_documents('bookstore','books',['1','2','3'])
+can be converted to
 
+    Swiftype.configure do |config|
+      config.api_key = 'your_api_key'
+    end
 
-Todo
-===
+or simply `Swiftype.api_key = 'your_api_key'`.
 
-+ Tests!
+## Development
 
+You can run tests with `rspec`. All HTTP interactions are stubbed out using VCR.
 
-Questions?
-===
-Get in touch! We would be happy to help you get up and running.
+To contribute code to this gem, please fork the repository and submit a pull request.
 
-[Quin](mailto:quin@swiftype.com) and [Matt](mailto:matt@swiftype.com) from [Swiftype](http://swiftype.com)