documentation, example and README for delete/3, delete!/3

msonawane · Oct 9, 2018 · 074773d · 074773d
1 parent 8d9915e
commit 074773d
Show file tree

Hide file tree

Showing 2 changed files with 72 additions and 44 deletions.
diff --git a/README.md b/README.md
@@ -100,35 +100,38 @@ for more details on available search parameters.
 Hui provides functions to add, update and delete Solr documents, as well as optimised search indexes.
 
 ```elixir
- # Specify an update handler endpoint for JSON-formatted update
- headers = [{"Content-type", "application/json"}]
- url = %Hui.URL{url: "http://localhost:8983/solr/collection", handler: "update", headers: headers}
-
- # Solr documents
- 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"
- }
-
- # Add the docs and commit them to the index immediately
- Hui.update(url, [doc1, doc2])
-
- # Send documents to another pre-configured endpoint
- Hui.update(:updater, [doc1, doc2])
+  # Specify an update handler endpoint for JSON-formatted update
+  headers = [{"Content-type", "application/json"}]
+  url = %Hui.URL{url: "http://localhost:8983/solr/collection", handler: "update", headers: headers}
+
+  # Solr documents
+  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"
+  }
+
+  # Add the docs and commit them to the index immediately
+  Hui.update(url, [doc1, doc2])
+
+  # Send documents to another pre-configured endpoint
+  Hui.update(:updater, [doc1, doc2])
+
+  Hui.delete(url, "tt0077711") # delete one doc
+  Hui.delete(url, ["tt0077711", "tt0060827"]) # delete a list of docs
 
 ```
 
@@ -137,24 +140,24 @@ a struct - [`Hui.U`](https://hexdocs.pm/hui/Hui.U.html), as well as through
 any valid binary data encapsulating Solr documents and commands.
 
 ```elixir
- # Hui.U struct command for updating and committing the docs to Solr immediately
- x = %Hui.U{doc: [doc1, doc2], commit: true, waitSearcher: true}
- Hui.Request.update(url, x)
+  # Hui.U struct command for updating and committing the docs to Solr immediately
+  x = %Hui.U{doc: [doc1, doc2], commit: true, waitSearcher: true}
+  Hui.Request.update(url, x)
 
- # Commits docs within 5 seconds
- x = %Hui.U{doc: [doc1, doc2], commitWithin: 5000, overwrite: true}
- Hui.Request.update(url, x)
+  # Commits docs within 5 seconds
+  x = %Hui.U{doc: [doc1, doc2], commitWithin: 5000, overwrite: true}
+  Hui.Request.update(url, x)
 
- # Delete docs by query
- Hui.Request.update(url, %Hui.U{delete_query: "name:Persona"})
+  # Delete docs by query
+  Hui.Request.update(url, %Hui.U{delete_query: "name:Persona"})
 
- # Commit and optimise index
- Hui.Request.update(url, %Hui.U{commit: true, waitSearcher: true, optimize: true, maxSegments: 10})
+  # Commit and optimise index
+  Hui.Request.update(url, %Hui.U{commit: true, waitSearcher: true, optimize: true, maxSegments: 10})
 
- # Binary mode, e.g. delete a document via XML binary
- headers = [{"Content-type", "application/xml"}]
- url = %Hui.URL{url: "http://localhost:8983/solr/collection", handler: "update", headers: headers}
- Hui.Request.update(url, "<delete><id>9780141981727</id></delete>")
+  # Binary mode, e.g. delete a document via XML binary
+  headers = [{"Content-type", "application/xml"}]
+  url = %Hui.URL{url: "http://localhost:8983/solr/collection", handler: "update", headers: headers}
+  Hui.Request.update(url, "<delete><id>9780141981727</id></delete>")
 
 ```
 

diff --git a/lib/hui.ex b/lib/hui.ex
@@ -6,7 +6,7 @@ defmodule Hui do
   ### Usage
   
   - Searching Solr: `q/1`, `q/6`, `search/2`, `search/7`
-  - Updating: `update/3`
+  - Updating: `update/3`, `delete/3`
   - Other: `suggest/2`, `suggest/5`, `spellcheck/3`
   - [README](https://hexdocs.pm/hui/readme.html#usage)
   """
@@ -405,10 +405,35 @@ defmodule Hui do
   def update!(url, docs, _commit) when is_binary(docs), do: Request.update(url, true, docs)
   def update!(url, docs, commit) when is_map(docs) or is_list(docs), do: Request.update(url, true, %Hui.U{doc: docs, commit: commit})
 
+  @doc """
+  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 `t: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
+  ```
+  """
   @spec delete(binary | Hui.URL.t, binary | list(binary), boolean) :: {:ok, HTTPoison.Response.t} | {:error, Hui.Error.t}
   def delete(url, ids, commit \\ true)
   def delete(url, ids, commit) when is_binary(ids) or is_list(ids), do: Request.update(url, %Hui.U{delete_id: ids, commit: commit})
 
+  @doc """
+  Deletes Solr documents, raise an exception in case of failure.
+  """
   @spec delete!(binary | Hui.URL.t, binary | list(binary), boolean) :: HTTPoison.Response.t
   def delete!(url, ids, commit \\ true)
   def delete!(url, ids, commit) when is_binary(ids) or is_list(ids), do: Request.update(url, true, %Hui.U{delete_id: ids, commit: commit})