Indexelt szövegkeresés

Az indexelt szövegkeresés a szövegkeresés gyorsítótárral bemelegített változata. Az első hívás létrehoz egy trigramokat és azonosító-előfordulásokat tartalmazó, lemezen tárolt adattárat; a további hívások ezt használva kihagyják azokat a fájlokat, amelyek nyilvánvalóan nem tartalmazhatják a mintát. Így nagy adattárak ismételt lekérdezéseinél jelentősen csökken a késleltetés, démon vagy figyelőfolyamat bevezetése nélkül.

A bemelegített szövegkeresési felület mostantól a következőket is tartalmazza:

• egyindexes keresés
• ismételt --index-dir többindexes keresés
• jegyzékfájl-alapú halmazkeresés
• életciklus-tudatos elavultindex-kezelés
• terveződiagnosztika a --trace-plan segítségével

Az index a greph-index CLI alatt, valamint a Greph::buildTextIndex() / Greph::searchTextIndexed() homlokzati metódusokon keresztül érhető el.

Az index létrehozása

# Full build at the current directory
./vendor/bin/greph-index build .

# Full build at an explicit root
./vendor/bin/greph-index build path/to/repo

# Use a non-default index directory
./vendor/bin/greph-index build . --index-dir /tmp/greph-index

# Build with an explicit lifecycle policy
./vendor/bin/greph-index build . \
  --lifecycle opportunistic-refresh \
  --auto-refresh-max-files 32 \
  --auto-refresh-max-bytes 1048576

Az index alapértelmezés szerint itt tárolódik: <root>/.greph-index/.

A sikeres létrehozás egyetlen soros összefoglalót ír ki:

Built index for 2547 files in .greph-index (193428 trigrams, +2547 ~0 -0 =0)

A négy számláló a hozzáadott, frissített, törölt és változatlan fájlok számát jelzi. Új felépítéskor a hozzáadott fájlok száma megegyezik a fájlok számával, a többi érték pedig nulla.

Az index frissítése

./vendor/bin/greph-index refresh .

A refresh újra bejárja az indexelt gyökeret, minden fájl hashét kiszámítja, és csak a megváltozott metaadatú bejegyzéseket írja át. A kimenet ugyanazt a négy számlálót használja, így pontosan láthatja, mi változott:

Refreshed index for 2547 files in .greph-index (193428 trigrams, +3 ~7 -1 =2536)

Ha a manual-refresh használatakor szerkeszti a követett fájlokat, futtassa a refresh parancsot. A opportunistic-refresh indexeknél a Greph keresés közben automatikusan frissítheti az indexet, ha a módosult fájlok halmaza még elég kicsi.

Életciklus-profilok

A Greph nem használ démont. Az életciklus-profilok szabályozzák, hogyan viselkedik a bemelegített index a forrásfa változásakor:

• static: soha ne ellenőrizze az aktualitást, és ne módosítson automatikusan
• manual-refresh: jelezze az elavultságot a stats felületen, de keresés közben soha ne frissítsen
• opportunistic-refresh: csak akkor frissítsen keresés közben, ha a módosult fájlok száma a beállított küszöb alatt van
• strict-stale-check: frissítés helyett utasítsa el az elavult bemelegített kereséseket

Használja a greph-index stats --dry-refresh lehetőséget, hogy előre megvizsgálja, mit tenne a bemelegített keresés:

./vendor/bin/greph-index stats . --dry-refresh

Lekérdezés az indexben

# Fixed-string search
./vendor/bin/greph-index search -F "function" .

# Case-insensitive whole-word
./vendor/bin/greph-index search -F -i -w "function" .

# Counts
./vendor/bin/greph-index search -F -c "function" .

# Files only
./vendor/bin/greph-index search -F -l "function" .

# Multi-index search
./vendor/bin/greph-index search -F "apply_filters" . \
  --index-dir wordpress/.greph-index \
  --index-dir wp-content/plugins/my-plugin/.greph-index \
  --show-index-origin

# Regex search
./vendor/bin/greph-index search "function\s+\w+" .

# JSON output
./vendor/bin/greph-index search --json -F "function" .

# Planner trace to stderr
./vendor/bin/greph-index search --trace-plan -F "function" .

A jelzőkészlet megegyezik a natív szövegkeresésével. A teljes listát lásd a CLI referenciában.

Ha a kért helyen nem létezik az index, a greph-index search hibát jelez. Ez a parancs nem áll át automatikusan index nélküli keresésre (az AST-parancsoknál van erre külön bekapcsolható --fallback scan, a szövegparancsnál viszont nincs). Előbb építse fel az indexet.

Elnevezett indexkészletek

Ha ugyanabban a bemelegített elrendezésben keres ismételten, a --index-dir jelzők ismételt megadása helyett használjon jegyzékfájlt:

{
  "name": "wordpress-local",
  "indexes": [
    {
      "name": "core-text",
      "root": "wordpress",
      "mode": "text",
      "lifecycle": "static",
      "priority": 100
    },
    {
      "name": "plugin-text",
      "root": "wp-content/plugins/my-plugin",
      "mode": "text",
      "lifecycle": "opportunistic-refresh",
      "max_changed_files": 16,
      "max_changed_bytes": 262144,
      "priority": 200
    }
  ]
}

Mentse .greph-index-set.json néven, majd:

./vendor/bin/greph-index set build
./vendor/bin/greph-index set stats --dry-refresh
./vendor/bin/greph-index set search --show-index-origin -F "apply_filters" .

Mit tárol az index

A szövegindex trigramok és azonosító-előfordulások adattára. Minden indexelt fájlból a Greph a következőket nyeri ki:

• Trigramkészlet: a fájltartalomban előforduló három bájtos sorozatok halmaza. Durva előszűrőként szolgál a szó szerinti és a reguláris kifejezéses lekérdezéseknél.
• Azonosító-előfordulások: a fájlban lévő, azonosítóra emlékeztető tokenek halmaza ([A-Za-z_][A-Za-z0-9_]*). Egész szavas kereséseket gyorsít.
• Életciklus-metaadatok: tárolt küszöbértékek és az elavultság-ellenőrzés viselkedése.
• Tartalom-metaadatok: méret és módosítási idő a frissítési döntésekhez és az elavultság ellenőrzéséhez.

Lekérdezéskor a Greph ugyanilyen mintákat nyer ki a keresési mintából (trigramokat a szó szerinti részkarakterláncokból, azonosítótokent az egész szavas mintákból), metszi az előfordulási halmazokat, és csak a találatokhoz tartozó fájlokat olvassa be újra. A metszetben megmaradó fájlokat ugyanaz a keresőmotor vizsgálja át, mint a natív szöveges módban.

Egyes bemelegített összesítő lekérdezéseket a Greph közvetlenül is megválaszolhat az előfordulási halmazokból:

• egész szavas -l
• egész szavas -L
• egész szavas -q

Így egyáltalán nem kell újra megnyitni a jelölt fájlokat, ha az előfordulási halmazok már bizonyítják a választ.

Ugyanez az elv, mint a ripgrep opcionális előindexelése és a codesearch trigramindexe, de kifejezetten a lemezen tárolt olyan mintákra építve, amelyeket a bemelegített PHP tud a leggyorsabban elérni.

Terveződiagnosztika

A --trace-plan kiírja a bemelegített szövegkereső tervezőjének döntését a stderr kimenetre, miközben a normál eredményfolyam változatlan marad.

A nyomkövetés a következőket tartalmazza:

• életciklus-profil
• kiválasztott fájlok száma
• a jelöltek forrása (full-scan, trigram-postings, word-postings vagy invert-scan)
• előfordulási halmazokban szereplő kifejezések száma
• jelölt és ellenőrzött fájlok száma
• a közvetlen összesítésre való jogosultság
• a lekérdezési gyorsítótárra való jogosultság és feltöltési döntés

Mikor használja

Az indexelt mód a megfelelő eszköz, ha:

• Egymás után sokszor keres ugyanabban a tárolóban (CI-feladatok, ügynökciklusok, IDE-integrációk).
• A tároló elég nagy ahhoz, hogy a natív keresés legyen a szűk keresztmetszet.
• A minták szó szerinti részkarakterláncokat vagy azonosítótokeneket tartalmaznak, amelyekre az index előszűrhet.

A natív keresés továbbra is a megfelelő eszköz, ha:

• Kis tárolóban keres, ahol a felépítés költsége meghatározó.
• Egyszeri keresést végez egy olyan útvonalon, amelyre később nem fog újra keresni.
• Egyetlen eseti futtatással szeretné megkapni az összes találatot, és nem akar indexet karbantartani.

A README közzétett benchmarkeredményei szerint a bemelegített indexelt mód a WordPress korpuszon végzett reguláris kifejezéses lekérdezéseknél, valamint a találatok számát, a találatot tartalmazó fájlokat és a találat nélküli fájlokat vizsgáló lekérdezéseknél megelőzi a rg és a grep módot. Egyszerű szó szerinti lekérdezéseknél gyorsabb a grep módnál, de kissé elmarad a rg módtól.

Programozott használat

use Greph\Greph;
use Greph\Text\TextSearchOptions;
use Greph\Index\IndexLifecycleProfile;

// Build once
Greph::buildTextIndex('.', lifecycle: IndexLifecycleProfile::OpportunisticRefresh);

// Refresh after edits
Greph::refreshTextIndex('.');

// Query
$results = Greph::searchTextIndexed(
    'function',
    'src',
    new TextSearchOptions(fixedString: true),
);

A searchTextIndexed ugyanazt a TextSearchOptions fogadja el, mint a natív szövegkeresés, és ugyanolyan alakú list<TextFileResult> eredményt ad vissza. Több indexet vagy jegyzékfájlt használó munkafolyamatokhoz használja a searchTextIndexedMany(...) és a searchTextIndexedSet(...) lehetőséget.