Ricerca Full-Text in Cinese su PostgreSQL usando pg_jieba in ServBay

Panoramica

Per lingue come l’inglese, la funzione di ricerca full-text incorporata in PostgreSQL funziona efficacemente tramite analisi lessicale basata su spazi e punteggiatura. Tuttavia, il cinese non utilizza spazi naturali tra le parole, rendendo necessaria una soluzione di tokenizzazione specifica che suddivida sequenze di caratteri cinesi in termini semanticamente indipendenti.

pg_jieba è un’estensione di terze parti per PostgreSQL che integra la popolare libreria cinese di tokenizzazione Jieba. Tramite pg_jieba, puoi effettuare la segmentazione di testo cinese in modo efficiente e preciso direttamente in PostgreSQL, abilitando potenti funzionalità di ricerca full-text in cinese.

ServBay, ambiente integrato per lo sviluppo web locale, include già l’estensione pg_jieba, eliminando la necessità di installazione manuale o compilazione, e consentendoti di sviluppare e testare rapidamente la ricerca full-text in locale.

In questa guida vedrai come abilitare, configurare e utilizzare l’estensione pg_jieba in ServBay.

Prerequisiti

Prima di utilizzare pg_jieba, assicurati di aver completato i seguenti passaggi:

1. Hai installato ServBay su macOS e il database PostgreSQL è funzionante.
2. Hai familiarità con le operazioni di base di PostgreSQL, come la connessione e l’esecuzione di comandi SQL.

Installazione e abilitazione di pg_jieba

In ServBay, il modulo estensione pg_jieba viene già fornito insieme a PostgreSQL. Non è necessario scaricarlo o compilarlo: basta eseguire un semplice comando SQL nel database target per abilitarlo.

Procedura per abilitare l’estensione pg_jieba:

1. Connettiti al database PostgreSQL:
   Apri il terminale e usa lo strumento a riga di comando psql per collegarti al tuo database. Sostituisci your_username col nome utente PostgreSQL e your_database con il nome del database. Gli utenti e database di default ServBay sono di solito servbay o postgres.

   psql -U your_username -d your_database

   Ad esempio, con utente e database predefiniti:

   psql -U servbay -d servbay

2. Crea e abilita l'estensione pg_jieba:
   Da psql, esegui questo comando SQL:

   CREATE EXTENSION pg_jieba;

   Se l’estensione è già presente, il comando potrebbe restituire un errore: è normale.

3. Verifica che pg_jieba sia abilitato:
   Elenca le estensioni installate con:

   \dx

   Se nella lista compare pg_jieba, allora l’estensione è attiva.

Configurazione di pg_jieba per la ricerca full-text in cinese

Dopo aver abilitato pg_jieba, occorre configurare la ricerca testuale di PostgreSQL per usare pg_jieba come tokenizzatore.

Imposta la configurazione di ricerca testuale

La configurazione di ricerca testuale determina come vengono processati i documenti per la ricerca full-text, incluso quale parser usare e come gestire i diversi tipi di token.

1. Crea una nuova configurazione:
   Crea una configurazione chiamata chinese che usa pg_jieba come parser.

   CREATE TEXT SEARCH CONFIGURATION chinese (PARSER = pg_jieba);

   Questa configurazione istruisce PostgreSQL a usare pg_jieba per dividere il testo.

2. Mappa i risultati della segmentazione (Mapping):
   Il parser pg_jieba produce diversi tipi di token in base alla parte del discorso. Per indicizzarli e renderli ricercabili, mappali su uno specifico dizionario. Qui, le principali parti del discorso (come nome, verbo, aggettivo, ecc.) sono mappate sul dizionario built-in simple di PostgreSQL, che lascia i token invariati.

   ALTER TEXT SEARCH CONFIGURATION chinese ADD MAPPING FOR n,v,a,i,e,l WITH simple;

   n,v,a,i,e,l sono alcuni dei tag che pg_jieba riconosce. Puoi aggiungere o modificarli a seconda delle esigenze. Alcuni tra i più comuni:

   • n: sostantivo
   • v: verbo
   • a: aggettivo
   • i: idiomatico
   • e: esclamazione
   • l: espressione
   • nr: nome proprio
   • ns: nome geografico
   • nt: organizzazione
   • nz: altro nome proprio
   • m: numerale
   • q: classificatore
   • t: tempo
   • s: luogo
   • f: direzionale
   • p: preposizione
   • c: congiunzione
   • u: particella
   • xc: altre particelle
   • w: punteggiatura
   • eng: inglese
   • x: carattere non lessicale

   In genere si indica e si ricerca soprattutto termini di reale significato, come nomi, verbi e aggettivi.

Esempio di ricerca full-text con pg_jieba

Dopo la configurazione, puoi usare pg_jieba per ricerche full-text su testo cinese. Ecco un esempio pratico:

Crea tabella e dati di esempio

Per prima cosa, crea una tabella per archiviare documenti con testo in cinese.

1. Crea la tabella:

   CREATE TABLE documents (
       id SERIAL PRIMARY KEY,
       content TEXT
   );

2. Inserisci dati di esempio:

   INSERT INTO documents (content) VALUES
   ('我爱自然语言处理技术'),
   ('中文分词是文本处理的重要步骤'),
   ('pg_jieba是一个很好的中文分词工具，它基于结巴分词库'),
   ('ServBay 让本地开发变得简单高效');

Crea un indice per la ricerca full-text

Per migliorare l’efficienza della ricerca, specialmente con molti dati, è altamente consigliato creare un indice sulla colonna usata per la ricerca. PostgreSQL offre l’indice GIN (Generalized Inverted Index), ideale per la ricerca full-text.

1. Crea indice GIN:
   Usiamo la funzione to_tsvector insieme alla configurazione chinese per indicizzare la colonna content. to_tsvector('chinese', content) trasforma il testo in un tipo tsvector, usato internamente per la ricerca.

   CREATE INDEX idx_gin_content ON documents USING gin (to_tsvector('chinese', content));

Esegui query di ricerca full-text

Ora puoi effettuare ricerche con la funzione to_tsquery abbinata all’operatore @@. to_tsquery('chinese', 'query') trasforma la frase di ricerca nel formato giusto secondo la configurazione chinese. Con @@ verifichi se un tsvector corrisponde a una tsquery.

1. Esegui una ricerca: Cerca documenti che contengano sia "中文" che "分词".

   SELECT
       id,
       content
   FROM documents
   WHERE to_tsvector('chinese', content) @@ to_tsquery('chinese', '中文 & 分词');

   Il simbolo & rappresenta AND logico. Puoi anche usare | (OR) e ! (NOT).

   Esempio: trova documenti che contengano "ServBay" o "开发":

   SELECT
       id,
       content
   FROM documents
   WHERE to_tsvector('chinese', content) @@ to_tsquery('chinese', 'ServBay | 开发');

Dizionario personalizzato

pg_jieba usa il dizionario predefinito di Jieba per la tokenizzazione. In alcuni casi, potresti voler aggiungere termini personalizzati (es. terminologia tecnica, nomi di prodotti) per aumentare l’accuratezza.

Puoi creare un file di dizionario personalizzato e configurare pg_jieba per utilizzarlo.

Aggiungi termini personalizzati

1. Crea un file dizionario personalizzato: Nella cartella di configurazione di ServBay, crea un file di testo. Ad esempio:

   /Applications/ServBay/etc/pg_jieba/custom_dict.txt

   Questo è un percorso suggerito: adatta in base all’installazione di ServBay e alle tue preferenze.

2. Aggiungi i termini al dizionario: Apri custom_dict.txt con un editor e inserisci un termine per riga. Puoi opzionalmente indicare frequenza e tag separati da uno spazio. Il formato è termine [frequenza [tag]]. Più alta la frequenza, più probabile che il termine sia riconosciuto.

   自然语言处理 3 n
   ServBay 5 eng
   结巴分词库 3 n

   Ad esempio, 3 n indica che "自然语言处理" ha frequenza 3 e tag sostantivo (n). 5 eng indica "ServBay", frequenza 5 e tag inglese (eng).

3. Configura pg_jieba per usare il dizionario personalizzato: Nella sessione PostgreSQL, imposta il parametro pg_jieba.dict_path verso la cartella che contiene il dizionario personalizzato.
   Nota: pg_jieba.dict_path di solito punta alla cartella, non a un solo file. Se il file custom è nella stessa cartella del dizionario principale, spesso non serve modificare il parametro, oppure ServBay può avere delle specifiche proprie. Consulta la documentazione di ServBay per dettagli su dict_path.

   Se ServBay permette la specifica diretta del file, oppure se il file custom è in una cartella scansionata di default, il comando SET potrebbe variare o non essere necessario.
   Esempio (adatta alle tue necessità):

   SET pg_jieba.dict_path = '/Applications/ServBay/etc/pg_jieba/'; -- Supponiamo che il dizionario principale e custom siano qui

   Oppure, se eccezionalmente fosse accettato il file singolo:

   SET pg_jieba.dict_path = '/Applications/ServBay/etc/pg_jieba/custom_dict.txt'; -- Usare con cautela, verifica la configurazione ServBay

   Nota importante: Il comando SET vale solo per la sessione corrente. Per renderlo permanente, modifica il file di configurazione postgresql.conf impostando il percorso nel parametro pg_jieba.dict_path.

Ricarica i dizionari

Dopo aver modificato il dizionario personalizzato o la variabile pg_jieba.dict_path, occorre ricaricare i dizionari per rendere effettive le modifiche.

1. Ricarica dizionari: Esegui la funzione SQL:

   SELECT jieba_reload_dict();

   Una volta completato, le modifiche saranno operative sulle successive tokenizzazioni.

Domande Frequenti (FAQ)

• D: Ricevo l’errore "extension 'pg_jieba' is not available" durante CREATE EXTENSION pg_jieba;. Cosa fare?
  R: Questo di solito indica che il file di estensione non è disponibile nella directory estensioni di PostgreSQL o non è stato trovato. Su ServBay, l’estensione dovrebbe già essere presente: assicurati di essere connesso all’istanza PostgreSQL fornita da ServBay e che l’installazione non sia corrotta. Se il problema persiste, prova a riavviare ServBay o verifica i log di ServBay.

• D: Il dizionario personalizzato non viene applicato, cosa posso fare?
  R: Controlla questi punti:

  1. Il percorso del dizionario è corretto e l’utente PostgreSQL ha i permessi di lettura.
  2. Il formato del file è corretto: un termine per riga, frequenza e tag opzionali separati da spazio.
  3. Hai impostato correttamente la variabile pg_jieba.dict_path. Ricorda che SET vale solo per la sessione; per rendere le modifiche persistenti, modifica postgresql.conf.
  4. Hai eseguito SELECT jieba_reload_dict(); per ricaricare i termini.
  5. Se hai modificato postgresql.conf, hai riavviato PostgreSQL?

• D: I risultati della ricerca non sono accurati. Suggerimenti? R: L’accuratezza della ricerca dipende dalla segmentazione e dalla costruzione della query.

  1. Controlla la segmentazione con ts_debug('chinese', 'tuo testo') per vedere come chinese segmenta il testo, verificando anche se i termini personalizzati vengono riconosciuti.
  2. Ottimizza la segmentazione regolando i tag inclusi in ALTER TEXT SEARCH CONFIGURATION chinese ADD MAPPING FOR ... WITH simple;, escludendo tag meno rilevanti (come particelle o punteggiatura).
  3. Ottimizza la query scegliendo i termini e gli operatori logici (&, |, !) più adatti alle tue necessità.

Conclusione

pg_jieba è uno strumento potente per implementare una ricerca full-text in cinese con PostgreSQL. Grazie all’integrazione pronta all’uso di ServBay, gli sviluppatori possono facilmente abilitare e configurare la segmentazione cinese nel proprio ambiente locale. Seguendo i passaggi di questa guida hai imparato come installare pg_jieba, creare e configurare la ricerca testuale, eseguire query di base e usare dizionari personalizzati per risultati ancora più precisi. Integrando queste tecniche nei tuoi progetti potrai rendere moltissimo più efficace la ricerca su testi in cinese.