PostgreSQL embarque une recherche full-text depuis plus de quinze ans. La plateforme tournait déjà sous PostgreSQL. Le hic: le projet utilise Doctrine ORM, et Doctrine ne sait pas nativement ce qu’est un tsvector.

Une bibliothèque communautaire, postgresql-for-doctrine, couvre une partie de cette lacune. Elle enregistre des fonctions DQL basiques comme TO_TSQUERY, TO_TSVECTOR, et l’opérateur de correspondance @@ en tant que pièces atomiques séparées. La fondation était là. Trois choses restaient à construire par-dessus.

Le type que Doctrine n’a jamais vu

La recherche full-text de PostgreSQL repose sur deux types: tsvector (une liste pré-traitée de tokens normalisés) et tsquery (une expression de recherche). On maintient une colonne tsvector, on l’indexe avec GIN, et on interroge avec l’opérateur @@.

Le DBAL de Doctrine ne livre aucun type tsvector. Déclarer #[ORM\Column(type: 'tsvector')] sans l’enregistrer au préalable lève une UnknownColumnTypeException. La solution: un type DBAL personnalisé:

class TsVector extends Type
{
    final public const string DBAL_TYPE = 'tsvector';

    public function getSQLDeclaration(array $column, AbstractPlatform $platform): string
    {
        return self::DBAL_TYPE;
    }

    public function getName(): string
    {
        return self::DBAL_TYPE;
    }

    public function convertToDatabaseValueSQL(string $sqlExpr, AbstractPlatform $platform): string
    {
        return sprintf("to_tsvector('simple', %s)", $sqlExpr);
    }

    public function convertToDatabaseValue(mixed $value, AbstractPlatform $platform): mixed
    {
        if (is_array($value) && isset($value['data'])) {
            return $value['data'];
        }

        return is_string($value) ? $value : null;
    }

    public function getMappedDatabaseTypes(AbstractPlatform $platform): array
    {
        return [self::DBAL_TYPE];
    }
}

La méthode intéressante est convertToDatabaseValueSQL(). Doctrine l’appelle pour envelopper le placeholder SQL avant que la valeur n’atteigne la base de données. La valeur écrite devient automatiquement to_tsvector('simple', ?) à la frontière DBAL, sans étape supplémentaire côté appelant.

On enregistre le type dans doctrine.yaml, puis on mappe la colonne sur l’entité:

doctrine:
    dbal:
        types:
            tsvector: App\Doctrine\DBAL\Types\TsVector

#[ORM\Column(type: 'tsvector', nullable: true)]
protected ?string $textSearch = null;

Côté PHP, la valeur est une simple chaîne. La conversion en vrai tsvector se fait invisiblement au niveau DBAL.

Nous avons utilisé le dictionnaire 'simple', qui tokenise sur les espaces et la ponctuation sans stemming spécifique à une langue. La plateforme gère plusieurs langues, et les règles de stemming français auraient cassé l’espagnol. Simple suffit largement pour la phonétique.

Garder la colonne à jour

Une colonne tsvector est une donnée dérivée: elle doit rester synchronisée avec les champs source chaque fois que l’entité change. Un event listener Doctrine s’en charge:

#[AsDoctrineListener(event: Events::prePersist)]
#[AsDoctrineListener(event: Events::preUpdate)]
class MediaTsVectorSubscriber
{
    public function prePersist(PrePersistEventArgs $event): void
    {
        if (!$event->getObject() instanceof Media) {
            return;
        }
        $this->updateTextSearch($event->getObject());
    }

    public function preUpdate(PreUpdateEventArgs $event): void
    {
        if (!$event->getObject() instanceof Media) {
            return;
        }
        $this->updateTextSearch($event->getObject());
    }

    private function updateTextSearch(Media $entity): void
    {
        $entity->setTextSearch(
            sprintf('%s %s', $entity->getTitle(), $entity->getCaption())
        );
    }
}

Avant chaque persist et update, le subscriber concatène les champs qui doivent être recherchables dans textSearch. Doctrine flush la chaîne combinée, le type DBAL l’enveloppe dans to_tsvector('simple', ...), et PostgreSQL stocke la forme tokenisée.

Une subtilité: la valeur côté PHP est "title caption", pas la sortie tsvector réelle. La base affiche 'caption' 'title' (tokens triés), mais l’entité contient une chaîne brute. C’est attendu: la conversion est une responsabilité DBAL, pas PHP. Ça peut dérouter le débogage jusqu’à ce qu’on se souvienne où se situe la frontière.

Étendre DQL avec les opérateurs FTS

Le DQL de Doctrine couvre les opérations SQL courantes, mais tout ce qui est spécifique à PostgreSQL est hors périmètre. C’est là que postgresql-for-doctrine entre en jeu: il enregistre TO_TSQUERY, TO_TSVECTOR, et TSMATCH comme fonctions DQL individuelles. Écrire une requête full-text en DQL sans lui signifierait basculer en SQL natif.

Les fonctions de la bibliothèque sont atomiques, cependant. Chacune correspond à un appel SQL. Exprimer une vérification de correspondance complète en DQL ressemble à TSMATCH(o.textSearch, TO_TSQUERY(:term)). Assez lisible, mais l’équipe voulait quelque chose de plus compact: une seule fonction DQL encodant à la fois l’opérateur de correspondance et le type de requête, y compris websearch_to_tsquery que postgresql-for-doctrine ne fournissait pas.

La solution: des fonctions DQL personnalisées via FunctionNode. On parse la syntaxe DQL, puis on émet du SQL. Toutes les fonctions FTS partagent la même signature à deux arguments, donc une classe abstraite de base gère le parsing:

abstract class TsFunction extends FunctionNode
{
    public PathExpression|Node|null $ftsField = null;
    public PathExpression|Node|null $queryString = null;

    public function parse(Parser $parser): void
    {
        $parser->match(TokenType::T_IDENTIFIER);
        $parser->match(TokenType::T_OPEN_PARENTHESIS);
        $this->ftsField = $parser->StringPrimary();
        $parser->match(TokenType::T_COMMA);
        $this->queryString = $parser->StringPrimary();
        $parser->match(TokenType::T_CLOSE_PARENTHESIS);
    }
}

Chaque classe concrète implémente getSql() pour émettre son expression PostgreSQL:

// e.textSearch @@ websearch_to_tsquery('simple', :term)
class TsWebsearchQueryFunction extends TsFunction
{
    public function getSql(SqlWalker $sqlWalker): string
    {
        return $this->ftsField->dispatch($sqlWalker)
            ." @@ websearch_to_tsquery('simple', "
            .$this->queryString->dispatch($sqlWalker).')';
    }
}

// ts_rank(e.textSearch, to_tsquery(:term)) pour le tri par pertinence
class TsRankFunction extends TsFunction
{
    public function getSql(SqlWalker $sqlWalker): string
    {
        return 'ts_rank('
            .$this->ftsField->dispatch($sqlWalker)
            .', to_tsquery('.$this->queryString->dispatch($sqlWalker).'))';
    }
}

doctrine:
    orm:
        entity_managers:
            default:
                dql:
                    string_functions:
                        tswebsearchquery: App\Doctrine\ORM\Query\AST\Functions\TsWebsearchQueryFunction
                        tsrank: App\Doctrine\ORM\Query\AST\Functions\TsRankFunction
                        tsquery: App\Doctrine\ORM\Query\AST\Functions\TsQueryFunction
                        tsplainquery: App\Doctrine\ORM\Query\AST\Functions\TsPlainQueryFunction

websearch_to_tsquery est le bon choix pour la recherche côté utilisateur: les espaces deviennent des AND, les chaînes entre guillemets deviennent des phrases, -mot exclut un terme. Inutile d’apprendre aux utilisateurs à taper interview & président. C’est disponible depuis PostgreSQL 11. Sur les versions antérieures, plainto_tsquery est l’équivalent le plus proche.

Le filtre API Platform et l’index GIN

Avec les fonctions DQL enregistrées, le filtre API Platform est simple. Un AbstractFilter personnalisé appelle directement la fonction DQL dans le QueryBuilder:

class TextSearchFilter extends AbstractFilter
{
    protected function filterProperty(
        string $property,
        $value,
        QueryBuilder $queryBuilder,
        QueryNameGeneratorInterface $queryNameGenerator,
        string $resourceClass,
        ?Operation $operation = null,
        array $context = []
    ): void {
        if ('textSearch' !== $property || empty($value)) {
            return;
        }

        $queryBuilder
            ->andWhere('tswebsearchquery(o.textSearch, :value) = true')
            ->setParameter(':value', $value);
    }

    public function getDescription(string $resourceClass): array
    {
        return [];
    }
}

On l’applique sur l’entité avec la déclaration d’index:

#[ORM\Index(
    columns: ['text_search'],
    name: 'media_text_search_idx_gin',
    options: ['USING' => 'gin (text_search)']
)]
#[ApiFilter(TextSearchFilter::class, properties: ['textSearch' => 'partial'])]
class Media
{
    // ...
    #[ORM\Column(type: 'tsvector', nullable: true)]
    protected ?string $textSearch = null;
}

L’option USING gin n’est pas négociable. Un index B-tree standard sur une colonne tsvector est inutile: PostgreSQL ne peut pas l’utiliser pour les requêtes @@. GIN (Generalized Inverted Index) fonctionne différemment: il indexe chaque token individuellement, donc les recherches par n’importe quel token sont en O(log n) plutôt que O(n). Sans ça, on a construit un système qui donne l’impression d’être rapide mais qui fait quand même un full table scan.

Un GET /media?textSearch=interview+president touche maintenant l’index GIN et répond en quelques millisecondes quel que soit la taille de la table.

Ce que la répartition ressemblait vraiment

La bibliothèque couvrait les fonctions atomiques bas niveau. Le code personnalisé couvrait les lacunes: un type DBAL tsvector que la bibliothèque ne fournissait pas, des wrappers DQL pratiques combinant @@ et websearch_to_tsquery en un seul appel, et la colle applicative reliant tout ça au système d’événements de Doctrine et à API Platform. Aucune requête native n’a été nécessaire.

La répartition vaut d’être notée en général: postgresql-for-doctrine donne les briques atomiques PostgreSQL, mais il faut quand même les composer en quelque chose que le reste du code peut utiliser sans y penser. Le pattern FunctionNode et le hook convertToDatabaseValueSQL() sont les deux points d’extension qui rendent cette composition propre. Les deux valent d’être connus, quelle que soit la bibliothèque de départ.

Les supprimer naïvement n’était pas une option. “Garder les 50 dernières” perd tout contexte historique pour les articles qui n’ont pas été touchés depuis un an. “Garder une par jour” perd tous les détails pour le contenu qui est activement édité. Ce dont on avait besoin, c’était une distribution qui correspondait à la façon dont les révisions sont réellement utilisées : couverture dense pour l’historique récent, couverture clairsemée pour l’ancien.

C’est une distribution logarithmique. Et la construire nécessitait du SQL brut.

Pourquoi les stratégies simples échouent

L’attrait d’une fenêtre fixe est évident : garder les N révisions les plus récentes et supprimer le reste. C’est une ligne de SQL et zéro maths. Le problème, c’est qu’elle traite une révision d’hier et une révision d’il y a trois ans comme également précieuses, ce qu’elles ne sont pas. Un éditeur qui ouvre un article de 2017 n’a pas besoin de ses 50 dernières versions ; il pourrait avoir besoin d’une par trimestre. Un article qui a été publié ce matin pourrait avoir besoin de chaque sauvegarde de la dernière heure.

Une stratégie temporelle (une révision par jour calendaire) a le problème inverse : elle est trop agressive pour le contenu actif. Si un article reçoit 30 sauvegardes entre 09h00 et 10h00, toutes sauf une disparaissent. Ce n’est pas de l’histoire, c’est de l’effacement.

Ni l’une ni l’autre ne peut exprimer “garder plus de détails pour le contenu récent, moins pour le vieux”. Cette relation est logarithmique.

L’idée de score

L’algorithme assigne à chaque révision un score basé sur son âge, puis garde seulement une révision par bucket de score. La formule de score produit des valeurs hautes et bien espacées pour les révisions récentes, et des valeurs petites et regroupées pour les anciennes.

L’expression centrale, simplifiée, ressemble à ça :

(
  ln( EXTRACT(epoch FROM (now() - created_at)) )
  /
  ( EXTRACT(epoch FROM (now() - created_at)) / 6000 )
)
* ( 1 / (EXTRACT(epoch FROM (now() - created_at)) / 60 / 1440) )
* 1000

Soit s l’âge en secondes. La formule est grossièrement ln(s) / s * C, où le logarithme au numérateur et s au dénominateur font diminuer le résultat rapidement à mesure que s augmente.

Converti en entier, l’effet est le suivant : une révision sauvegardée il y a 10 minutes pourrait scorer 8432, une sauvegardée il y a 11 minutes score 8431. Elles sont dans des buckets différents. Une révision d’il y a six mois score 2, une d’il y a huit mois score aussi 2. Même bucket. La window function choisit ensuite la révision la plus récente de chaque bucket et supprime le reste.

Le résultat est automatique : les sauvegardes récentes sont toutes gardées parce que chacune a un score distinct ; les anciennes sont élagées parce que beaucoup partagent le même score.

La tentative DQL qui n’a pas abouti

Les window functions ne font pas partie de DQL. Le langage de requête de Doctrine n’a pas de syntaxe pour OVER, PARTITION BY ou ROW_NUMBER(). Avant de passer au SQL brut, l’équipe a essayé de les ajouter.

L’approche FunctionNode fonctionne pour les fonctions SQL simples, comme on l’avait déjà vu avec la FTS. Un nœud RowNumber émettant ROW_NUMBER() est trivial :

class RowNumber extends FunctionNode
{
    public function getSql(SqlWalker $sqlWalker): string
    {
        return 'ROW_NUMBER()';
    }
}

La partie plus difficile est OVER(PARTITION BY ... ORDER BY ...). Un nœud de fonction Over a été ébauché, avec un nœud AST PartitionByClause personnalisé pour gérer la clause PARTITION BY :

class Over extends FunctionNode
{
    protected ?PartitionByClause $partitionByClause = null;
    protected ?OrderByClause $orderByClause = null;

    public function getSql(SqlWalker $sqlWalker): string
    {
        return 'OVER('
            .($this->partitionByClause
                ? $this->partitionByClause->dispatch($sqlWalker)
                : ($this->orderByClause
                    ? $this->orderByClause->dispatch($sqlWalker)
                    : ''))
            .')';
    }
}

Ça n’a jamais été terminé. Les classes ont été livrées marquées @deprecated et “NOT TESTED YET”. Le problème est la composabilité : FunctionNode de DQL fonctionne bien pour les fonctions qui apparaissent dans les clauses WHERE ou les expressions SELECT. Une window function comme ROW_NUMBER() OVER (PARTITION BY ...) est une structure différente : elle apparaît dans une position SELECT, modifie la sémantique de la requête englobante, et exige que le parseur gère PARTITION BY comme une extension de la grammaire DQL. Rendre ça suffisamment robuste pour être fiable en production est un investissement significatif. Passer à DBAL et écrire le SQL directement a pris un après-midi.

La requête, couche par couche

L’implémentation finale est trois requêtes imbriquées :

DELETE FROM revision
WHERE iri = ?
AND id NOT IN (
    SELECT id FROM (
        SELECT
            row_number() OVER (
                PARTITION BY num, iri
                ORDER BY num DESC, created_at DESC
            ) AS lines,
            *
        FROM (
            SELECT
                (
                    ( ln( EXTRACT(epoch FROM (now() - created_at)) )
                      / ( EXTRACT(epoch FROM (now() - created_at)) / 6000 ) )
                    * ( 1 / (EXTRACT(epoch FROM (now() - created_at)) / 60 / 1440) )
                    * 1000
                )::numeric::integer AS num,
                *
            FROM revision
            WHERE iri = ?
            ORDER BY created_at DESC
        ) AS lst
    ) AS rst
    WHERE lines = 1
);

Requête intérieure : calcule num, le score entier, pour chaque révision de l’IRI donnée. Les lignes sont triées par created_at DESC à ce stade.

Requête intermédiaire : exécute ROW_NUMBER() OVER (PARTITION BY num, iri ORDER BY num DESC, created_at DESC). Dans chaque bucket de score (num), les révisions sont numérotées à partir de 1 dans l’ordre décroissant d’âge. La révision la plus récente de chaque bucket obtient lines = 1.

Filtre extérieur : ne garde que les lignes lines = 1, une révision par bucket de score.

DELETE : supprime chaque révision pour cet IRI qui n’est pas dans l’ensemble gardé.

Le PARTITION BY num, iri est redondant sur l’IRI (toute la requête est déjà filtrée sur un IRI), mais rend l’intention explicite et garde la logique correcte si la requête est un jour réutilisée dans un contexte plus large.

La méthode est appelée depuis une requête complémentaire qui identifie quels IRIs ont accumulé plus qu’un seuil de révisions :

public function getIrisWithMoreRevisionThan(int $maxRevisionsCount, int $limit = 0, ?int $retencyDay = null): array
{
    $queryBuilder = $this
        ->createQueryBuilder('revision')
        ->select('revision.iri')
        ->groupBy('revision.iri')
        ->having('COUNT(1) > :maxRevisions')
        ->orderBy('COUNT(1)', Order::Descending->value)
        ->setParameter('maxRevisions', $maxRevisionsCount);

    // ...

    return array_column($queryBuilder->getQuery()->getResult(), 'iri');
}

Les deux méthodes tournent ensemble dans un nettoyage planifié : trouver les IRIs au-dessus du seuil, élaguer chacun.

Le câbler à une commande planifiée

La requête d’élagage ne s’exécute pas dans une requête HTTP. Elle tourne derrière une commande Symfony, appelée sur un planning.

La commande prend quelques options pour contrôler son agressivité :

#[AsCommand('app:purge:revision', 'Remove useless revisions')]
final class PurgeRevisionCommand extends Command
{
    protected function configure(): void
    {
        $this
            ->addOption('max-revisions', 'm', InputOption::VALUE_REQUIRED,
                'Seuil de révisions au-dessus duquel un IRI est élaguée', 30)
            ->addOption('limit', 'l', InputOption::VALUE_REQUIRED,
                'Nombre max d\'IRIs à traiter par exécution')
            ->addOption('delay', 'w', InputOption::VALUE_REQUIRED,
                'Délai en secondes entre chaque IRI')
            ->addOption('retencyDay', 'r', InputOption::VALUE_OPTIONAL,
                'Ne traiter que les IRIs dont la dernière révision est plus vieille que N jours');
    }

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $iris = $this->revisionRepository->getIrisWithMoreRevisionThan(
            (int) $input->getOption('max-revisions'),
            (int) $input->getOption('limit'),
            (int) $input->getOption('retencyDay'),
        );

        foreach ($iris as $iri) {
            $totalDeleted += $this->revisionRepository->deleteOldRevisionForIri($iri);
            usleep((int) $input->getOption('delay') * 1_000_000);
        }

        return Command::SUCCESS;
    }
}

L’option --delay mérite attention : sur une base de données chargée, marteler une centaine d’instructions DELETE dos à dos peut provoquer de la contention de verrous. Un petit sleep entre les itérations empêche l’élagage d’entrer en concurrence avec le trafic de production.

La commande tourne derrière deux entrées crontab avec des seuils différents :

# Horaire : garder 30 révisions par IRI, traiter 100 IRIs par exécution
0 * * * * php bin/console app:purge:revision --max-revisions 30 --limit 100

# Nocturne : pour le contenu non touché depuis un an, garder seulement 3
0 0 * * * php bin/console app:purge:revision --max-revisions 3 --limit 100 --retencyDay 365

La stratégie à deux niveaux est importante. Le job horaire garde 30 révisions par IRI, ce qui est un plafond raisonnable pour le contenu activement édité. Le job nocturne cible seulement les IRIs non mis à jour depuis plus d’un an et n’en garde que 3. Un article qui n’a pas bougé depuis douze mois n’a pas besoin de trente versions dans son historique.

Ce que ça donne en pratique

Un article sauvegardé 200 fois gardera typiquement 20 à 30 révisions après élagage : la plupart des sauvegardes récentes, quelques-unes du mois dernier, une ou deux de chaque trimestre de l’année précédente. Le décompte exact dépend de la distribution d’âge des sauvegardes, pas d’un plafond arbitraire.

Un article mis à jour pour la dernière fois il y a deux ans pourrait se retrouver avec 5 ou 6 révisions. Les modifications récentes sont toutes là ; l’ancien historique est compressé mais pas effacé.

Ce n’est pas un historique parfait. C’est un historique utile.

La frontière entre DQL et SQL brut

La tentative window function n’est pas un échec à cacher. C’est une donnée utile : FunctionNode fonctionne bien pour les fonctions scalaires dans les positions WHERE et SELECT, mais composer une expression complète ROW_NUMBER() OVER (PARTITION BY ... ORDER BY ...) en DQL est plus difficile qu’il n’y paraît. L’extension de grammaire, les nœuds AST, l’intégration du SQL walker : c’est une quantité non triviale de code pour quelque chose que le SQL natif gère en trois lignes.

La frontière pratique est grossièrement celle-ci : si une fonctionnalité PostgreSQL correspond à un appel de fonction d’arité fixe, le DQL personnalisé convient. Si elle nécessite une nouvelle syntaxe de clause (frames de fenêtre, CTEs, lateral joins), le DBAL natif est généralement le meilleur compromis.