{"id":19206,"date":"2013-11-27T01:48:51","date_gmt":"2013-11-26T23:48:51","guid":{"rendered":"http:\/\/www.javacodegeeks.com\/?p=19206"},"modified":"2013-11-27T01:48:51","modified_gmt":"2013-11-26T23:48:51","slug":"getting-started-with-spring-data-solr","status":"publish","type":"post","link":"https:\/\/www.javacodegeeks.com\/2013\/11\/getting-started-with-spring-data-solr.html","title":{"rendered":"Getting started with Spring Data Solr"},"content":{"rendered":"

Spring Data Solr<\/a> is an extension to the Spring Data project which aims to simplify the usage of Apache Solr<\/a> in Spring applications. Please note that this is not an introduction into Spring (Data) or Solr. I assume you have at least some basic understanding of both technologies. Within the following post I will show how you can use Spring Data repositories to access Solr features in Spring applications.<\/p>\n

Configuration<\/h2>\n

First we need a running Solr server. For simplicity reasons we will use the example configuration that comes with the current Solr release (4.5.1 at the time I am writing) and is described in the official Solr tutorial<\/a>. So we only have to download Solr, extract it in a directory of our choice and then run java -jar start.jar from the <solr home>\/example directory.<\/p>\n

Now let’s move to our demo application and add the Spring Data Solr dependency using maven:<\/p>\n

<dependency>\r\n\u00a0\u00a0<groupId>org.springframework.data<\/groupId>\r\n\u00a0\u00a0<artifactId>spring-data-solr<\/artifactId>\r\n\u00a0\u00a0<version>1.0.0.RELEASE<\/version>\r\n<\/dependency><\/pre>\n
In this example I am using Spring Boot to set up a small example Spring application. I am using the following Spring Boot dependencies and the Spring Boot parent pom for this:<\/p>\n
<parent>\r\n\u00a0\u00a0<groupId>org.springframework.boot<\/groupId>\r\n\u00a0\u00a0<artifactId>spring-boot-starter-parent<\/artifactId>\r\n\u00a0\u00a0<version>0.5.0.BUILD-SNAPSHOT<\/version>\r\n<\/parent><\/pre>\n
<dependency>\r\n\u00a0\u00a0<groupId>org.springframework.boot<\/groupId>\r\n\u00a0\u00a0<artifactId>spring-boot-starter<\/artifactId>\r\n<\/dependency>\r\n<dependency>\r\n\u00a0\u00a0<groupId>org.springframework.boot<\/groupId>\r\n\u00a0\u00a0<artifactId>spring-boot-starter-test<\/artifactId>\r\n\u00a0\u00a0<scope>test<\/scope>\r\n<\/dependency><\/pre>\n
Don’t worry if you haven’t used Spring Boot yet. These dependencies mainly act as shortcut for common (Spring) dependencies and simplify the configuration a bit. If you want to integrate Spring Data Solr within an existing Spring application you can skip the Spring Boot dependencies.<\/p>\n
The Spring bean configuration is quite simple, we only have to define two beans ourself:<\/p>\n
@ComponentScan\r\n@EnableSolrRepositories(\"com.mscharhag.solr.repository\")\r\npublic\u00a0class\u00a0Application\u00a0{\r\n\r\n\u00a0\u00a0@Bean\r\n\u00a0\u00a0public\u00a0SolrServer\u00a0solrServer()\u00a0{\r\n\u00a0\u00a0\u00a0\u00a0return\u00a0new\u00a0HttpSolrServer(\"http:\/\/localhost:8983\/solr\");\r\n\u00a0\u00a0}\r\n\r\n\u00a0\u00a0@Bean\r\n\u00a0\u00a0public\u00a0SolrTemplate\u00a0solrTemplate(SolrServer\u00a0server)\u00a0throws\u00a0Exception\u00a0{\r\n\u00a0\u00a0\u00a0\u00a0return\u00a0new\u00a0SolrTemplate(server);\r\n\u00a0\u00a0}\r\n}<\/pre>\n
The solrServer bean is used to connect to the running Solr instance. Since Spring Data Solr uses Solrj<\/a> we create a Solrj HttpSolrServer<\/a> instance. It would also be possible to use an embedded Solr server by using EmbeddedSolrServer<\/a>. The SolrTemplate provides common functionality to work with Solr (similar to Spring’s JdbcTemplate). A solrTemplate bean is required for creating Solr repositories. Please also note the @EnableSolrRepositories annotation. With this annotation we tell Spring Data Solr to look in the specified package for Solr repositories.<\/p>\n
Creating a document<\/h2>\n
Before we can query Solr we have to add documents to the index. To define a document we create a POJO<\/a> and add Solrj annotations to it. In this example we will use a simple Book class as document:<\/p>\n
public\u00a0class\u00a0Book\u00a0{\r\n\r\n\u00a0\u00a0@Field\r\n\u00a0\u00a0private\u00a0String\u00a0id;\r\n\r\n\u00a0\u00a0@Field\r\n\u00a0\u00a0private\u00a0String\u00a0name;\r\n\r\n\u00a0\u00a0@Field\r\n\u00a0\u00a0private\u00a0String\u00a0description;\r\n\r\n\u00a0\u00a0@Field(\"categories_txt\")\r\n\u00a0\u00a0private\u00a0List<Category>\u00a0categories;\r\n\r\n\u00a0\u00a0\/\/\u00a0getters\/setters\r\n}<\/pre>\n
public\u00a0enum\u00a0Category\u00a0{\r\n\u00a0\u00a0EDUCATION,\u00a0HISTORY,\u00a0HUMOR,\u00a0TECHNOLOGY,\u00a0ROMANCE,\u00a0ADVENTURE\r\n}<\/pre>\n
Each book has a unique id, a name, a description and belongs to one or more categories. Note that Solr requires a unique ID of type String for each document by default. Fields that should be added to the Solr index are annotated with the Solrj @Field<\/a> annotation. By default Solrj tries to map document field names to Solr fields of the same name. The Solr example configuration already defines Solr fields named id, name and description so it should not be necessary to add these fields to the Solr configuration.
 
<\/div> <\/div><\/p>\n
In case you want to change the Solr field definitions you can find the example configuration file at <solr home>\/example\/solr\/collection1\/conf\/schema.xml. Within this file you should find the following field definitions:<\/p>\n
<field\u00a0name=\"id\"\u00a0type=\"string\"\u00a0indexed=\"true\"\u00a0stored=\"true\"\u00a0required=\"true\"\u00a0multiValued=\"false\"\u00a0\/>\u00a0\r\n<field\u00a0name=\"name\"\u00a0type=\"text_general\"\u00a0indexed=\"true\"\u00a0stored=\"true\"\u00a0\/>\r\n<field\u00a0name=\"description\"\u00a0type=\"text_general\"\u00a0indexed=\"true\"\u00a0stored=\"true\"\/><\/pre>\n
In general title would be a better attribute name for a Book than name. However, by using name we can use the default Solr field configuration. So I go for name instead of title for simplicity reasons.<\/p>\n
For categories we have to define the field name manually using the @Field annotation: categories_txt. This matches the dynamic field named *_txt from the Solr example. This field definition can also be found in schema.xml:<\/p>\n
<dynamicField\u00a0name=\"*_txt\"\u00a0type=\"text_general\"\u00a0\u00a0\u00a0indexed=\"true\"\u00a0\u00a0stored=\"true\"\u00a0multiValued=\"true\"\/><\/pre>\n
Creating a repository<\/h2>\n
Spring Data uses repositories to simplify the usage of various data access technologies. A repository is basically an interface whose implementation is dynamically generated by Spring Data on application start. The generated implementation is based on naming conventions used in the repository interface. If this is new to you I recommend reading Working with Spring Data Repositories<\/a>.<\/p>\n
Spring Data Solr uses the same approach. We use naming conventions and annotations inside interfaces to define the methods we need to access Solr features. We start with a simple repository that contains only one method (we will add more later):<\/p>\n
public\u00a0interface\u00a0BookRepository\u00a0extends\u00a0SolrCrudRepository<Book,\u00a0String>\u00a0{\r\n\r\n\u00a0\u00a0List<Book>\u00a0findByName(String\u00a0name);\r\n\r\n}<\/pre>\n
We get some common methods like save(), findAll(), delete() or count() in the repository by extending SolrCrudRepository. With the definition of the interface method findByName(String name) we tell Spring Data Solr to create a method implementation that queries Solr for a list of books. The book names in this list should match the passed parameter.<\/p>\n
The repository implementation can be injected into other classes using Spring’s DI functionality. In this example we inject the repository into a simple JUnit test:<\/p>\n
@RunWith(SpringJUnit4ClassRunner.class)\r\n@ContextConfiguration(classes\u00a0=\u00a0Application.class,\u00a0loader=SpringApplicationContextLoader.class)\r\npublic\u00a0class\u00a0BookRepositoryTests\u00a0{\r\n\r\n\u00a0\u00a0@Autowired\r\n\u00a0\u00a0private\u00a0BookRepository\u00a0bookRepository;\r\n\r\n\u00a0\u00a0...\r\n}<\/pre>\n
Adding a document to Solr<\/h2>\n
Now it is time to add some books to Solr. Using our repository this is a very easy job:<\/p>\n
private\u00a0void\u00a0addBookToIndex(String\u00a0name,\u00a0String\u00a0description,\u00a0Category...\u00a0categories)\u00a0{\r\n\u00a0\u00a0Book\u00a0book\u00a0=\u00a0new\u00a0Book();\r\n\u00a0\u00a0book.setName(name);\r\n\u00a0\u00a0book.setDescription(description);\r\n\u00a0\u00a0book.setCategories(Arrays.asList(categories));\r\n\u00a0\u00a0book.setId(UUID.randomUUID().toString());\r\n\u00a0\u00a0bookRepository.save(book);\r\n}\r\n\r\nprivate\u00a0void\u00a0createSampleData()\u00a0{\r\n\u00a0\u00a0addBookToIndex(\"Treasure\u00a0Island\",\u00a0\"Best\u00a0seller\u00a0by\u00a0R.L.S.\", Category.ADVENTURE);\r\n\u00a0\u00a0addBookToIndex(\"The\u00a0Pirate\u00a0Island\",\u00a0\"Oh\u00a0noes,\u00a0the\u00a0pirates\u00a0are\u00a0coming!\", Category.ADVENTURE, Category.HUMOR);\r\n\u00a0\u00a0...\r\n}<\/pre>\n
Adding pagination and boosting<\/h2>\n
Assume we have an application where users are able to search for books. We need to find books whose name or description match the search query given by the user. For performance reasons we want to add some kind of pagination which shows only 10 search results at once to the user.<\/p>\n
Let’s create a new method in our repository interface for this:<\/p>\n
Page<Book>\u00a0findByNameOrDescription(@Boost(2)\u00a0String\u00a0name,\u00a0String\u00a0description,\u00a0Pageable\u00a0pageable);<\/pre>\n
The method name findByNameOrDescription tells Spring Data Solr to query for book objects whose name or description match the passed parameters. To support pagination we added the Pageable parameter and changed the return type from List<Book> to Page<Book>. By adding the @Boost annotation to the name parameter we are boosting books whose name matches the search parameter. This makes sense because those books are typically at higher Interest for the user.<\/p>\n
If we now want to query for the first page containing 10 elements we just have to do:<\/p>\n
Page<Book>\u00a0booksPage\u00a0=\u00a0bookRepository.findByNameOrDescription\r\n(searchString,\u00a0searchString,\u00a0new\u00a0PageRequest(0,\u00a010));<\/pre>\n
Besides the first 10 search results Page<Book> provides some useful methods for building pagination functionality:<\/p>\n
booksPage.getContent()\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\/\/\u00a0get\u00a0a\u00a0list\u00a0of\u00a0(max)\u00a010\u00a0books\r\nbooksPage.getTotalElements() \/\/\u00a0total\u00a0number\u00a0of\u00a0elements\u00a0(can\u00a0be\u00a0>10)\r\nbooksPage.getTotalPages()\u00a0\u00a0\u00a0\u00a0\/\/\u00a0total\u00a0number\u00a0of\u00a0pages\r\nbooksPage.getNumber()\u00a0\u00a0\u00a0\u00a0\u00a0  \u00a0\/\/\u00a0current\u00a0page\u00a0number\r\nbooksPage.isFirstPage()\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\/\/\u00a0true\u00a0if\u00a0this\u00a0is\u00a0the\u00a0first\u00a0page\r\nbooksPage.hasNextPage()\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\/\/\u00a0true\u00a0if\u00a0another\u00a0page\u00a0is\u00a0available\r\nbooksPage.nextPageable()\u00a0\u00a0\u00a0\u00a0 \/\/\u00a0the\u00a0pageable\u00a0for\u00a0requesting\u00a0the\u00a0next\u00a0page\r\n...<\/pre>\n
Faceting<\/h2>\n
Whenever a user searches for a book name we want to show him how many books matching the given query parameter are available in the different categories. This feature is called faceted search<\/a> and directly supported by Spring Data Solr. We just have to add another method to our repository interface:<\/p>\n
@Query(\"name:?0\")\r\n@Facet(fields\u00a0=\u00a0{\u00a0\"categories_txt\"\u00a0},\u00a0limit\u00a0=\u00a05)\r\nFacetPage<Book>\u00a0findByNameAndFacetOnCategories(String\u00a0name,\u00a0Pageable\u00a0page);<\/pre>\n
This time the query will be derived from the @Query annotation (containing the Solr query) instead of the method name. With the @Facet annotation we tell Spring Data Solr to facet books by categories and return the first five facets.<\/p>\n
It would also be possible to remove the @Query annotation and change the method name to findByName for the same effect. The small disadvantage in this approach is that it is not obvious to the caller that this repository method does perform facetting. Addionally the method signature might collide with other methods that search books by name.<\/p>\n
Usage:<\/strong><\/p>\n
FacetPage<Book>\u00a0booksFacetPage\u00a0=\u00a0bookRepository.findByNameAndFacetOnCategories(bookName,\u00a0new\u00a0PageRequest(0,\u00a010));\r\n\r\nbooksFacetPage.getContent();\u00a0\/\/\u00a0the\u00a0first\u00a010\u00a0books\r\n\r\nfor\u00a0(Page<?\u00a0extends\u00a0FacetEntry>\u00a0page\u00a0:\u00a0booksFacetPage.getAllFacets())\u00a0{\r\n\u00a0\u00a0for\u00a0(FacetEntry\u00a0facetEntry\u00a0:\u00a0page.getContent())\u00a0{\r\n\u00a0\u00a0\u00a0\u00a0String\u00a0categoryName\u00a0=\u00a0facetEntry.getValue();\u00a0 \/\/\u00a0name\u00a0of\u00a0the\u00a0category\r\n\u00a0\u00a0\u00a0\u00a0long\u00a0count\u00a0=\u00a0facetEntry.getValueCount();\u00a0\u00a0\u00a0\u00a0  \/\/\u00a0number\u00a0of\u00a0books\u00a0in\u00a0this\u00a0category\r\n\r\n\u00a0\u00a0\u00a0\u00a0\/\/\u00a0convert\u00a0the\u00a0category\u00a0name\u00a0back\u00a0to\u00a0an\u00a0enum\r\n\u00a0\u00a0\u00a0\u00a0Category\u00a0category\u00a0=\u00a0Category.valueOf(categoryName.toUpperCase());\r\n\u00a0 }\r\n}<\/pre>\n
Note that booksFacetPage.getAllFacets() returns a Collection of FacetEntry pages. This is because the @Facet annotation allows you to facet multiple fields at once. Each FacetPage contains max. five FacetEntries (defined by the limit attribute of @Facet).<\/p>\n
Highlighting<\/h2>\n
Often it is useful to highlight the search query occurrences in the list of search results (like it is done by google or bing). This can be achieved with the highlighting feature of (Spring Data) Solr.<\/p>\n
Let’s add another repository method:<\/p>\n
@Highlight(prefix\u00a0=\u00a0\"<highlight>\",\u00a0postfix\u00a0=\u00a0\"<\/highlight>\")\r\nHighlightPage<Book>\u00a0findByDescription(String\u00a0description,\u00a0Pageable\u00a0pageable);<\/pre>\n
The @Highlight annotation tells Solr to highlight to occurrences of the searched description.<\/p>\n
Usage:<\/strong><\/p>\n
HighlightPage<Book>\u00a0booksHighlightPage\u00a0=\u00a0bookRepository.findByDescription(description,\u00a0new\u00a0PageRequest(0,\u00a010));\r\n\r\nbooksHighlightPage.getContent();\u00a0\/\/\u00a0first\u00a010\u00a0books\r\n\r\nfor\u00a0(HighlightEntry<Book>\u00a0he\u00a0:\u00a0booksHighlightPage.getHighlighted())\u00a0{\r\n\u00a0\u00a0\/\/\u00a0A\u00a0HighlightEntry\u00a0belongs\u00a0to\u00a0an\u00a0Entity\u00a0(Book)\u00a0and\u00a0may\u00a0have\u00a0multiple\u00a0highlighted\u00a0fields\u00a0(description)\r\n\u00a0\u00a0for\u00a0(Highlight\u00a0highlight\u00a0:\u00a0he.getHighlights())\u00a0{\r\n\u00a0\u00a0\u00a0\u00a0\/\/\u00a0Each\u00a0highlight\u00a0might\u00a0have\u00a0multiple\u00a0occurrences\u00a0within\u00a0the\u00a0description\r\n\u00a0\u00a0\u00a0\u00a0for\u00a0(String\u00a0snipplet\u00a0:\u00a0highlight.getSnipplets())\u00a0{\r\n\u00a0\u00a0\u00a0\u00a0\u00a0 \/\/ snipplet contains the highlighted text\r\n\u00a0\u00a0\u00a0\u00a0}\r\n\u00a0\u00a0}\r\n}<\/pre>\n
If you use this repository method to query for books whose description contains the string Treasure Island<\/i> a snipplet might look like this:<\/p>\n
<highlight>Treasure\u00a0Island<\/highlight>\u00a0is\u00a0a\u00a0tale\u00a0of\u00a0pirates\u00a0and\u00a0villains,\u00a0maps,\u00a0treasure\u00a0and\u00a0shipwreck,\u00a0and\u00a0is\u00a0perhaps\u00a0one\u00a0of\u00a0the\u00a0best\u00a0adventure\u00a0story\u00a0ever\u00a0written.<\/pre>\n
In this case\u00a0 Treasure Island<\/i> is located at the beginning of the description and is highlighted with the prefix and postfix defined in the @Highlight annotation. This additional markup can be used to mark query occurrences when the search results are shown to the user.<\/p>\n
Conclusion<\/h2>\n
Spring Data Solr provides a very simple way to integrate Solr into Spring applications. With the repository abstraction it follows the same design principle most other Spring Data project do. The only small drawback I faced while playing around with Spring Data Solr was the documentation that could be improved here and there.<\/p>\n