Introduzione ad Apache Lucene

1. Panoramica

Apache Lucene è un motore di ricerca full-text che può essere utilizzato da vari linguaggi di programmazione.

In questo articolo, proveremo a comprendere i concetti fondamentali della libreria e a creare una semplice applicazione.

2. Installazione di Maven

Per iniziare, aggiungiamo prima le dipendenze necessarie:

 org.apache.lucene lucene-core 7.1.0 

L'ultima versione può essere trovata qui.

Inoltre, per analizzare le nostre query di ricerca, avremo bisogno di:

 org.apache.lucene lucene-queryparser 7.1.0 

Controlla l'ultima versione qui.

3. Concetti fondamentali

3.1. Indicizzazione

In poche parole, Lucene utilizza una "indicizzazione invertita" dei dati: invece di mappare le pagine alle parole chiave, mappa le parole chiave alle pagine proprio come un glossario alla fine di qualsiasi libro.

Ciò consente risposte di ricerca più rapide, poiché cerca in un indice, invece di cercare direttamente nel testo.

3.2. Documenti

In questo caso, un documento è una raccolta di campi e ogni campo ha un valore associato ad esso.

Gli indici sono in genere costituiti da uno o più documenti e i risultati della ricerca sono gruppi di documenti che corrispondono meglio.

Non è sempre un documento di testo semplice, potrebbe anche essere una tabella di database o una raccolta.

3.3. Campi

I documenti possono contenere dati di campo, dove un campo è in genere una chiave che contiene un valore di dati:

title: Goodness of Tea body: Discussing goodness of drinking herbal tea...

Notare che qui titolo e corpo sono campi e possono essere cercati insieme o individualmente.

3.4. Analisi

Un'analisi sta convertendo il testo dato in unità più piccole e precise per facilitare la ricerca.

Il testo passa attraverso varie operazioni di estrazione di parole chiave, rimozione di parole comuni e punteggiatura, modifica delle parole in minuscolo, ecc.

A tale scopo, ci sono più analizzatori integrati:

  1. StandardAnalyzer : analizza in base alla grammatica di base, rimuove le parole chiave come "a", "an" ecc. Converte anche in minuscolo
  2. SimpleAnalyzer : interrompe il testo in base al carattere senza lettere e lo converte in minuscolo
  3. WhiteSpaceAnalyzer : interrompe il testo in base agli spazi bianchi

Sono disponibili anche più analizzatori da utilizzare e personalizzare.

3.5. Ricerca

Una volta che un indice è stato creato, possiamo cercare quell'indice usando una Query e un IndexSearcher. Il risultato della ricerca è in genere un set di risultati, contenente i dati recuperati.

Si noti che un IndexWritter è responsabile della creazione dell'indice e un IndexSearcher per la ricerca nell'indice.

3.6. Sintassi della query

Lucene fornisce una sintassi delle query molto dinamica e facile da scrivere.

Per cercare un testo libero, useremo semplicemente una stringa di testo come query.

Per cercare un testo in un campo particolare, useremmo:

fieldName:text eg: title:tea

Ricerche per intervallo:

timestamp:[1509909322,1572981321] 

Possiamo anche cercare utilizzando i caratteri jolly:

dri?nk

cercherebbe un singolo carattere al posto del carattere jolly "?"

d*k

cerca parole che iniziano con "d" e finiscono con "k", con più caratteri in mezzo.

uni*

troverà le parole che iniziano con "uni".

Possiamo anche combinare queste query e creare query più complesse. E includi operatori logici come AND, NOT, OR:

title: "Tea in breakfast" AND "coffee"

Maggiori informazioni sulla sintassi delle query qui.

4. Una semplice applicazione

Creiamo una semplice applicazione e indicizziamo alcuni documenti.

Innanzitutto, creeremo un indice in memoria e vi aggiungeremo alcuni documenti:

... Directory memoryIndex = new RAMDirectory(); StandardAnalyzer analyzer = new StandardAnalyzer(); IndexWriterConfig indexWriterConfig = new IndexWriterConfig(analyzer); IndexWriter writter = new IndexWriter(memoryIndex, indexWriterConfig); Document document = new Document(); document.add(new TextField("title", title, Field.Store.YES)); document.add(new TextField("body", body, Field.Store.YES)); writter.addDocument(document); writter.close(); 

Here, we create a document with TextField and add them to the index using the IndexWriter. The third argument in the TextField constructor indicates whether the value of the field is also to be stored or not.

Analyzers are used to split the data or text into chunks, and then filter out the stop words from them. Stop words are words like ‘a', ‘am', ‘is' etc. These completely depend on the given language.

Next, let's create a search query and search the index for the added document:

public List searchIndex(String inField, String queryString) { Query query = new QueryParser(inField, analyzer) .parse(queryString); IndexReader indexReader = DirectoryReader.open(memoryIndex); IndexSearcher searcher = new IndexSearcher(indexReader); TopDocs topDocs = searcher.search(query, 10); List documents = new ArrayList(); for (ScoreDoc scoreDoc : topDocs.scoreDocs) { documents.add(searcher.doc(scoreDoc.doc)); } return documents; }

In the search() method the second integer argument indicates how many top search results it should return.

Now let's test it:

@Test public void givenSearchQueryWhenFetchedDocumentThenCorrect() { InMemoryLuceneIndex inMemoryLuceneIndex = new InMemoryLuceneIndex(new RAMDirectory(), new StandardAnalyzer()); inMemoryLuceneIndex.indexDocument("Hello world", "Some hello world"); List documents = inMemoryLuceneIndex.searchIndex("body", "world"); assertEquals( "Hello world", documents.get(0).get("title")); }

Here, we add a simple document to the index, with two fields ‘title' and ‘body', and then try to search the same using a search query.

6. Lucene Queries

As we are now comfortable with the basics of indexing and searching, let us dig a little deeper.

In earlier sections, we've seen the basic query syntax, and how to convert that into a Query instance using the QueryParser.

Lucene provides various concrete implementations as well:

6.1. TermQuery

A Term is a basic unit for search, containing the field name together with the text to be searched for.

TermQuery is the simplest of all queries consisting of a single term:

@Test public void givenTermQueryWhenFetchedDocumentThenCorrect() { InMemoryLuceneIndex inMemoryLuceneIndex = new InMemoryLuceneIndex(new RAMDirectory(), new StandardAnalyzer()); inMemoryLuceneIndex.indexDocument("activity", "running in track"); inMemoryLuceneIndex.indexDocument("activity", "Cars are running on road"); Term term = new Term("body", "running"); Query query = new TermQuery(term); List documents = inMemoryLuceneIndex.searchIndex(query); assertEquals(2, documents.size()); }

6.2. PrefixQuery

To search a document with a “starts with” word:

@Test public void givenPrefixQueryWhenFetchedDocumentThenCorrect() { InMemoryLuceneIndex inMemoryLuceneIndex = new InMemoryLuceneIndex(new RAMDirectory(), new StandardAnalyzer()); inMemoryLuceneIndex.indexDocument("article", "Lucene introduction"); inMemoryLuceneIndex.indexDocument("article", "Introduction to Lucene"); Term term = new Term("body", "intro"); Query query = new PrefixQuery(term); List documents = inMemoryLuceneIndex.searchIndex(query); assertEquals(2, documents.size()); }

6.3. WildcardQuery

As the name suggests, we can use wildcards “*” or “?” for searching:

// ... Term term = new Term("body", "intro*"); Query query = new WildcardQuery(term); // ...

6.4. PhraseQuery

It's used to search a sequence of texts in a document:

// ... inMemoryLuceneIndex.indexDocument( "quotes", "A rose by any other name would smell as sweet."); Query query = new PhraseQuery( 1, "body", new BytesRef("smell"), new BytesRef("sweet")); List documents = inMemoryLuceneIndex.searchIndex(query); // ...

Notice that the first argument of the PhraseQuery constructor is called slop, which is the distance in the number of words, between the terms to be matched.

6.5. FuzzyQuery

We can use this when searching for something similar, but not necessarily identical:

// ... inMemoryLuceneIndex.indexDocument("article", "Halloween Festival"); inMemoryLuceneIndex.indexDocument("decoration", "Decorations for Halloween"); Term term = new Term("body", "hallowen"); Query query = new FuzzyQuery(term); List documents = inMemoryLuceneIndex.searchIndex(query); // ...

We tried searching for the text “Halloween”, but with miss-spelled “hallowen”.

6.6. BooleanQuery

Sometimes we might need to execute complex searches, combining two or more different types of queries:

// ... inMemoryLuceneIndex.indexDocument("Destination", "Las Vegas singapore car"); inMemoryLuceneIndex.indexDocument("Commutes in singapore", "Bus Car Bikes"); Term term1 = new Term("body", "singapore"); Term term2 = new Term("body", "car"); TermQuery query1 = new TermQuery(term1); TermQuery query2 = new TermQuery(term2); BooleanQuery booleanQuery = new BooleanQuery.Builder() .add(query1, BooleanClause.Occur.MUST) .add(query2, BooleanClause.Occur.MUST) .build(); // ...

7. Sorting Search Results

We may also sort the search results documents based on certain fields:

@Test public void givenSortFieldWhenSortedThenCorrect() { InMemoryLuceneIndex inMemoryLuceneIndex = new InMemoryLuceneIndex(new RAMDirectory(), new StandardAnalyzer()); inMemoryLuceneIndex.indexDocument("Ganges", "River in India"); inMemoryLuceneIndex.indexDocument("Mekong", "This river flows in south Asia"); inMemoryLuceneIndex.indexDocument("Amazon", "Rain forest river"); inMemoryLuceneIndex.indexDocument("Rhine", "Belongs to Europe"); inMemoryLuceneIndex.indexDocument("Nile", "Longest River"); Term term = new Term("body", "river"); Query query = new WildcardQuery(term); SortField sortField = new SortField("title", SortField.Type.STRING_VAL, false); Sort sortByTitle = new Sort(sortField); List documents = inMemoryLuceneIndex.searchIndex(query, sortByTitle); assertEquals(4, documents.size()); assertEquals("Amazon", documents.get(0).getField("title").stringValue()); }

Abbiamo provato a ordinare i documenti recuperati in base ai campi del titolo, che sono i nomi dei fiumi. L'argomento booleano del costruttore SortField serve per invertire l'ordinamento.

8. Rimuovere i documenti dall'indice

Proviamo a rimuovere alcuni documenti dall'indice basato su un dato Termine:

// ... IndexWriterConfig indexWriterConfig = new IndexWriterConfig(analyzer); IndexWriter writer = new IndexWriter(memoryIndex, indexWriterConfig); writer.deleteDocuments(term); // ...

Lo testeremo:

@Test public void whenDocumentDeletedThenCorrect() { InMemoryLuceneIndex inMemoryLuceneIndex = new InMemoryLuceneIndex(new RAMDirectory(), new StandardAnalyzer()); inMemoryLuceneIndex.indexDocument("Ganges", "River in India"); inMemoryLuceneIndex.indexDocument("Mekong", "This river flows in south Asia"); Term term = new Term("title", "ganges"); inMemoryLuceneIndex.deleteDocument(term); Query query = new TermQuery(term); List documents = inMemoryLuceneIndex.searchIndex(query); assertEquals(0, documents.size()); }

9. Conclusione

Questo articolo è stata una rapida introduzione per iniziare con Apache Lucene. Inoltre, abbiamo eseguito varie query e ordinato i documenti recuperati.

Come sempre il codice per gli esempi può essere trovato su Github.