Specs

commit(endpoint(), boolean()) :: http_response()

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

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

Specs

delete(endpoint(), binary() | [binary()], boolean()) :: 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

  # Index handler for JSON-formatted update
  headers = [{"content-type", "application/json"}]
  endpoint = {"http://localhost:8983/solr/collection/update", headers}

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

  Hui.delete(endpoint, ["tt2358891", "tt1602620"], false) # delete without immediate commit

Specs

delete_by_query(endpoint(), binary() | [binary()], boolean()) :: http_response()

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

  # 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

Specs

get(endpoint(), query()) :: http_response()

Issues a get request of Solr query to a specific endpoint.

The query can be a keyword list or a list of Hui query structs (query/0).

Example - parameters

  endpoint = "http://..."

  # query via a list of keywords, which are unbound and sent to Solr directly
  Hui.get(endpoint, q: "glen cova", facet: "true", "facet.field": ["type", "year"])

  # query via Hui structs
  alias Hui.Query
  Hui.get(endpoint, %Query.DisMax{q: "glen cova"})
  Hui.get(endpoint, [%Query.DisMax{q: "glen"}, %Query.Facet{field: ["type", "year"]}])

The use of structs is more idiomatic and succinct. It is bound to qualified Solr fields.

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 Erlang httpc options or HTTPoison options if configured, 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.

Specs

metrics(endpoint(), keyword()) :: http_response()

Retrieves metrics data from the Solr admin API.

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"])

Specs

ping() :: {:pong, integer()} | :pang

Ping the default configured endpoint.

Successful ping returns a {:pong, qtime} tuple, whereas failure gets a :pang response.

Specs

ping(binary() | atom()) :: {:pong, integer()} | :pang

Ping a given endpoint.

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.

Specs

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, ..}}

Specs

post(endpoint(), update_query()) :: http_response()

Issues a POST request to a specific Solr endpoint, e.g. for data indexing and deletion.

Specs

q(query()) :: http_response()

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.solr_struct/0. This function is a shortcut for search/2 with :default as the configured endpoint 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])

Specs

q(
  binary(),
  nil | integer(),
  nil | integer(),
  nil | binary() | [binary()],
  nil | binary() | [binary()],
  nil | binary()
) :: http_response()

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

Example

  Hui.q("scott")
  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

Specs

search(endpoint(), query()) :: http_response()

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
}

Specs

search(
  endpoint(),
  binary(),
  nil | integer(),
  nil | integer(),
  nil | binary() | [binary()],
  nil | binary() | [binary()],
  nil | binary()
) :: http_response()

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

See q/6.

Specs

suggest(endpoint(), Hui.Query.Suggest.t()) :: http_response()

Issue a structured suggest query to a specified Solr endpoint.

Example

  # :library is a configured endpoint
  suggest_query = %Hui.Query.Suggest{q: "ha", count: 10, dictionary: "name_infix"}
  Hui.suggest(:library, suggest_query)

Specs

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

  # :autocomplete is a configured endpoint
  Hui.suggest(:autocomplete, "t")
  Hui.suggest(:autocomplete, "bo", 5, ["name_infix", "ln_prefix", "fn_prefix"], "1939")

Specs

update(endpoint(), update_query(), boolean()) :: 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

  # 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

  # 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})