Sphinx, “the Russian black magic” / 1

Per queste caratteristiche, in particolare la velocità di indicizzazione e ricerca su basi dati di parecchie decine di Gb (BoardReader ad esempio indicizza più di un miliardo di post per circa 1.5Tb di dati), Sphinx è stato definito Russian black magic. La definizione è meno azzardata di quanto sembri: come tutte le arti magiche che si rispettano Sphinx è abbastanza esoterico, e imparare ad utilizzarlo con successo richiede tempo e costanza, per recuperare frammenti di informazione indispensabili dal forum degli utilizzatori e sperimentarne le funzionalità.

Questa serie di articoli su Sphinx vuole quindi essere una introduzione a questo eccezionale motore di ricerca, illustrandone l'installazione e l'utilizzo attraverso una serie di esempi pratici, e fornendo i dati e il codice per eseguirli. La serie è composta da tre articoli:

• installazione e utilizzo di base (questo articolo)
• funzionalità avanzate di indicizzazione e ricerca
• benchmark di utilizzo, in cui Sphinx verrà comparato con Solr e i motori di full text search di MySQL e PostgreSQL

Prerequisiti

Per gli esempi di questa serie di articoli utilizzeremo

• MySQL, che è la base dati più diffusa sui servizi di shared hosting e probabilmente la più utilizzata per lo sviluppo di applicazioni web, specialmente in PHP
• Python 2.5 (o 2.4) o, in alternativa, PHP 4.x o 5.x
• la versione di sviluppo di Sphinx (0.9.8-x), che offre alcune funzionalità non presenti nella versione stabile (0.9.7) e dovrebbe venire comunque rilasciata in versione definitiva fra non molto
• se volete provare le funzionalità di stemming per la lingua italiana (non è indispensabile, soprattutto per questo primo articolo), una versione recente di libstemmer del progetto Snowball

Se siete su Linux/Unix vi servirà anche un compilatore C++, e gli header e le librerie necessarie per compilare Sphinx. Gli esempi che troverete sotto presuppongono che sphinx sia stato compilato con il supporto a MySQL (--with-mysql), e sia installato in /opt/sphinx/. Se usate PostgreSQL e/o avete installato Sphinx in una cartella diversa, aggiustate le istruzioni SQL e i percorsi degli esempi di conseguenza.

Se invece siete su Windows potete utilizzare gli eseguibili rilasciati da Andrew e quelli ufficiali di MySQL, e dovrete ovviamente sostituire i percorsi Unix con quelli della vostra installazione.

I dati utilizzati per gli esempi di questo articolo sono un dump semplificato degli articoli pubblicati su Qix.it, dato che sono una buona base per illustrare le funzionalità di Sphinx, non hanno problemi di copyright (non per me, almeno), e sono già disponibili in formato SQL. Potete scaricarli qui e, dopo aver creato un nuovo database sphinx su MySQL, caricarli con i comandi qui sotto.

    $ mysql --user=root -p
    mysql> CREATE DATABASE sphinx CHARACTER SET utf8 COLLATE utf8_general_ci;
    mysql> GRANT ALL on sphinx.* TO sphinx@localhost IDENTIFIED BY 'sphinx';
    mysql> \q
    $ cat dataset.sql |mysql --user=sphinx -p sphinx
  

Se siete su Windows, sostituite il comando type a cat.

Architettura e configurazione

L'architettura di Sphinx è piuttosto semplice:

• un eseguibile per l'indicizzazione, indexer, che viene di solito lanciato periodicamente via cron
• un demone TCP, searchd, che accetta le richieste, estrae i risultati e li restituisce ai client
• un eseguibile, search, con cui effettuare ricerche da linea di comando
• delle librerie client per vari linguaggi che permettono di effettuare ricerche utilizzando searchd

Gli eseguibili e il demone leggono le proprie impostazioni da sphinx.conf, un file di configurazione in formato pseudo-shell che definisce le caratteristiche delle fonti dati, degli indici disponibili, e i parametri di esecuzione di indexer e searchd.

Iniziamo quindi la definizione del file di configurazione che utilizzeremo per gli esempi di questo articolo, specificando la prima fonte di dati.

Definizione di una fonte di dati

Le fonti di dati (source) descrivono dove e come recuperare i dati da indicizzare, e come indicizzarli (per la ricerca, come attributi per il raggruppamento, ecc.). Le tipologie di source accettate da Sphinx sono tre: MySQL, PostgreSQL, e una fonte generica definita XML pipe. Le fonti SQL sono le più sofisticate, dato che offrono diversi parametri per alleggerire il carico sul DB o definire fonti incrementali, che esamineremo in dettaglio nel secondo articolo di questa serie. La fonte XML è più semplice, e serve come “fonte universale” in quelle situazioni dove non sia disponibile una base dati compatibile con Sphinx. Per questo articolo utilizzeremo, come detto in precedenza, una base dati MySQL e la relativa tipologia di source in Sphinx.

Per definire una fonte dobbiamo avere chiaro il modello della base dati, e ovviamente sapere cosa ci interessa indicizzare. La base dati di esempio mette a disposizione tre tabelle (ne arriveranno altre per la seconda parte dell'articolo):

    +-------------------+
    | Tables_in_sphinx  |
    +-------------------+
    | sphinx_entry      |
    | sphinx_tag        |
    | sphinx_entry_tags |
    +-------------------+
  

Le tabelle contengono — ovviamente — i post di Qix, le singole tag utilizzate, e le relazioni tra post e tag. Esaminiamo brevemente la struttura delle singole tabelle, nell'ordine in cui sono riportate sopra:

    +-----------------+--------------+
    | Field           | Type         |
    +-----------------+--------------+
    | id              | int(11)      |
    | slug            | varchar(255) |
    | author_id       | int(11)      |
    | updated         | datetime     |
    | title           | varchar(255) |
    | comment_count   | int(11)      |
    | trackback_count | int(11)      |
    | body            | longtext     |
    +-----------------+--------------+
    +-------+-------------+
    | Field | Type        |
    +-------+-------------+
    | id    | int(11)     |
    | slug  | varchar(50) |
    | name  | varchar(50) |
    +-------+-------------+
    +----------+---------+
    | Field    | Type    |
    +----------+---------+
    | id       | int(11) |
    | entry_id | int(11) |
    | tag_id   | int(11) |
    +----------+---------+
  

Come accennato, i dati indicizzati da sphinx possono essere divisi in due macrocategorie: quelli utilizzati per la ricerca full text vera e propria; e i dati che servono per limitare l'ambito della ricerca e ordinare o raggruppare i risultati, che Sphinx definisce “attributi”. Mentre per i primi non ci sono grandi limitazioni — devono ovviamente essere campi testo — per gli attributi Sphinx limita la scelta a dati di tipo numerico (interi o float nell'ultima versione) e date. La limitazione è dovuta all'architettura degli indici e ad esigenze di prestazioni, e gli eventuali problemi di compatibilità con strutture dati esistenti (ad esempio tabelle senza una ID numerica) possono essere facilmente aggirati, come vedremo negli articoli successivi.

Tornando al nostro esempio, descriviamo una prima semplice sorgente di dati che ci permette di:

• effettuare ricerche full text sul contenuto e il titolo dei post
• limitare, ordinare, o raggruppare i risultati per data di pubblicazione, autore, numero di commenti, tag

Creiamo quindi un nuovo file sphinx.conf nella cartella etc sotto il percorso dove abbiamo installato Sphinx (ad es. /opt/sphinx/etc/sphinx.conf), e utilizziamo come riferimento i commenti alla configurazione di esempio rilasciata insieme ai sorgenti (/opt/sphinx/etc/sphinx.conf.dist). Iniziamo con la definizione della connessione a MySQL, utilizzando se possibile il socket invece della connessione TCP per il collegamento, e specificando il charset (nel nostro caso UTF-8):

    source qix_1 {
    type = mysql
    sql_host = localhost
    sql_port = 3306
    sql_sock = /var/run/mysqld/mysqld.sock # opzionale
    sql_db = sphinx
    sql_user = sphinx
    sql_pass = sphinx
    sql_query_pre = SET NAMES utf8
  

Come potete notare, il comando sql_query_pre con cui impostiamo il charset accetta una o — ripetendolo — più query generiche. Potremmo quindi usarlo anche per altri scopi: ad esempio per impostare un lock che impedisca a due processi di indicizzazione di girare contemporaneamente, per innescare una transazione, o per manipolare un contatore che ci permetta di implementare l'indicizzazione incrementale. Vedremo alcune di queste tecniche nel secondo articolo di questa serie.

Definito il collegamento a MySQL, indichiamo a Sphinx come recuperare i dati da indicizzare. La query deve rispettare alcune semplici condizioni: il primo campo deve essere l'id numerico che identifica univocamente ogni record; gli attributi devono essere interi a 32 bit non negativi (o float nell'ultima versione); i campi non dichiarati come id o attributi (vedremo sotto come) vengono indicizzati come full text. La nostra query quindi sarà:

    sql_query = \
    SELECT \
    id, author_id, unix_timestamp(updated) as updated, \
    comment_count + trackback_count as num_comments, \
    title, body \
    FROM sphinx_entry
  

Definita la query principale, indichiamo a sphinx quali sono gli attributi che ci serviranno per filtrare o raggruppare i risultati delle ricerche. Gli attributi possono essere definiti come

• sql_attr_uint, per cui Sphinx usa interi a 32 bit
• sql_attr_bool, attributi boolean che richiedono meno spazio
• sql_attr_timestamp, date in formato Unix
• sql_attr_str2ordinal, attributi in formato stringa che vengono ordinati da Sphinx in memoria durante l'indicizzazione e convertiti in interi che rispecchiano l'ordinamento, servono per il sorting dei risultati
• sql_attr_float, attributi in formato float

Definiamo quindi gli attributi estratti dalla query SQL:

    sql_attr_uint = author_id
    sql_attr_timestamp = updated
    sql_attr_uint = num_comments
  

L'ultima operazione che ci rimane per completare la definizione della sorgente di dati è recuperare le tag, e definirle come attributo multivalore (MVA, Multi-Valued Attribute), una funzionalità introdotta con la versione 0.9.8 di Sphinx. Gli attributi MVA, come quelli semplici visti sopra, possono essere di tipo uint o timestamp e possono venire estratti in due modi:

• field, uno dei campi della query principale viene utilizzato per recuperare i valori di un singolo record; questo metodo non è ancora supportato (cf. sphinx-0.9.8-svn-rxxxx/src/indexer.cpp intorno alla riga 340), ma dovrebbe tornare utile per quei tipi di attributi che è più conveniente recuperare con istruzioni tipo GROUP_CONCAT, o che sono salvati in campi singoli
• query, una query SQL che restituisce coppie di valori costituite dalla id del record principale (nel nostro caso i singoli post) e dalla id dell'attributo (nel nostro caso le tag distinte dei post)

La definizione del nostro attributo MVA, le tag, è piuttosto semplice:

    sql_attr_multi = uint tag from query; \
    SELECT entry_id, tag_id FROM sphinx_entry_tags
  

Ci sono altre istruzioni che possono essere definite per una sorgente di dati, ne vedremo alcune nella seconda parte di questa serie quando ci occuperemo di indicizzazione avanzata. Per adesso manca una sola istruzione, che serve all'eseguibile da linea di comando search per recuperare i dati delle singole entry contenute nei risultati della ricerca:

    sql_query_info = SELECT * FROM sphinx_entry WHERE id=$id
    }
  

Definita la fonte di dati, passiamo a vedere come configurare l'indice che la utilizza.

Definizione di un indice

La definizione dell'indice serve a Sphinx per sapere quali parametri fisici utilizzare (file e percorsi, utilizzo della memoria per gli attributi, ecc.) e come manipolare i dati forniti dalla sorgente. Anche per l'indice, in questo articolo esamineremo solo le istruzioni fondamentali, riservando al secondo articolo della serie le istruzioni destinate ad utilizzi avanzati.

Cominciamo con il definire il nome dell'indice, la fonte di dati utilizzata (una fonte di dati può ovviamente essere utilizzata da più indici), il percorso per i file fisici generati, e il metodo di storage degli attributi (nel nostro caso in un file separato, data la dimensione limitata del dataset utilizzato)

    index qix_1 {
    source = qix_1
    path = /opt/sphinx/var/data/qix1
    docinfo = extern
  

Le altre istruzioni che ci interessano a questo livello riguardano il trattamento dei dati ricevuti:

• morphology definisce lo stemmer da utilizzare, o in alternativa se farne a meno; gli stemmer inclusi con Sphinx sono stem_en per la lingua inglese, stem_ru per il russo, stem_enru che combina inglese e russo, soundex e metaphone che utilizzano algoritmi fonetici; se Sphinx è stato compilato con il supporto per libstemmer, sono disponibili inoltre tutti gli stemmer supportati da Snowball
• stopwords definisce il percorso della lista opzionale di parole da escludere dall'indicizzazione (ad esempio congiunzioni, articoli, ecc.), che possono essere ottenute facendo generare a indexer una lista della frequenza dei termini di una o più fonti di dati (indexer --buildstops o --buildfreqs)
• synonims definisce il percorso della lista opzionale di sinonimi
• min_word_len definisce la lunghezza minima delle parole da indicizzare, con il valore 1 vengono indicizzate tutte le parole (ed evitati problemi con ricerche per frasi, tipo “e lui disse”)
• charset_type definisce se l'encoding dei dati deve essere single byte (ad esempio ISO-8859-1) o UTF-8
• charset_table definisce una tabella di conversione dei caratteri, tipicamente per mappare caratteri accentati sui loro equivalenti traslitterati (ad es. per mappare 'à' su 'a')
• enable_star, infine, attiva il funzionamento della wildcard '*' nelle ricerche

Altre istruzioni utili per un utilizzo non avanzato, che però non utilizzeremo per gli esempi di questo articolo, sono:

• html_strip rimuove il codice HTML dai campi testo indicizzati
• html_index_attrs definisce attributi HTML da indicizzare, ad esempio img=alt,title; a=title;

Completiamo quindi la definizione del nostro indice ed esaminiamo brevemente l'ereditarietà di indici e fonti di dati, per poi passare alle impostazioni del demone, all'indicizzazione, e a qualche esempio di utilizzo delle API:

    morphology = none
    stopwords =
    synonyms =
    min_word_len = 1
    charset_type = utf-8
    charset_table = 0..9, A..Z->a..z, _, a..z, \
    U+C0, U+C8, U+E0, U+E8, U+E9, U+EC, U+F2, U+F9, \
    U+C0->U+61, U+C8->e, U+E0->a, U+E8->e, U+E9->e, \
    U+EC->i, U+F2->o, U+F9->u, U+2019->', U+2018->',
    enable_star = 1
    }
  

La configurazione di Sphinx permette di utilizzare l'ereditarietà sia per le fonti di dati che per gli indici: in pratica, dove due indici (o due fonti) condividono un buon numero di impostazioni, è sufficiente definirne uno solo per esteso, e implementare l'altro come estensione del primo. L'ereditarietà è utilissima soprattutto per configurazioni avanzate, e la utilizzeremo a fondo nel prossimo articolo. Per ora, limitiamoci ad utilizzarla per definire un secondo indice uguale a quello che abbiamo già definito, che utilizza però un algoritmo di stemming:

    index qix_1_stemmed : qix_1 {
    morphology = stem_en
    }
  

Tutte le impostazioni che non definiamo specificamente per il nuovo indice (fonte di dati, encoding, ecc.) saranno identiche all'indice indicato come progenitore, nel nostro caso qix_1.

Definizione delle impostazioni di runtime

L'ultima parte del file di configurazione definisce le impostazioni utilizzate dai due processi principali di Sphinx: indexer per l'indicizzazione, e searchd per la ricerca. Definiamo quindi i parametri necessari per poter utilizzare gli esempi:

    indexer {
    mem_limit = 32M
    }
    searchd {
    address = 127.0.0.1
    port = 3312
    log = /opt/sphinx/var/log/searchd.log
    query_log = /opt/sphinx/var/log/query.log
    max_children = 15
    pid_file = /opt/sphinx/var/log/searchd.pid
    max_matches = 1000
    }
  

I parametri che abbiamo impostato non sono tutti quelli disponibili, e sono uguali ai valori di default: li abbiamo riportati per darvi un'idea delle principali opzioni di runtime che potete controllare.

Indicizzazione e lancio del demone

Salviamo il file di configurazione (qui la versione completa) nella posizione predefinita, nel nostro caso /opt/sphinx/etc/sphinx.conf ed eseguiamo una prima indicizzazione dei dati.

Assicuratevi prima che

• l'utente MySQL che avete indicato in sphinx.conf esista e abbia permessi di lettura sulla base dati
• l'utente con cui fate l'indicizzazione (meglio ovviamente se non è root e se è lo stesso con cui farete girare il demone) abbia i permessi di scrittura sui percorsi degli indici

A questo punto, possiamo lanciare il comando /opt/sphinx/bin/indexer --all che utilizzerà la configurazione di default per rigenerare tutti gli indici che abbiamo definito. La mia istanza di Sphinx gira come utente sphinx, modificate il comando sotto in maniera appropriata per le vostre impostazioni:

    # su - sphinx -c "/opt/sphinx/bin/indexer --all"
    Sphinx 0.9.8-dev (r1038)
    Copyright (c) 2001-2007, Andrew Aksyonoff
    using config file '/opt/sphinx/etc/sphinx.conf'...
    indexing index 'qix_1'...
    collected 743 docs, 1.1 MB
    collected 906 attr values
    sorted 0.0 Mvalues, 100.0% done
    sorted 0.2 Mhits, 100.0% done
    total 743 docs, 1099344 bytes
    total 0.474 sec, 2317931.66 bytes/sec, 1566.59 docs/sec
    indexing index 'qix_1_stemmed'...
    collected 743 docs, 1.1 MB
    collected 906 attr values
    sorted 0.0 Mvalues, 100.0% done
    sorted 0.2 Mhits, 100.0% done
    total 743 docs, 1099344 bytes
    total 0.602 sec, 1824949.25 bytes/sec, 1233.41 docs/sec
  

Omettendo l'opzione --all e specificando i nomi di uno o più indici, indexer rigenererà solo quelli. Le opzioni più importanti oltre a quelle già viste (buildstops, buildfreqs e all) sono:

• --config, che imposta il file di configurazione da utilizzare
• --rotate, utilizzata quando il demone searchd è in esecuzione per rigenerare gli indici senza toccare quelli in uso, e riavviare searchd in automatico con i nuovi indici una volta finito il processo di indicizzazione
• --merge, per unire due indici distinti, utile quando si utilizzano i delta index, come vedremo nel prossimo articolo

Una volta che gli indici sono stati generati con successo, possiamo lanciare il demone searchd e iniziare a usare Sphinx per le ricerche. Anche per searchd valgono le osservazioni fatte sopra sull'utenza con cui lanciare il processo e i permessi di accesso a indici e log. Se utilizzate un sistema Unix che supporta init SysV, in sphinx-0.9.8-svn-rxxxx/contrib/scripts/searchd è disponibile un file per avviare searchd compatibile con chkconfig di RedHat/CentOS. Su Debian/Ubuntu potete utilizzare il mio, aggiustando il percorso del file pid e l'utente nella configurazione. Lanciamo quindi searchd da linea di comando:

    # su - sphinx -c "/opt/sphinx/bin/searchd"
    Sphinx 0.9.8-dev (r1038)
    Copyright (c) 2001-2007, Andrew Aksyonoff
    using config file '/opt/sphinx/etc/sphinx.conf'...
  

Ricerche base

Ora che i dati sono indicizzati e searchd è attivo, possiamo eseguire alcune ricerche di base, utilizzando l'eseguibile search incluso nella distribuzione. Per brevità, le ricerche che vedete qui sotto utilizzano l'opzione -q di search per non ricevere il testo completo dei risultati, potete ovviamente ometterla nei vostri esperimenti per vedere il testo ed i dati completi dei risultati.

Cominciamo con una semplice ricerca per keyword:

    $ /opt/sphinx/bin/search -i qix_1 -e "sphinx" -q
    Sphinx 0.9.8-dev (r1038)
    Copyright (c) 2001-2007, Andrew Aksyonoff
    using config file '/opt/sphinx/etc/sphinx.conf'...
    index 'qix_1': query 'sphinx ': returned 2 matches of 2 total in 0.008 sec
    displaying matches:
    1. document=682, weight=1703, author_id=1, updated=Fri Oct  5 14:21:38 2007, num_comments=4, tag=(21,172)
    2. document=743, weight=1703, author_id=1, updated=Fri Oct  5 14:21:37 2007, num_comments=7, tag=(140,190)
    words:
    1. 'sphinx': 2 documents, 2 hits
  

Modalità di ricerca

La ricerca che abbiamo appena eseguito utilizza la modalità di default, che cerca una corrispondenza esatta con tutte i termini di ricerca inseriti. Sphinx supporta cinque modalità di ricerca differenti:

• SPH_MATCH_ALL, la modalità di default che abbiamo appena utilizzato
• SPH_MATCH_ANY (-a usando search), che cerca una corrispondenza con almeno uno dei termini di ricerca
• SPH_MATCH_PHRASE (-p), cerca una corrispondenza esatta con i termini, interpretandoli come una unica frase nell'ordine in cui sono stati inseriti
• SPH_MATCH_BOOLEAN (-b), permette l'utilizzo di operatori booleani (& | + -) e parentesi per il raggruppamento, considerando un & implicito tra i termini di ricerca
• SPH_MATCH_EXTENDED (-e), modalità estesa che utilizza il linguaggio di interrogazione interno di Sphinx

La modalità estesa è quella più interessante sia per l'utente comune che per eseguire ricerche avanzate: all'utente comune offre il riconoscimento degli operatori booleani e del raggruppamento con virgolette, permettendo quindi di utilizzare una sintassi di ricerca simile a quella base di Google e in genere dei motori di ricerca su web; all'utente avanzato, offre la possibilità di restringere l'applicazione di alcuni termini a singoli campi, e un operatore di prossimità.

Vediamo un esempio semplice di funzionamento della ricerca estesa. Eseguiamo prima una ricerca con più keyword in modalità SPH_MATCH_ALL:

    $ /opt/sphinx/bin/search -i qix_1 '"classifica dei blog"' -q
    Sphinx 0.9.8-dev (r1038)
    Copyright (c) 2001-2007, Andrew Aksyonoff
    using config file '/opt/sphinx/etc/sphinx.conf'...
    index 'qix_1': query '"classifica dei blog" ': returned 21 matches of 21 total in 0.001 sec
    displaying matches:
    1. document=682, weight=4, author_id=1, updated=Fri Oct  5 14:21:38 2007, num_comments=4, tag=(21,172)
    2. document=452, weight=3, author_id=1, updated=Fri Oct  5 14:21:39 2007, num_comments=16, tag=(21,100,208,214)
    [...]
    20. document=681, weight=1, author_id=1, updated=Fri Oct  5 14:21:38 2007, num_comments=6, tag=(16,100,215)
    words:
    1. 'classifica': 26 documents, 47 hits
    2. 'dei': 342 documents, 628 hits
    3. 'blog': 297 documents, 773 hits
  

Sphinx estrae i documenti che contengono i singoli termini e li incrocia, restituendo tutti i 21 documenti che contengono — in qualsiasi posizione e rapporto tra loro — i tre termini che abbiamo indicato. Eseguiamo la stessa ricerca in modalità estesa:

    $ /opt/sphinx/bin/search -i qix_1 -e '"classifica dei blog"' -q
    Sphinx 0.9.8-dev (r1038)
    Copyright (c) 2001-2007, Andrew Aksyonoff
    using config file '/opt/sphinx/etc/sphinx.conf'...
    index 'qix_1': query '"classifica dei blog" ': returned 6 matches of 6 total in 0.006 sec
    displaying matches:
    1. document=665, weight=3548, author_id=1, updated=Fri Oct  5 14:21:38 2007, num_comments=20, tag=(21,23,100,214)
    2. document=672, weight=3548, author_id=1, updated=Fri Oct  5 14:21:38 2007, num_comments=6, tag=(23,100,141,214)
    [...]
    6. document=659, weight=3545, author_id=1, updated=Fri Oct  5 14:21:38 2007, num_comments=2, tag=(199,234)
    words:
    1. 'classifica': 26 documents, 47 hits
    2. 'dei': 342 documents, 628 hits
    3. 'blog': 297 documents, 773 hits
  

Come potete notare, i risultati sono cambiati radicalmente, dato che Sphinx cerca adesso i documenti in cui è presente la frase intera che abbiamo specificato. Possiamo anche approssimare il riconoscimento della frase utilizzando l'operatore di prossimità, dicendo a Sphinx che i singoli termini che compongono la frase non devono essere consecutivi, ma possono anche essere separati da un massimo di 10 parole:

    $ /opt/sphinx/bin/search -i qix_1 -e '"classifica dei blog"~10' -q
    Sphinx 0.9.8-dev (r1038)
    Copyright (c) 2001-2007, Andrew Aksyonoff
    using config file '/opt/sphinx/etc/sphinx.conf'...
    index 'qix_1': query '"classifica dei blog"~10 ': returned 7 matches of 7 total in 0.001 sec
    displaying matches:
    1. document=665, weight=3548, author_id=1, updated=Fri Oct  5 14:21:38 2007, num_comments=20, tag=(21,23,100,214)
    2. document=672, weight=3548, author_id=1, updated=Fri Oct  5 14:21:38 2007, num_comments=6, tag=(23,100,141,214)
    [...]
    7. document=578, weight=577, author_id=1, updated=Fri Oct  5 14:21:38 2007, num_comments=11, tag=(21,214)
    words:
    1. 'classifica': 26 documents, 47 hits
    2. 'dei': 342 documents, 628 hits
    3. 'blog': 297 documents, 773 hits
  

Il risultato non cambia molto, dato che il set di dati su cui stiamo eseguendo le ricerche è abbastanza limitato, ma l'utilizzo dell'operatore di prossimità ha comunque allargato il campo di ricerca e restituito un documento in più.

Un altro operatore disponibile nella ricerca avanzata è quello che permette di restringere l'applicazione di uno o più termini di ricerca ad un singolo campo. Vediamo una semplice ricerca prima e dopo l'applicazione di uno dei termini al campo title:

    $ /opt/sphinx/bin/search -i qix_1 -e 'classifica blog' -q
    Sphinx 0.9.8-dev (r1038)
    Copyright (c) 2001-2007, Andrew Aksyonoff
    using config file '/opt/sphinx/etc/sphinx.conf'...
    index 'qix_1': query 'classifica blog ': returned 24 matches of 24 total in 0.000 sec
    displaying matches:
    1. document=587, weight=2618, author_id=1, updated=Fri Oct  5 14:21:38 2007, num_comments=38, tag=(21,100,214)
    2. document=452, weight=2604, author_id=1, updated=Fri Oct  5 14:21:39 2007, num_comments=16, tag=(21,100,208,214)
    [...]
    20. document=678, weight=1566, author_id=1, updated=Fri Oct  5 14:21:38 2007, num_comments=12, tag=(101,102,115,172)
    words:
    1. 'classifica': 26 documents, 47 hits
    2. 'blog': 297 documents, 773 hits
  

restringendo l'applicazione del termine "blog" al solo titolo dei post, i risultati cambiano drasticamente:

    $ /opt/sphinx/bin/search -i qix_1 -e 'classifica @title blog' -q
    Sphinx 0.9.8-dev (r1038)
    Copyright (c) 2001-2007, Andrew Aksyonoff
    using config file '/opt/sphinx/etc/sphinx.conf'...
    index 'qix_1': query 'classifica @title blog ': returned 6 matches of 6 total in 0.000 sec
    displaying matches:
    1. document=587, weight=2618, author_id=1, updated=Fri Oct  5 14:21:38 2007, num_comments=38, tag=(21,100,214)
    2. document=452, weight=2604, author_id=1, updated=Fri Oct  5 14:21:39 2007, num_comments=16, tag=(21,100,208,214)
    [...]
    6. document=570, weight=2568, author_id=1, updated=Fri Oct  5 14:21:38 2007, num_comments=1, tag=(138,180)
    words:
    1. 'classifica': 26 documents, 47 hits
    2. 'blog': 297 documents, 773 hits
  

Infine, gli operatori booleani funzionano allo stesso modo che per le ricerche su Google e altri motori di ricerca. Proviamo ad esempio una delle ricerche qui sopra, escludendo un termine con l'operatore -:

    $ /opt/sphinx/bin/search -i qix_1 -e 'classifica blog -technorati' -q
    Sphinx 0.9.8-dev (r1038)
    Copyright (c) 2001-2007, Andrew Aksyonoff
    using config file '/opt/sphinx/etc/sphinx.conf'...
    index 'qix_1': query 'classifica blog -technorati ': returned 20 matches of 20 total in 0.001 sec
    displaying matches:
    1. document=581, weight=2570, author_id=1, updated=Fri Oct  5 14:21:38 2007, num_comments=15, tag=(21,100,214)
    2. document=682, weight=2570, author_id=1, updated=Fri Oct  5 14:21:38 2007, num_comments=4, tag=(21,172)
    [...]
    20. document=813, weight=1564, author_id=1, updated=Thu Nov 15 16:45:57 2007, num_comments=3, tag=(20)
    words:
    1. 'classifica': 26 documents, 47 hits
    2. 'blog': 297 documents, 773 hits
  

Escludendo il termine "technorati" il numero di risultati restituiti è passato da 24 a 20.

Ordinamento

Come le modalità di ricerca, anche l'ordinamento dei risultati supporta diverse modalità:

• SPH_SORT_RELEVANCE (default), ordina per rilevanza dei risultati
• SPH_SORT_ATTR_DESC, ordina secondo il valore di un attributo (che deve essere specificato), con ordinamento decrescente
• SPH_SORT_ATTR_ASC, ordina secondo il valore di un attributo (che deve essere specificato), con ordinamento crescente
• SPH_SORT_TIME_SEGMENTS, ordina temporalmente per segmenti (ora/giorno/settimana/mese) su un attributo (che deve essere specificato), e all'interno dei segmenti temporali per rilevanza decrescente
• SPH_SORT_EXTENDED, ordina utilizzando un'espressione con operatori simili a SQL

L'ordinamento per segmenti temporali è particolarmente comodo per la ricerca di notizie, o dati dove la freschezza di pubblicazione ha un'importanza pari o superiore alla rilevanza dei termini di ricerca, ed è spiegata con qualche dettaglio in più sul manuale di Sphinx.

L'ordinamento esteso utilizza due operatori: @id, l'id del risultato; @rank (o @weight @relevance), la rilevanza. Gli operatori possono essere combinati tra di loro e con gli attributi, specificando per ognuno se l'ordinamento deve essere crescente o decrescente. Un esempio di ordinamento esteso dal manuale di Sphinx è @relevance DESC, price ASC, @id DESC.

Proviamo a ripetere una delle query precedenti, ordinando questa volta i risultati per time segments:

    $ /opt/sphinx/bin/search -i qix_1 -e 'classifica blog -technorati' -q --sort=ts
    Sphinx 0.9.8-dev (r1038)
    Copyright (c) 2001-2007, Andrew Aksyonoff
    using config file '/opt/sphinx/etc/sphinx.conf'...
    index 'qix_1': query 'classifica blog -technorati ': returned 20 matches of 20 total in 0.001 sec
    displaying matches:
    1. document=813, weight=1564, author_id=1, updated=Thu Nov 15 16:45:57 2007, num_comments=3, tag=(20)
    2. document=682, weight=2570, author_id=1, updated=Wed Nov 22 14:28:58 2006, num_comments=4, tag=(21,172)
    3. document=581, weight=2570, author_id=1, updated=Wed Jul 19 18:39:40 2006, num_comments=15, tag=(21,100,214)
    4. document=643, weight=2569, author_id=1, updated=Mon Oct  9 00:33:12 2006, num_comments=22, tag=(21,100)
    5. document=570, weight=2568, author_id=1, updated=Sat Jul  1 12:10:56 2006, num_comments=1, tag=(138,180)
    6. document=691, weight=1607, author_id=1, updated=Sun Dec  3 00:01:42 2006, num_comments=25, tag=(16,21,37,100,214,215)
    [...]
    20. document=595, weight=1564, author_id=1, updated=Thu Aug 24 22:32:02 2006, num_comments=1, tag=(7,86)
    words:
    1. 'classifica': 26 documents, 47 hits
    2. 'blog': 297 documents, 773 hits
  

Come potete notare, il primo risultato restituito ha una rilevanza più bassa rispetto ai seguenti, ma è molto più recente e quindi viene portato in prima posizione. Altri ordinamenti, come quello esteso o quello per attributi, possono essere utilizzati solo dalle API e li vedremo quindi in seguito.

Filtri

Gli attributi non servono solo per ordinare i risultati, ma anche per restringerli a determinati valori di uno o più attributi utilizzando dei filtri. I filtri possono specificare un attributo e un valore che deve avere in tutti i risultati restituiti, o un attributo e un range di valori. Come per l'ordinamento, i tipi di filtri avanzati possono essere utilizzati solo dalle API, e li mostreremo nei prossimi articoli. Vediamo quindi un semplice tipo di filtro, che limita i risultati restituiti ad un singolo autore. I risultati senza filtro sono:

    $ /opt/sphinx/bin/search -i qix_1 -e 'ebay ' -q
    Sphinx 0.9.8-dev (r1038)
    Copyright (c) 2001-2007, Andrew Aksyonoff
    using config file '/opt/sphinx/etc/sphinx.conf'...
    index 'qix_1': query 'ebay  ': returned 37 matches of 37 total in 0.001 sec
    displaying matches:
    1. document=332, weight=2693, author_id=3, updated=Thu Mar 10 09:37:00 2005, num_comments=0, tag=()
    2. document=121, weight=2671, author_id=3, updated=Fri Aug 13 17:05:00 2004, num_comments=0, tag=()
    [...]
    18. document=739, weight=1639, author_id=1, updated=Mon Apr  2 23:07:02 2007, num_comments=14, tag=(126,234)
    19. document=794, weight=1639, author_id=1, updated=Sun Oct 14 14:25:13 2007, num_comments=4, tag=(13,42,83)
    20. document=1, weight=1601, author_id=2, updated=Wed Aug  4 17:40:00 2004, num_comments=0, tag=()
    words:
    1. 'ebay': 37 documents, 81 hits
  

e applicando un filtro che limita l'id dell'autore a 1:

    $ /opt/sphinx/bin/search -i qix_1 -e 'ebay ' -q -f author_id 1
    Sphinx 0.9.8-dev (r1038)
    Copyright (c) 2001-2007, Andrew Aksyonoff
    using config file '/opt/sphinx/etc/sphinx.conf'...
    index 'qix_1': query 'ebay  ': returned 15 matches of 15 total in 0.000 sec
    displaying matches:
    1. document=118, weight=1685, author_id=1, updated=Mon Jul 19 17:35:02 2004, num_comments=0, tag=()
    2. document=300, weight=1671, author_id=1, updated=Mon Jan 10 21:49:51 2005, num_comments=3, tag=()
    [...]
    15. document=804, weight=1601, author_id=1, updated=Sat Oct 27 23:17:29 2007, num_comments=10, tag=(120,124)
    words:
    1. 'ebay': 37 documents, 81 hits
  

Raggruppamenti

Oltre che per ordinare e filtrare i risultati, gli attributi possono essere utilizzati anche per creare raggruppamenti, che isolano i singoli valori di un attributo presenti nei risultati e restituiscono il documento con la migliore corrispondenza per ogni valore, insieme a due nuovi attributi: @groupby, che indica il valore dell'attributo utilizzato per il raggruppamento; @count, che indica il numero di documenti tra i risultati che hanno l'attributo di raggruppamento corrispondente al valore di @groupby. I raggruppamenti funzionano ancora solo su attributi singoli, se (come me) siete interessati ad utilizzarli su attributi MVA, magari per replicare le funzionalità di faceting di Apache Solr, aggiungetevi a questo bug sul tracker di Sphinx.

Vediamo un semplice raggruppamento per id dell'autore:

    $ /opt/sphinx/bin/search -i qix_1 -e 'ebay ' -q -g author_id
    Sphinx 0.9.8-dev (r1038)
    Copyright (c) 2001-2007, Andrew Aksyonoff
    using config file '/opt/sphinx/etc/sphinx.conf'...
    index 'qix_1': query 'ebay  ': returned 4 matches of 4 total in 0.000 sec
    displaying matches:
    1. document=71, weight=1659, author_id=6, updated=Thu Aug 26 16:23:00 2004, num_comments=0, tag=(), @groupby=6, @count=1
    2. document=332, weight=2693, author_id=3, updated=Thu Mar 10 09:37:00 2005, num_comments=0, tag=(), @groupby=3, @count=19
    3. document=1, weight=1601, author_id=2, updated=Wed Aug  4 17:40:00 2004, num_comments=0, tag=(), @groupby=2, @count=2
    4. document=118, weight=1685, author_id=1, updated=Mon Jul 19 17:35:02 2004, num_comments=0, tag=(), @groupby=1, @count=15
    words:
    1. 'ebay': 37 documents, 81 hits
  

Come potete notare abbiamo quattro risultati, uno per ogni id di autore restituito dalla ricerca. Ogni risultato ha il documento con la corrispondenza migliore ai termini di ricerca per l'autore identificato in @groupby, e il numero di documenti che la ricerca restituirebbe impostando un filtro su quell'autore contenuto in @count. L'autore con id 3, ad esempio, è quello che ha scritto più post su ebay (19), e il suo post dove ebay è utilizzato di più è il numero 332.

Se utilizzassimo le API invece del comando search, potremmo ordinare i risultati, oltre che per rilevanza come mostrato qui sopra, anche per numero di post per ogni autore (@count) o id dell'autore (@groupby).

Utilizzo delle API

Il sorgente di Sphinx contiene tre client direttamente supportati per PHP, Python, e Java; e due sviluppati dagli utenti per Perl e Ruby. Tutti i client si uniformano alla sintassi del modulo PHP, sviluppato direttamente da Andrew e l'unico disponibile con le prime versioni di Sphinx, in modo da facilitare la documentazione ufficiale e semplificare il passaggio da un linguaggio all'altro.

Il risvolto negativo di questa scelta (fatta direttamente da Andrew) è che l'utilizzo dei client non rispetta le convenzioni dei singoli linguaggi e risulta quindi poco intuitivo (e a volte decisamente macchinoso). Fortunatamente il protocollo utilizzato da searchd è molto semplice, e scrivere un client “personalizzato” (o uno per un linguaggio non supportato direttamente) utilizzando come punto di partenza uno dei client disponibili è questione di poche ore. Nei prossimi articoli di questa serie vedremo come, esaminando il client alternativo per Python che ho sviluppato per BlogBabel, che è l'unico oltre a quello ufficiale in PHP che — per ora — supporta alcune nuove funzionalità come le query multiple, che veicolano più set di richieste/risposte all'interno di un'unica connessione TCP.

Per stuzzicarvi l'appetito, ecco due semplici esempi di utilizzo del driver standard per PHP

    require_once 'sphinxapi.php';
    $c =& new SphinxClient();
    $cl->SetServer('localhost', 3312);
    if ($err = $cl->GetLastError())
        die("Error while querying Sphinx: " . $err);
    $cl->setMode(SPH_MATCH_EXTENDED);
    $res = $cl->Query('sphinx', 'qix_1');
    if (!$res)
        die("Error while querying Sphinx: " . $cl->GetLastError());
  

e del mio driver per Python

    import sphinx
    try:
        c = sphinx.SphinxClient('localhost', 3312)
        r = c.query('sphinx', index='qix_1', mode=sphinx.SPH_MATCH_EXTENDED)
    except sphinx.SphinxError, e:
        raise SystemExit("Error while querying Sphinx: %s" % e)
  

Spero che questa prima infarinatura di Sphinx sia stata sufficiente a farvi intravedere le potenzialità di questo motore di ricerca. Continueremo ad esaminarlo nei prossimi articoli, se avete qualche curiosità o argomento che vi piacerebbe fosse trattato, segnalatemelo nei commenti.