View Source Hui (Hui v0.11.0)
Hui 辉 ("shine" in Chinese) is an Elixir client and library for Solr enterprise search platform.
usage
Usage
Link to this section Summary
Functions
Commit any added or deleted Solr documents to the index.
Deletes Solr documents.
Deletes Solr documents by filter queries.
Retrieves metrics data from the Solr admin API.
Ping a given endpoint.
Ping a given endpoint with options.
Issue a keyword list or structured query to a Solr endpoint.
Issue a structured suggest query to a specified Solr endpoint.
Convenience function for issuing a suggester query to a specified Solr endpoint.
Updates or adds Solr documents to an index or collection.
See Hui.Http.post/4
.
Link to this section Types
@type endpoint() :: Hui.Http.endpoint()
@type http_response() :: Hui.Http.response()
@type query() :: Hui.Http.query()
@type update_query() :: Hui.Http.update_query()
Link to this section Functions
commit(endpoint, wait_searcher \\ true, client \\ Hui.Http.Clients.Httpc)
View SourceCommit any added or deleted Solr documents to the index.
This provides a (separate) mechanism to commit previously added or deleted documents to Solr index for different updating and index maintenance scenarios. By default, the commit waits for a new Solr searcher to be regenerated, so that the commit result is made available for search.
An index/update handler endpoint should be specified through a URL string or {url, headers, options} tuple.
A JSON "content-type" request header is required so that Solr knows the incoming data format and can process data accordingly.
example
Example
# Index handler for JSON-formatted update
headers = [{"content-type", "application/json"}]
endpoint = {"http://localhost:8983/solr/collection", headers}
Hui.commit(endpoint) # commits, make new docs available for search
Hui.commit(endpoint, false) # commits op only, new docs to be made available later
Use Hui.Query.Update.t/0
struct for other types of commit and index optimisation, e.g. expunge deleted docs to
physically remove docs from the index, which could be a system-intensive operation.
delete_by_id(endpoint, ids, commit \\ true, client \\ Hui.Http.Clients.Httpc)
View SourceDeletes Solr documents.
This function accepts a single or list of IDs and immediately delete the corresponding documents from the Solr index (commit by default).
An index/update handler endpoint should be specified through a URL string or {url, headers, options} tuple.
A JSON "content-type" request header is required so that Solr knows the incoming data format and can process data accordingly.
example
Example
# Index handler for JSON-formatted update
headers = [{"content-type", "application/json"}]
endpoint = {"http://localhost:8983/solr/collection/update", headers}
Hui.delete_by_id(endpoint, "tt2358891") # delete a single doc
Hui.delete_by_id(endpoint, ["tt2358891", "tt1602620"]) # delete a list of docs
Hui.delete_by_id(endpoint, ["tt2358891", "tt1602620"], false) # delete without immediate commit
delete_by_query(endpoint, q, commit \\ true, client \\ Hui.Http.Clients.Httpc)
View SourceDeletes Solr documents by filter queries.
This function accepts a single or list of filter queries and immediately delete the corresponding documents from the Solr index (commit by default).
An index/update handler endpoint should be specified through a URL string or {url, headers, options} tuple.
A JSON "content-type" request header is required so that Solr knows the incoming data format and can process data accordingly.
example
Example
# Index handler for JSON-formatted update
headers = [{"content-type", "application/json"}]
endpoint = {"http://localhost:8983/solr/collection", headers}
Hui.delete_by_query(endpoint, "name:Persona") # delete with a single filter
Hui.delete_by_query(endpoint, ["genre:Drama", "name:Persona"]) # delete with a list of filters
@spec metrics(endpoint(), keyword()) :: http_response()
Retrieves metrics data from the Solr admin API.
example
Example
endpoint = {"http://localhost:8983/solr/admin/metrics", [{"content-type", "application/json"}]}
Hui.metrics(endpoint, group: "core", type: "timer", property: ["mean_ms", "max_ms", "p99_ms"])
Ping a given endpoint.
example
Example
# ping a configured atomic endpoint
Hui.ping(:gettingstarted)
# directly ping a binary URL
Hui.ping("http://localhost:8983/solr/gettingstarted/admin/ping")
Successful ping returns a {:pong, qtime}
tuple, whereas failure gets a :pang
response.
@spec ping(binary() | atom(), keyword()) :: http_response()
Ping a given endpoint with options.
Raw HTTP response is returned when options such as wt
, distrib
is provided:
Hui.ping(:gettingstarted, wt: "xml", distrib: false)
# -> returns {:ok, %Hui.HTTP{body: "raw HTTP response", status: 200, ..}}
@spec search(endpoint(), query(), module()) :: http_response()
Issue a keyword list or structured query to a Solr endpoint.
example-parameters
Example - parameters
url = "http://localhost:8983/solr/collection"
# a keyword list of arbitrary parameters
Hui.search(url, q: "edinburgh", rows: 10)
# supply a list of Hui structs for more complex query e.g. DisMax
alias Hui.Query
x = %Query.DisMax{q: "run", qf: "description^2.3 title", mm: "2<-25% 9<-3"}
y = %Query.Common{rows: 10, start: 10, fq: ["edited:true"]}
z = %Query.Facet{field: ["cat", "author_str"], mincount: 1}
Hui.search(url, [x, y, z])
# SolrCloud query
x = %Query.DisMax{q: "john"}
y = %Query.Common{collection: "library,commons", rows: 10, distrib: true, "shards.tolerant": true, "shards.info": true}
Hui.search(url, [x,y])
# With results highlighting (snippets)
x = %Query.Standard{q: "features:photo"}
y = %Query.Highlight{fl: "features", usePhraseHighlighter: true, fragsize: 250, snippets: 3}
Hui.search(url, [x, y])
example-faceting
Example - faceting
alias Hui.Query
range1 = %Query.FacetRange{range: "price", start: 0, end: 100, gap: 10, per_field: true}
range2 = %Query.FacetRange{range: "popularity", start: 0, end: 5, gap: 1, per_field: true}
x = %Query.DisMax{q: "ivan"}
y = %Query.Facet{field: ["cat", "author_str"], mincount: 1, range: [range1, range2]}
Hui.search(:default, [x, y])
The above Hui.search(:default, [x, y])
example issues a request that resulted in
the following Solr response header showing the corresponding generated and encoded parameters.
"responseHeader" => %{
"QTime" => 106,
"params" => %{
"f.popularity.facet.range.end" => "5",
"f.popularity.facet.range.gap" => "1",
"f.popularity.facet.range.start" => "0",
"f.price.facet.range.end" => "100",
"f.price.facet.range.gap" => "10",
"f.price.facet.range.start" => "0",
"facet" => "true",
"facet.field" => ["cat", "author_str"],
"facet.mincount" => "1",
"facet.range" => ["price", "popularity"],
"q" => "ivan"
},
"status" => 0,
"zkConnected" => true
}
urls-headers-options
URLs, Headers, Options
HTTP headers and client options for a specific endpoint may also be
included in the a {url, headers, options}
tuple where:
url
is a typical Solr endpoint that includes a request handlerheaders
: a tuple list of HTTP headersoptions
: a keyword list of configured http client options such as Erlang httpc, HTTPoison, e.g.timeout
,recv_timeout
,max_redirect
If HTTPoison
is used, advanced HTTP options such as the use of connection pools
may also be specified via options
.
@spec suggest(endpoint(), Hui.Query.Suggest.t()) :: http_response()
Issue a structured suggest query to a specified Solr endpoint.
example
Example
# :library is a configured endpoint
suggest_query = %Hui.Query.Suggest{q: "ha", count: 10, dictionary: "name_infix"}
Hui.suggest(:library, suggest_query)
@spec suggest( endpoint(), binary(), nil | integer(), nil | binary() | [binary()], nil | binary() ) :: http_response()
Convenience function for issuing a suggester query to a specified Solr endpoint.
example
Example
# :autocomplete is a configured endpoint
Hui.suggest(:autocomplete, "t")
Hui.suggest(:autocomplete, "bo", 5, ["name_infix", "ln_prefix", "fn_prefix"], "1939")
@spec update(endpoint(), update_query()) :: http_response()
Updates or adds Solr documents to an index or collection.
This function accepts documents as map (single or a list) and commits the docs
to the index immediately by default - set commit
to false
for manual or
auto commits later.
It can also operate in update struct and binary modes,
the former uses the Hui.Query.Update.t/0
struct
while the latter acepts text containing any valid Solr update data or commands.
An index/update handler endpoint should be specified through a URL string or {url, headers, options} tuple for headers and HTTP client options specification.
A "content-type" request header is required so that Solr knows the incoming data format (JSON, XML etc.) and can process data accordingly.
example-map-list-and-binary-data
Example - map, list and binary data
# Index handler for JSON-formatted update
headers = [{"content-type", "application/json"}]
endpoint = {"http://localhost:8983/solr/collection/update", headers}
# Solr docs in maps
doc1 = %{
"actors" => ["Ingrid Bergman", "Liv Ullmann", "Lena Nyman", "Halvar Björk"],
"desc" => "A married daughter who longs for her mother's love is visited by the latter, a successful concert pianist.",
"directed_by" => ["Ingmar Bergman"],
"genre" => ["Drama", "Music"],
"id" => "tt0077711",
"initial_release_date" => "1978-10-08",
"name" => "Autumn Sonata"
}
doc2 = %{
"actors" => ["Bibi Andersson", "Liv Ullmann", "Margaretha Krook"],
"desc" => "A nurse is put in charge of a mute actress and finds that their personas are melding together.",
"directed_by" => ["Ingmar Bergman"],
"genre" => ["Drama", "Thriller"],
"id" => "tt0060827",
"initial_release_date" => "1967-09-21",
"name" => "Persona"
}
Hui.update(endpoint, doc1) # add a single doc
Hui.update(endpoint, [doc1, doc2]) # add a list of docs
# Don't commit the docs e.g. mass ingestion when index handler is setup for autocommit.
Hui.update(endpoint, [doc1, doc2], false)
# Send to a configured endpoint
Hui.update(:updater, [doc1, doc2])
# Binary mode, add and commit a doc
Hui.update(endpoint, "{\"add\":{\"doc\":{\"name\":\"Blade Runner\",\"id\":\"tt0083658\",..}},\"commit\":{}}")
# Binary mode, delete a doc via XML
headers = [{"content-type", "application/xml"}]
endpoint = {"http://localhost:8983/solr/collection/update", headers}
Hui.update(endpoint, "<delete><id>9780141981727</id></delete>")
example-hui-query-update-t-0-and-other-update-options
Example - Hui.Query.Update.t/0
and other update options
# endpoint, doc1, doc2 from the above example
...
# Hui.Query.Update struct command for updating and committing the docs to Solr within 5 seconds
alias Hui.Query
x = %Query.Update{doc: [doc1, doc2], commitWithin: 5000, overwrite: true}
{status, resp} = Hui.update(endpoint, x)
# Delete the docs by IDs, with a URL key from configuration
{status, resp} = Hui.update(:library_update, %Query.Update{delete_id: ["tt1316540", "tt1650453"]})
# Commit and optimise index, keep max index segments at 10
{status, resp} = Hui.update(endpoint, %Query.Update{commit: true, waitSearcher: true, optimize: true, maxSegments: 10})
# Commit index, expunge deleted docs
{status, resp} = Hui.update(endpoint, %Query.Update{commit: true, expungeDeletes: true})
@spec update(endpoint(), update_query(), boolean(), module()) :: http_response()
See Hui.Http.post/4
.