This quick guide will get you started with Solr. It is by no means comprehensive, and should not replace reading the documentation
- Java (
java -version
must be 1.8.0 or higher.) - Ruby (Any version should work, newer is better.)
If you want to skip this, I have included a Vagrantfile which will set up the environment in an Ubuntu 16_04 box.
Install the solr_wrapper gem by running gem install solr_wrapper
. You may need to put sudo
in front of that.
Then, copy the .solr_wrapper file below to the folder you want to work in.
The .solrwrapper file configures the version of Solr we use, and how it runs. Right now, we are using version 6.6.2, Solr's UI shows up on port 8983, and data is not deleted between shutdowns.
Start Solr by running solr_wrapper
.
You should see a download progress bar, if this is your first time running it.
When it prints a URL (like http://127.0.0.1:8983/solr/), Solr is running.
It will continue to run in the foreground until you use ctrl-c
to stop it.
If this is the first time starting Solr, you'll need to create a core.
For now, we'll create one named 'dev' by running ./solr-dev/bin/solr create -c 'dev'
.
Trust me, this is easier than trying to create one through the UI.
If you changed the instance_dir from 'solr-dev' in the .solrwrapper file, you'll need to change it the previous command as well.
Now, we can open a browser and go to the URL Solr gave earlier (like http://127.0.0.1:8983/solr/). This will take you to the Solr Dashboard.
In the column on the left side, under the Solr logo, click on Core Admin You will see any cores you have created here. This is a sanity check to ensure the core you created earlier exists.
Back on that left-hand column, there is a dropdown called Core Selector. Click on it, and pick your core. You should now see more options below the selector. Two in particular are useful to us: Documents and Query.
The Documents page is where you add (or remove) results (documents) to Solr, through the UI.
You can change the doument type to XML and copy a single doc from the add_docs.xml file below,
or change it to Solr Command, and copy the whole file into the Document(s) box, and click Submit Document.
The latter is the same as running curl http://127.0.0.1:8983/solr/dev/update -H "Content-Type: text/xml" --data-binary @./add_docs.xml
from the folder add_docs.xml is in.
The add_docs.xml file has three documents in it, which we will search for in the Query section below. Since Overwrite is set to true (both by default in the form, and in the file), adding documents is idempotent, and can be rerun without adverse effects.
To remove documents, change the document type to Solr Command, and copy the contents of the remove_docs.xml into
the Documents field, and click Submit Documents. The curl equivalent is
curl http://127.0.0.1:8983/solr/dev/update -H "Content-Type: text/xml" --data-binary @./remove_docs.xml
.
That will delete the test page doc, and any doc with HealthSciences in the library field.
This is where you can build a search. Putting a string into the 'q' field will search all fields for that string. You can restrict a search to a specific field by putting the field name and a colon before the search term, like 'title:Test'. The 'fq' field allows you to filter the documents the search will run against. For example, setting the 'fq' to 'library:General' will only return results where the library field matches General, in addition to whatever the 'q' term is. The 'start' and 'rows' settings allow you to paginate the results, and 'wt' sets the format the results will be returned as.
I absolutely love that the URL equivalent of what you create from the form is shown above the results.
The easiest way to recover from errors is to delete the solr-dev forlder, and start from the Running Solr above again. This will delete all the data you had in Solr, though.