Module: Swiftype::Client::Search

Included in:
Swiftype::Client
Defined in:
lib/swiftype/client.rb

Overview

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.

For more information, visit the REST API documentation on searching.

Instance Method Summary collapse

Instance Method Details

#search(engine_id, query, options = {}) ⇒ Swiftype::ResultSet

Perform a full-text search over all the DocumentTypes of the provided engine.

results = client.search("swiftype-api-example", "glass")
results['videos'] # => [{'external_id' => 'v1uyQZNg2vE', 'title' => 'How It Feels [through Glass]', ...}, ...]

Parameters:

  • engine_id (String) —

    the Engine slug or ID

  • query (String) —

    the search terms (may be nil)

  • options (Hash) (defaults to: {}) —

    search options (see the REST API docs for a complete list)

Options Hash (options):

  • :page (Integer) —

    page number of results to fetch (server defaults to 1)

  • :per_page (Integer) —

    number of results per page (server defaults to 20)

  • :document_types (Array) —

    an array of DocumentType slugs to search. The server defaults to searching all DocumentTypes in the engine. To search a single document type, the search_document_type method is more convenient.

  • :fetch_fields (Hash) —

    a Hash of DocumentType slug to array of the fields to return with results (example: {'videos' => ['title', 'channel_id']})

  • :search_fields (Hash) —

    a Hash of DocumentType slug to array of the fields to search. May contain field weight boosts (example: {'videos' => ['title^5', 'tags^2', 'caption']}). The server defaults to searching all string and text fields for search queries.

  • :filters (Hash) —

    a Hash of DocumentType slug to filter definition Hash. See filters in the REST API documentation for more details (example: {'videos' => {'category_id' => ['23', '25']}})

  • :functional_boosts (Hash) —

    a Hash of DocumentType slug to functional boost definition (example: {'videos' => {'view_count' => 'logarithmic'}}).

  • :facets (Hash) —

    a Hash of DocumentType slug to an Array of field names to provide facetted counts for (example: {'videos' => ['category_id', 'channel_id']})

  • :sort_field (Hash) —

    a Hash of DocumentType slug to field name to sort on (example: {'videos' => 'view_count'})

  • :sort_direction (Hash) —

    a Hash of DocumentType slug to direction to sort (example: 'videos' => 'desc'). Usually used with :sort_field.

Returns:



109
110
111
112
113
 
# File 'lib/swiftype/client.rb', line 109

def search(engine_id, query, options={})
  search_params = { :q => query }.merge(options)
  response = post("engines/#{engine_id}/search.json", search_params)
  ResultSet.new(response)
end

#search_document_type(engine_id, document_type_id, query, options = {}) ⇒ Swiftype::ResultSet

Perform a full-text search over a single DocumentType in an Engine.

results = client.search_document_type("swiftype-api-example", "videos", "glass")
results['videos'] # => [{'external_id' => 'v1uyQZNg2vE', 'title' => 'How It Feels [through Glass]', ...}, ...]

Parameters:

  • engine_id (String) —

    the Engine slug or ID

  • document_type_id (String) —

    the DocumentType slug or ID

  • query (String) —

    the search terms (may be nil)

  • options (Hash) (defaults to: {}) —

    search options (see the REST API docs for a complete list)

Options Hash (options):

  • :page (Integer) —

    page number of results to fetch (server defaults to 1)

  • :per_page (Integer) —

    number of results per page (server defaults to 20)

  • :fetch_fields (Hash) —

    a Hash of DocumentType slug to array of the fields to return with results (example: {'videos' => ['title', 'channel_id']})

  • :search_fields (Hash) —

    a Hash of DocumentType slug to array of the fields to search. May contain field weight boosts (example: {'videos' => ['title^5', 'tags^2', 'caption']}). The server defaults to searching all string and text fields for search queries.

  • :filters (Hash) —

    a Hash of DocumentType slug to filter definition Hash. See filters in the REST API documentation for more details (example: {'videos' => {'category_id' => ['23', '25']}})

  • :functional_boosts (Hash) —

    a Hash of DocumentType slug to functional boost definition (example: {'videos' => {'view_count' => 'logarithmic'}}).

  • :facets (Hash) —

    a Hash of DocumentType slug to an Array of field names to provide facetted counts for (example: {'videos' => ['category_id', 'channel_id']})

  • :sort_field (Hash) —

    a Hash of DocumentType slug to field name to sort on (example: {'videos' => 'view_count'})

  • :sort_direction (Hash) —

    a Hash of DocumentType slug to direction to sort (example: 'videos' => 'desc'). Usually used with :sort_field.

Returns:



184
185
186
187
188
 
# File 'lib/swiftype/client.rb', line 184

def search_document_type(engine_id, document_type_id, query, options={})
  search_params = { :q => query }.merge(options)
  response = post("engines/#{engine_id}/document_types/#{document_type_id}/search.json", search_params)
  ResultSet.new(response)
end

#suggest(engine_id, query, options = {}) ⇒ Swiftype::ResultSet

Perform an autocomplete (prefix) search over all the DocumentTypes of the provided engine. This can be used to implement type-ahead autocompletion. However, if your data is not sensitive, you should consider using the Swiftype public JSONP API in the user's web browser for suggest queries.

results = client.suggest("swiftype-api-example", "gla")
results['videos'] # => [{'external_id' => 'v1uyQZNg2vE', 'title' => 'How It Feels [through Glass]', ...}, ...]

Parameters:

  • engine_id (String) —

    the Engine slug or ID

  • query (String) —

    the search terms

  • options (Hash) (defaults to: {}) —

    search options (see the REST API docs for a complete list)

Options Hash (options):

  • :page (Integer) —

    page number of results to fetch (server defaults to 1)

  • :per_page (Integer) —

    number of results per page (server defaults to 20)

  • :document_types (Array) —

    an array of DocumentType slugs to search. The server defaults to searching all DocumentTypes in the engine. To search a single document type, the suggest_document_type method is more convenient.

  • :fetch_fields (Hash) —

    a Hash of DocumentType slug to array of the fields to return with results (example: {'videos' => ['title', 'channel_id']})

  • :search_fields (Hash) —

    a Hash of DocumentType slug to array of the fields to search. May contain field weight boosts (example: {'videos' => ['title^5', 'tags^2', 'caption']}). The server defaults to searching all string fields for suggest queries.

  • :filters (Hash) —

    a Hash of DocumentType slug to filter definition Hash. See filters in the REST API documentation for more details (example: {'videos' => {'category_id' => ['23', '25']}})

  • :functional_boosts (Hash) —

    a Hash of DocumentType slug to functional boost definition (example: {'videos' => {'view_count' => 'logarithmic'}}).

  • :sort_field (Hash) —

    a Hash of DocumentType slug to field name to sort on (example: {'videos' => 'view_count'})

  • :sort_direction (Hash) —

    a Hash of DocumentType slug to direction to sort (example: 'videos' => 'desc'). Usually used with :sort_field.

Returns:



71
72
73
74
75
 
# File 'lib/swiftype/client.rb', line 71

def suggest(engine_id, query, options={})
  search_params = { :q => query }.merge(options)
  response = post("engines/#{engine_id}/suggest.json", search_params)
  ResultSet.new(response)
end

#suggest_document_type(engine_id, document_type_id, query, options = {}) ⇒ Swiftype::ResultSet

Perform an autocomplete (prefix) search over a single DocumentType in an Engine. This can be used to implement type-ahead autocompletion. However, if your data is not sensitive, you should consider using the Swiftype public JSONP API in the user's web browser for suggest queries.

results = client.suggest_document_type("swiftype-api-example", "videos", "gla")
results['videos'] # => [{'external_id' => 'v1uyQZNg2vE', 'title' => 'How It Feels [through Glass]', ...}, ...]

Parameters:

  • engine_id (String) —

    the Engine slug or ID

  • query (String) —

    the search terms

  • options (Hash) (defaults to: {}) —

    search options (see the REST API docs for a complete list)

Options Hash (options):

  • :page (Integer) —

    page number of results to fetch (server defaults to 1)

  • :per_page (Integer) —

    number of results per page (server defaults to 20)

  • :document_types (Array) —

    an array of DocumentType slugs to search. The server defaults to searching all DocumentTypes in the engine. To search a single document type, the suggest_document_type method is more convenient.

  • :fetch_fields (Hash) —

    a Hash of DocumentType slug to array of the fields to return with results (example: {'videos' => ['title', 'channel_id']})

  • :search_fields (Hash) —

    a Hash of DocumentType slug to array of the fields to search. May contain field weight boosts (example: {'videos' => ['title^5', 'tags^2', 'caption']}). The server defaults to searching all string fields for suggest queries.

  • :filters (Hash) —

    a Hash of DocumentType slug to filter definition Hash. See filters in the REST API documentation for more details (example: {'videos' => {'category_id' => ['23', '25']}})

  • :functional_boosts (Hash) —

    a Hash of DocumentType slug to functional boost definition (example: {'videos' => {'view_count' => 'logarithmic'}}).

  • :sort_field (Hash) —

    a Hash of DocumentType slug to field name to sort on (example: {'videos' => 'view_count'})

  • :sort_direction (Hash) —

    a Hash of DocumentType slug to direction to sort (example: 'videos' => 'desc'). Usually used with :sort_field.

Returns:



148
149
150
151
152
 
# File 'lib/swiftype/client.rb', line 148

def suggest_document_type(engine_id, document_type_id, query, options={})
  search_params = { :q => query }.merge(options)
  response = post("engines/#{engine_id}/document_types/#{document_type_id}/suggest.json", search_params)
  ResultSet.new(response)
end