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.

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.

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

Link to this function

commit(endpoint, wait_searcher \\ true, client \\ Hui.Http.Clients.Httpc)

View Source

Commit 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.

Link to this function

delete(endpoint, ids, commit \\ true)

View Source
This function is deprecated. Use delete_by_id/3 instead.
Link to this function

delete_by_id(endpoint, ids, commit \\ true, client \\ Hui.Http.Clients.Httpc)

View Source
@spec delete_by_id(endpoint(), binary() | [binary()], boolean(), module()) ::
  http_response()

Deletes 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
Link to this function

delete_by_query(endpoint, q, commit \\ true, client \\ Hui.Http.Clients.Httpc)

View Source

Deletes 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
Link to this function

metrics(endpoint, options)

View Source
@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"])
@spec ping(binary() | atom()) :: {:pong, integer()} | :pang

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, ..}}
Link to this function

search(endpoint, query, client)

View Source
@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 handler
  • headers: a tuple list of HTTP headers
  • options: 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.

Link to this function

suggest(endpoint, query)

View Source
@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)
Link to this function

suggest(endpoint, q, count, dictionaries, context)

View Source
@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})
Link to this function

update(endpoint, query, commit, client)

View Source
@spec update(endpoint(), update_query(), boolean(), module()) :: http_response()

See Hui.Http.post/4.