Hui v0.9.0 Hui View Source

Hui 辉 (“shine” in Chinese) is an Elixir client and library for Solr enterprise search platform.

Usage

Link to this section Summary

Functions

Commit any added or deleted Solr documents to the index, raise an exception in case of failure

Commit any added or deleted Solr documents to the index

Deletes Solr documents, raise an exception in case of failure

Deletes Solr documents

Deletes Solr documents by filter queries, raise an exception in case of failure

Deletes Solr documents by filter queries

Issue a keyword list or structured query to the default Solr endpoint, raising an exception in case of failure

Convenience function for issuing various typical queries to the default Solr endpoint, raise an exception in case of failure

Issue a keyword list or structured query to the default Solr endpoint

Convenience function for issuing various typical queries to the default Solr endpoint

Issue a keyword list or structured query to a specified Solr endpoint, raise an exception in case of failure

Convenience function for issuing various typical queries to a specified Solr endpoint, raise an exception in case of failure

Issue a keyword list or structured query to a specified Solr endpoint

Convenience function for issuing various typical queries to a specified Solr endpoint

Issue a structured suggester query to a specified Solr endpoint, raise an exception in case of failure

Convenience function for issuing a suggester query to a specified Solr endpoint, raise an exception in case of failure

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, raise an exception in case of failure

Updates or adds Solr documents to an index or collection

Link to this section Types

Link to this section Functions

Link to this function commit!(url, wait_searcher \\ true) View Source
commit!(binary() | Hui.URL.t(), boolean()) :: HTTPoison.Response.t()

Commit any added or deleted Solr documents to the index, raise an exception in case of failure.

Link to this function commit(url, wait_searcher \\ true) View Source
commit(binary() | Hui.URL.t(), boolean()) ::
  {:ok, HTTPoison.Response.t()} | {:error, Hui.Error.t()}

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 Hui.URL.t/0 struct or a URL config key. A JSON content type header for the URL is required so that Solr knows the incoming data format and can process data accordingly.

Example

  # Index handler for JSON-formatted update
  headers = [{"Content-type", "application/json"}]
  url = %Hui.URL{url: "http://localhost:8983/solr/collection", handler: "update", headers: headers}

  Hui.commit(url) # commits, make new docs available for search
  Hui.commit(url, false) # commits op only, new docs to be made available later

Use Hui.Request.update/3 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!(url, ids, commit \\ true) View Source
delete!(binary() | Hui.URL.t(), binary() | [binary()], boolean()) ::
  HTTPoison.Response.t()

Deletes Solr documents, raise an exception in case of failure.

Link to this function delete(url, ids, commit \\ true) View Source
delete(binary() | Hui.URL.t(), binary() | [binary()], boolean()) ::
  {:ok, HTTPoison.Response.t()} | {:error, Hui.Error.t()}

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 Hui.URL.t/0 struct or a URL config key. A JSON content type header for the URL is required so that Solr knows the incoming data format and can process data accordingly.

Example

  # Index handler for JSON-formatted update
  headers = [{"Content-type", "application/json"}]
  url = %Hui.URL{url: "http://localhost:8983/solr/collection", handler: "update", headers: headers}

  Hui.delete(url, "tt2358891") # delete a single doc
  Hui.delete(url, ["tt2358891", "tt1602620"]) # delete a list of docs

  Hui.delete(url, ["tt2358891", "tt1602620"], false) # delete without immediate commit
Link to this function delete_by_query!(url, queries, commit \\ true) View Source
delete_by_query!(binary() | Hui.URL.t(), binary() | [binary()], boolean()) ::
  HTTPoison.Response.t()

Deletes Solr documents by filter queries, raise an exception in case of failure.

Link to this function delete_by_query(url, queries, commit \\ true) View Source
delete_by_query(binary() | Hui.URL.t(), binary() | [binary()], boolean()) ::
  {:ok, HTTPoison.Response.t()} | {:error, Hui.Error.t()}

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 Hui.URL.t/0 struct or a URL config key. A JSON content type header for the URL is required so that Solr knows the incoming data format and can process data accordingly.

Example

  # Index handler for JSON-formatted update
  headers = [{"Content-type", "application/json"}]
  url = %Hui.URL{url: "http://localhost:8983/solr/collection", handler: "update", headers: headers}

  Hui.delete_by_query(url, "name:Persona") # delete with a single filter
  Hui.delete_by_query(url, ["genre:Drama", "name:Persona"]) # delete with a list of filters

Issue a keyword list or structured query to the default Solr endpoint, raising an exception in case of failure.

See q/1.

Link to this function q!(keywords, rows \\ nil, start \\ nil, filters \\ nil, facet_fields \\ nil, sort \\ nil) View Source
q!(
  binary(),
  nil | integer(),
  nil | integer(),
  nil | binary() | [binary()],
  nil | binary() | [binary()],
  nil | binary()
) :: HTTPoison.Response.t()

Convenience function for issuing various typical queries to the default Solr endpoint, raise an exception in case of failure.

Issue a keyword list or structured query to the default Solr endpoint.

The query can either be a keyword list or a list of Hui structs - see Hui.Query.solr_struct/0. This function is a shortcut for search/2 with :default as URL key.

Example

  Hui.q(q: "loch", rows: 5, facet: true, "facet.field": ["year", "subject"])

  # supply a list of Hui structs for more complex query, e.g. faceting
  alias Hui.Query

  Hui.q([%Query.Standard{q: "author:I*"}, %Query.Facet{field: ["cat", "author"], mincount: 1}])

  # DisMax
  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"], mincount: 1}

  Hui.q([x, y, z])
Link to this function q(keywords, rows \\ nil, start \\ nil, filters \\ nil, facet_fields \\ nil, sort \\ nil) View Source
q(
  binary(),
  nil | integer(),
  nil | integer(),
  nil | binary() | [binary()],
  nil | binary() | [binary()],
  nil | binary()
) :: {:ok, HTTPoison.Response.t()} | {:error, Hui.Error.t()}

Convenience function for issuing various typical queries to the default Solr endpoint.

Example

  Hui.q("scott")
  # keywords
  Hui.q("loch", 10, 20)
  # .. with paging parameters
  Hui.q("\"apache documentation\"~5", 1, 0, "stream_content_type_str:text/html", ["subject"])
  # .. plus filter(s) and facet fields

Issue a keyword list or structured query to a specified Solr endpoint, raise an exception in case of failure.

See search/2.

Link to this function search!(url, keywords, rows \\ nil, start \\ nil, filters \\ nil, facet_fields \\ nil, sort \\ nil) View Source
search!(
  url(),
  binary(),
  nil | integer(),
  nil | integer(),
  nil | binary() | [binary()],
  nil | binary() | [binary()],
  nil | binary()
) :: HTTPoison.Response.t()

Convenience function for issuing various typical queries to a specified Solr endpoint, raise an exception in case of failure.

See q/6.

Link to this function search(url, query) View Source
search(url(), query()) ::
  {:ok, HTTPoison.Response.t()} | {:error, Hui.Error.t()}

Issue a keyword list or structured query to a specified Solr endpoint.

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

  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
}
Link to this function search(url, keywords, rows \\ nil, start \\ nil, filters \\ nil, facet_fields \\ nil, sort \\ nil) View Source
search(
  url(),
  binary(),
  nil | integer(),
  nil | integer(),
  nil | binary() | [binary()],
  nil | binary() | [binary()],
  nil | binary()
) :: {:ok, HTTPoison.Response.t()} | {:error, Hui.Error.t()}

Convenience function for issuing various typical queries to a specified Solr endpoint.

See q/6.

Issue a structured suggester query to a specified Solr endpoint, raise an exception in case of failure.

Link to this function suggest!(url, q, count \\ nil, dictionaries \\ nil, context \\ nil) View Source
suggest!(
  url(),
  binary(),
  nil | integer(),
  nil | binary() | [binary()],
  nil | binary()
) :: HTTPoison.Response.t()

Convenience function for issuing a suggester query to a specified Solr endpoint, raise an exception in case of failure.

Link to this function suggest(url, query) View Source
suggest(url(), Hui.Query.Suggest.t()) ::
  {:ok, HTTPoison.Response.t()} | {:error, Hui.Error.t()}

Issue a structured suggest query to a specified Solr endpoint.

Example

  suggest_query = %Hui.Query.Suggest{q: "ha", count: 10, dictionary: "name_infix"}
  Hui.suggest(:library, suggest_query)
Link to this function suggest(url, q, count \\ nil, dictionaries \\ nil, context \\ nil) View Source
suggest(
  url(),
  binary(),
  nil | integer(),
  nil | binary() | [binary()],
  nil | binary()
) :: {:ok, HTTPoison.Response.t()} | {:error, Hui.Error.t()}

Convenience function for issuing a suggester query to a specified Solr endpoint.

Example

  Hui.suggest(:autocomplete, "t")
  Hui.suggest(:autocomplete, "bo", 5, ["name_infix", "ln_prefix", "fn_prefix"], "1939")
Link to this function update!(url, docs, commit \\ true) View Source
update!(binary() | Hui.URL.t(), binary() | map() | [map()], boolean()) ::
  HTTPoison.Response.t()

Updates or adds Solr documents to an index or collection, raise an exception in case of failure.

Link to this function update(url, docs, commit \\ true) View Source
update(binary() | Hui.URL.t(), binary() | map() | [map()], boolean()) ::
  {:ok, HTTPoison.Response.t()} | {:error, Hui.Error.t()}

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 binary mode, accepting text containing any valid Solr update data or commands.

An index/update handler endpoint should be specified through a Hui.URL.t/0 struct or a URL config key. A content type header is required so that Solr knows the incoming data format (JSON, XML etc.) and can process data accordingly.

Example

  # Index handler for JSON-formatted update
  headers = [{"Content-type", "application/json"}]
  url = %Hui.URL{url: "http://localhost:8983/solr/collection", handler: "update", headers: 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(url, doc1) # add a single doc
  Hui.update(url, [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(url, [doc1, doc2], false)

  # Send to a configured endpoint
  Hui.update(:updater, [doc1, doc2])

  # Binary mode, add and commit a doc
  Hui.update(url, "{\"add\":{\"doc\":{\"name\":\"Blade Runner\",\"id\":\"tt0083658\",..}},\"commit\":{}}")

  # Binary mode, delete a doc via XML
  headers = [{"Content-type", "application/xml"}]
  url = %Hui.URL{url: "http://localhost:8983/solr/collection", handler: "update", headers: headers}
  Hui.update(url, "<delete><id>9780141981727</id></delete>")

See Hui.Request.update/3 for more advanced update options.