Opis Problemu

Do zaindeksowania jest pewna lista produktów. Produkty jednak mogą być łączone w grupy. Dodatkowo w grupie, w kolejnych elementach mogą być pominięte te dane, które w elemencie wcześniej zostały zdefiniowane. Przykładowa struktura (nieistotne informacje pominąłem dla czytelności):

<products>
  <product>
    <id>1</id>
    <name>Product 1</name>
  </product>
  <product>
    <id>2</id>
    <name>Product 2</name>
  </product>
  <group>
    <product>
      <id>3</id>
      <name>Product 3 and 4</name>
    </product>
    <product>
      <id>4</id>
    </product>
  </group>
</products>

Rozwiązanie

Rozwiązanie polega na zdefiniowaniu – jak zawszę – elementu „entity” w sposób następujący:

<entity processor="XPathEntityProcessor"
    forEach="/products/product | /products/group/product">
  <field column="id" xpath="//id" />
  <field column="name" xpath="//name" commonField="true" />
</entity>

Wyjaśnienie

Dzięki takiej konstrukcji „forEach” do przetworzenia dostaną się zarówno produkty nie należące do grupy, jak i te w grupach. Istotnym atrybutem pola jest „commonField”. Informuje on DIH, że jeśli w danym rekordzie nie jest zdefiniowane to pole, należy je pobrać z rekordu poprzedniego.

Podane rozwiązanie ma parę ograniczeń, np. pierwszy element w grupie powinien mieć zdefiniowane pole „name” oraz ważna jest kolejność produktów, natomiast w moim przypadku pokrywało się to dokładnie ze specyfikacją dostarczonego pliku importu.

Mając pod ręką przykładowe dane z albumami i wykonawcami postanowiłem pokazać mój sposób postępowania w takich wypadkach. Dla uproszczenia i przejrzystości zakładam, że po pierwszym zaimportowaniu, danych może tylko ubywać.

Dane testowe

Moje dane testowe mieszczą się bazie PostgreSQL w tabeli zdefiniowanej następująco:

Table "public.albums"
Column |  Type   |                      Modifiers
--------+---------+-----------------------------------------------------
id     | integer | not null default nextval('albums_id_seq'::regclass)
name   | text    | not null
author | text    | not null
Indexes:
"albums_pk" PRIMARY KEY, btree (id)

W tabeli znajduje się 825661 rekordów.

Instalacja testowa

Do testów użyłem instancji SOLR posiadającej następującą charakterystykę:

Definicja w schema.xml:

<fields>
<field name="id" type="string" indexed="true" stored="true" required="true" />
<field name="album" type="text" indexed="true" stored="true" multiValued="true"/>
<field name="author" type="text" indexed="true" stored="true" multiValued="true"/>
</fields>
<uniqueKey>id</uniqueKey>
<defaultSearchField>album</defaultSearchField>

Definicja DIH w solrconfig.xml:

<requestHandler name="/dataimport" class="org.apache.solr.handler.dataimport.DataImportHandler">
<lst name="defaults">
<str name="config">db-data-config.xml</str>
</lst>
</requestHandler>

I plik DIH db-data-config.xml:

<dataConfig>
<dataSource driver="org.postgresql.Driver" url="jdbc:postgresql://localhost:5432/shardtest" user="solr" password="secret" />
<document>
<entity name="album" query="SELECT * from albums">
<field column="id" name="id" />
<field column="name" name="album" />
<field column="author" name="author" />
</entity>
</document>
</dataConfig>

Przed naszym testem zaimportowałem wszystkie dane z tabeli albums.

Usuwanie danych

Patrząc na tabelę widać, że gdy usuniemy rekord, ginie on bez śladu i jedynym sposobem aktualizacji naszego indeksu byłoby porównanie identyfikatorów dokumentów w indeksie z identyfikatorami w bazie i wyrzucenie tych, które w bazie już nie istnieją. Wolne i niewygodne. Innym sposobem jest dodatnie kolumny deleted_at: zamiast kasowania fizycznie rekordu, uzupełniamy tylko tę kolumnę. DIH może wtedy pobrać wszystkie rekordy z ustawioną datą późniejszą od ostatniego indeksowania. Wadą tego rozwiązania może by konieczność modyfikacji aplikacji by uwzględniały tak „skasowane” rekordy.

Ja zastosuje inne rozwiązanie, przeźroczyste dla aplikacji. Tworzymy nową tabelę:

CREATE TABLE deletes
(
id serial NOT NULL,
deleted_id bigint,
deleted_at timestamp without time zone NOT NULL,
CONSTRAINT deletes_pk PRIMARY KEY (id)
);

Do tej tabeli automagicznie będziemy dopisywać identyfikatory tych elementów, które zostały usunięte z tabeli albums oraz informacje kiedy zostały usunięte.

Teraz dodamy jeszcze funkcję:

CREATE OR REPLACE FUNCTION insert_after_delete()
RETURNS trigger AS
$BODY$BEGIN
IF tg_op = 'DELETE' THEN
INSERT INTO deletes(deleted_id, deleted_at)
VALUES (old.id, now());
RETURN old;
END IF;
END$BODY$
LANGUAGE plpgsql VOLATILE;

oraz trigger:

CREATE TRIGGER deleted_trg
BEFORE DELETE
ON albums
FOR EACH ROW
EXECUTE PROCEDURE insert_after_delete();

Sprawdzamy działanie

Zgodnie z planem, każdy usunięty wpis w tabeli albums powinien skutkować uzupełnieniem tabeli
deletes. Sprawdźmy więc. Usuwamy parę rekordów:

=> DELETE FROM albums where id < 37;
DELETE 2
=> SELECT * from deletes;
id | deleted_id |         deleted_at
----+------------+----------------------------
26 |         35 | 2010-12-23 13:53:18.034612
27 |         36 | 2010-12-23 13:53:18.034612
(2 rows)

Czyli baza działa.

Uzupełniamy plik konfiguracyjny DIH tak, by entity było zdefiniowane następująco:

<entity name="album" query="SELECT * from albums"
  deletedPkQuery="SELECT deleted_id as id FROM deletes WHERE deleted_at > '$'{dataimporter.last_index_time}'">

Dzięki temu przy imporcie przyrostowym DIH użyje atrybutu deletedPkQuery by pobrać identyfikatory tych dokumentów, które należy usunąć.

Sprytny czytelnik pewnie zacznie się zastanawiać, czy na pewno potrzebna jest nam kolumna z datą usunięcia rekordu. Przecież możemy usunąć wszystkie rekordy znalezione w tabeli deleted a następnie skasować zawartość tej tabeli. Teoretycznie to prawda, ale w przypadku problemu z serwerem indeksującym SOLR w naszym wypadku łatwo zastąpić go innym – jego stopień synchronizacji z bazą nie jest bardzo istotny – po prostu za następnym importem przyrostowym nastąpi synchronizacja z bazą. W opcji z kasowaniem zawartości deletes takie możliwości nie ma.

Wykonujemy teraz import przyrostowy wywołując adres: /solr/dataimport?command=delta-import
W logach powinna pojawić się linia podobna do tej:
INFO: {delete=[35, 36],optimize=} 0 2
Co oznacza, że DIH poprawnie usunął z indeksu te dokumenty, które usunęliśmy wcześniej z bazy.

W przykładach użyta została baza PostgeSQL zawierająca dane polskiej wikipedii. Testowa instancja solr została zdefiniowana jako rdzeń „wikipedia” i dostępna była pod adresem:

http://localhost:8983/solr/wikipedia/admin/

Konfiguracja solrconfig.xml

Konfiguracja sprowadza się do dodania dodatkowego requestHandlera. Parametr: config określa plik konfiguracyjny, w którym znajduje się definicja źródła danych.

 <requestHandler name="/dataimport" class="org.apache.solr.handler.dataimport.DataImportHandler">
  <lst name="defaults">
   <str name="config">db-data-config.xml</str>
  </lst>
</requestHandler>

Dzięki takiej definicji zyskujemy możliwość wywoływania adresu HTTP obsługującego import:

• /dataimport – w celu uzyskania aktualnego statusu
• /dataimport?command=reload-config – w celu ponownego odczytania konfiguracji
• /dataimport?command=full-import – w celu zlecenia rozpoczęcia pełnego indeksowania danych
• /dataimport?command=delta-import – w celu zlecenia rozpoczęcia indeksowania przyrostowego

(dla mojej konfiguracji pełen adres to: http://localhost:8983/solr/wikipedia/dataimport)

Powyżej widzimy dwie możliwości importowania danych: import pełny i przyrostowy.

Pełny import danych polega na każdorazowym wczytaniu wszystkich danych, które powinny znaleźć się w indeksie, podczas gdy import przyrostowy oznacza tylko dodanie i aktualizację w indeksie tych danych, które zmieniły się od ostatniego indeksowania. Pełny import zwykle trwa znacznie dłużej stąd prosty wniosek: jeśli czas pełnego indeksowania nie jest dla nas problemem – prawdopodobnie nie warto zawracać sobie głowy konfiguracją indeksowania przyrostowego, zwłaszcza, że nakłada ono  dodatkowe wymagania na strukturę źródła danych.

Warto zaznaczyć, że pełny import domyślnie rozpoczyna się od usunięcia istniejącego indeksu. Istnieje możliwość uniknięcia takiego zachowania poprzez dodanie parametru: clean=false.

Konfiguracja źródła danych

Konfiguracja polega na zdefiniowaniu zapytań pozwalających solr na pobieranie danych do indeksowania i zawiera się w pliku określonym przy definicji handlera (u nas: db-data-config.xml) W tym wpisie zaczniemy od zdefiniowania pełnego importu. Następnie, w kolejnej części artykułu rozbudujemy go o możliwość importowania przyrostowego.

Pełny import

<dataConfig>
  <dataSource driver="org.postgresql.Driver"
     url="jdbc:postgresql://localhost:5432/wikipedia"
     user="wikipedia"
     password="secret" />
  <document>
    <entity name="page" query="SELECT page_id, page_title from page">
      <field column="page_id" name="id" />
      <field column="page_title" name="name" />
      <entity name="revision" query="select rev_id from revision where rev_page=${page.page_id}">
        <entity name="pagecontent" query="select old_text from pagecontent where old_id=${revision.rev_id}">
          <field column="old_text" name="text" />
        </entity>
      </entity>
   </entity>
  </document>
</dataConfig>

Jak widzimy definicja źródła składa się z opisu sposobu połączenia do baz danych oraz opisu indeksowanego dokumentu. Import następuje zgodnie z następującym algorytmem:

1. Usuwany jest stary indeks (jeśli nie użyto parametru clean=false)
2. Solr po wywołaniu komendy indeksowania nawiązuje połączenie do bazy danych.
3. Definiowany jest kursor bazodanowy wykorzystujący zapytanie określone w argumencie „query” w głównej encji
4. Pobierana jest porcja danych
5. Dla każdego pobranego rekordu definiowane są zmienne postaci <nazwa encji>.<zwracana kolumna>, dzięki czemu do zwróconych wartości można odwołać się w encjach zagnieżdżonych
6. Wykonywane są zapytania z encji zagnieżdżonych
7. Encja może zawierać definicje pól. Dzięki temu Solr jest w stanie określić mapowanie kolumny z wyniku na pole dokumentu zdefiniowane w schema.xml
8. Dokument stworzony dzięki wartościom zwróconych przez zapytania jest dodawany do indeksu
9. Jeśli kursor posiada kolejne wyniki następuje skok do punktu 4.
10. Następuje zapisanie danych do pliku dataimport.properties, dane zostają zatwierdzone (commit) i wykonywana jest optymalizacja indeksu

Po uruchomieniu solr i wejściu na stronę: http://localhost:8983/solr/wikipedia/dataimport pojawiła sie odpowiedź:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <lst name="responseHeader">
    <int name="status">0</int>
    <int name="QTime">0</int>
  </lst>
  <lst name="initArgs">
    <lst name="defaults">
      <str name="config">db-data-config.xml</str>
    </lst>
  </lst>
  <str name="status">idle</str>
  <str name="importResponse"/>
  <lst name="statusMessages"/>
  <str name="WARNING">This response format is experimental.  It is likely to change in the future.</str>
</response>

Uwagę zwraca wpis: status: idle. Oznacza to, że nasz importer jest gotowy do pracy. W innym przypadku (np. Błąd poprawności XML konfiguracyjnego) dostaniemy opis wyjątku. Niestety na tym etapie nie są wykrywane jeszcze błędy związane np. z niewłaściwą definicją połączenia do bazy lub braku sterownika JDBC.

Wchodzimy więc na stronę: http://localhost:8983/solr/wikipedia/dataimport?command=full-import

To co powinniśmy otrzymać, to podobny jak wyżej XML. Jednak po ponownym wejściu na stronę: http://localhost:8983/solr/wikipedia/dataimport dostajemy już inny wynik.

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <lst name="responseHeader">
    <int name="status">0</int>
    <int name="QTime">0</int>
  </lst>
  <lst name="initArgs">
    <lst name="defaults">
      <str name="config">db-data-config.xml</str>
    </lst>
  </lst>
  <str name="status">busy</str>
  <str name="importResponse">A command is still running...</str>
  <lst name="statusMessages">
    <str name="Time Elapsed">0:1:15.460</str>
    <str name="Total Requests made to DataSource">39547</str>
    <str name="Total Rows Fetched">59319</str>
    <str name="Total Documents Processed">19772</str>
    <str name="Total Documents Skipped">0</str>
    <str name="Full Dump Started">2010-10-03 14:28:00</str>
  </lst>
  <str name="WARNING">This response format is experimental.  It is likely to change in the future.</str>
</response>

Czyli importer pracuje.

Po pewnym czasie, zależnym od ilości indeksowanych danych i szybkości komputera otrzymamy:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <lst name="responseHeader">
    <int name="status">0</int>
    <int name="QTime">0</int>
  </lst>
  <lst name="initArgs">
    <lst name="defaults">
      <str name="config">db-data-config.xml</str>
    </lst>
  </lst>
  <str name="status">idle</str>
  <str name="importResponse"/>
  <lst name="statusMessages">
    <str name="Total Requests made to DataSource">2118645</str>
    <str name="Total Rows Fetched">3177966</str>
    <str name="Total Documents Skipped">0</str>
    <str name="Full Dump Started">2010-10-03 14:28:00</str>
    <str name="">Indexing completed. Added/Updated: 1059322 documents. Deleted 0 documents.</str>
    <str name="Committed">2010-10-03 14:55:20</str>
    <str name="Optimized">2010-10-03 14:55:20</str>
    <str name="Total Documents Processed">1059322</str>
    <str name="Time taken ">0:27:20.325</str>
  </lst>
  <str name="WARNING">This response format is experimental.  It is likely to change in the future.</str>
</response>

Jak widzimy indeksacja zakończyła się sukcesem.

W kolejnym odcinku spróbujemy dodać możliwość importowania przyrostowego.

Sposobów na zaimportowanie danych jest kilka:

• Update Handler
• Cvs Request Handler
• Data Import Handler
• Extracting Request Handler (Solr Cell)
• Skorzystać z bibliotek klienckich (np. Solrj)
• Apache Connectors Framework (dawniej Lucene Connectors Framework)
• Apache nutch

Do tego można jeszcze dodać streaming, jako sposób przesyłania danych. Jak widać, panuje tutaj pewne zamieszanie i ciężko na pierwszy rzut oka podać najlepszą metodę do zastosowania w konkretnym wypadku.

Update Handler

Chyba najbardziej popularna metoda, ze względu na prostotę. Wymaga przygotowania odpowiedniego XML oraz przesłanie go poprzez HTTP do serwera Solr. Umożliwia podbijanie ważności dokumentów i pojedynczych pól.

CSV Request Handler

W przypadku, gdy dane wejściowe mamy w postaci CSV (Coma Separated Values) lub TSV (Tab Separated Values) ta opcja może być najwygodniejsza. Niestety, w przeciwieństwie do Update Handler, nie ma możliwości podbijania ważności.

Data Import Handler

Ta metoda jest mniej popularna, wymaga dodatkowej, czasem dość skomplikowanej konfiguracji, jednak pozwala na bezpośrednie podpięcie się do źródła danych. Dzięki temu nie wymaga żadnych dodatkowych skryptów eksportujących dane ze źródła i konwertujących je na format wymagany przez Solr. Standardowo jest dostępna integracja z bazami danych (w oparciu o JDBC), źródłami udostępniającymi XML (np. RSS), email (poprzez protokół IMAP), dokumenty obsługiwane przez projekt apache Tika (np. Openoffice, word, rtf, html i wiele innych). Dodatkowo można dopisywać własne źródła i transformacje.

Extracting Request Handler (Solr Cell)

Wyspecjalizowany handler do indeksowania treści dokumentów przechowywanych w plikach o różnych formatach. Lista obsługiwanych formatów jest dość szeroka a do indeksowania wykorzystywany jest projekt apache Tika. Wadą tego rozwiązania jest konieczność budowania dodatkowych rozwiązań dostarczających do SOLR namiary na dokument i informacje o identyfikatorze dokumentu oraz brak możliwości uzupełniania dokumentów o dodatkowe, zewnętrzne względem dokumentu, metadane.

Biblioteki klienckie

Solr udostępnia biblioteki klienckie do wielu języków programowania. Ich możliwości różnią się miedzy sobą, natomiast w przypadku, gdy dane są generowane na bieżąco przez aplikację i czas, po którym te dane muszą być dostępne do wyszukiwania jest bardzo mały, indeksowanie w ten sposób często jest jedyną dostępną opcją.

Apache Connectors Framework

ACF jest to relatywnie nowy projekt, który szerszej publiczności objawił się na początku 2010 roku. Projekt początkowo był wewnętrznym projektem prowadzonym przez firmę MetaCarta, został przekazany społeczności open source i w chwili obecnej rozwijany w ramach inkubatora apache. W założeniu jest to system, który dzięki szeregowi wtyczek pozwala „wyklikać” połączenie ze źródłem danych. W chwili obecnej brak jest opublikowanych wersji, ale sam system już warty jest zainteresowania w przypadku konieczności integracji z takimi systemami jak: FileNet P8 (IBM), Documentum (EMC), LiveLink (OpenText), Patriarch (Memex), Meridio (Autonomy), Windows shares (Microsoft) i SharePoint (Microsoft).

Apache nutch

Nutch to zasadzie to oddzielny projekt prowadzony przez Apache (wcześniej w ramach Apache Lucene). Dla osoby zajmującej się serwerem Solr jest on o tyle ciekawy, że pozwala na taką konfigurację, która umożliwia pobieranie stron WWW i indeksowanie ich poprzez Solr.

Słowo o streamingu

Streaming oznacza możliwość powiadomienia Solr,  skąd pobrać dane do zindeksowania. Pozwala to na uniknięcie zbędnego przesyłania danych przez sieć, jeśli dane znajdują się na zasobie lokalnym względem serwera indeksującego, lub podwójnego przesyłania danych (ze źródła do importera, z importera do Solra).

I słowo o bezpieczeństwie

Solr z założenia jest przewidziany do stosowania w architekturze zakładającej pracę w środowisku bezpiecznym. Bardzo ważne jest jednak zwrócenie uwagi na to, kto i jakie polecenia jest w stanie wykonywać. O ile zwracane dane można w miarę prosto ograniczyć, poprzez wymuszenie stosowania filtrów w definicji handlerów, o tyle w przypadku indeksowania nie jest to już takie proste. W szczególności niebezpieczny wydaje się być Solr Cell – nie tylko pozwoli na odczytanie dowolnego pliku, do którego ma dostęp Solr (np. pliki z hasłami), ale dodatkowo da możliwość atakującemu na ich wygodne przeszukiwanie w celu uzyskania przydatnych informacji

Inne opcje

Powyżej starałem się uwzględnić opcje, które nie wymagają dodatkowej pracy. Problemem może być definicja tej dodatkowej pracy, bo czasem łatwiej napisać dodatkową wtyczkę, niż przebijać się przez niezliczone opcje konfiguracyjne czy tworzyć gigantyczne XMLe. Dlatego też w wyborze metod kierowałem się własnym wyczuciem, co skutkowało pominięciem kilku sposobów (np. pobieranie danych ze stron WWW za pomocą Apache Droids lub Heritrixa, czy rozwiązania oparte o Open Pipeline lub Open Pipe).

Na pewno w tym krótkim artykule udało mi się pominąć jakieś ciekawe sposoby. Jeśli tak, proszę o komentarze, chętnie uaktualnię ten wpis