From 79368910cd0117fbeb939f3bfa7e64408890532a Mon Sep 17 00:00:00 2001 From: Andrea Esposito Date: Wed, 18 Nov 2026 21:56:31 +0100 Subject: [PATCH v1] doc: explain what can restrict an ltree GiST index search for lquery For ltree ~ lquery, ltree_consistent() prunes inner pages only via gist_between(), which range-compares the leading run of plain labels (lquery.firstgood), and gist_qe(), which checks label hashes in the signature. Star levels and their quantifiers are skipped entirely, and since recheck is always false the cost of that is invisible in EXPLAIN. Document which parts of a pattern can narrow the scan. Co-Authored-By: Claude Opus 5.5 --- doc/src/sgml/ltree.sgml | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/doc/src/sgml/ltree.sgml b/doc/src/sgml/ltree.sgml index ff3c227727b..3039fef8bbe 100644 --- a/doc/src/sgml/ltree.sgml +++ b/doc/src/sgml/ltree.sgml @@ -661,6 +661,25 @@ CREATE INDEX path_gist_idx ON test USING GIST (path); CREATE INDEX path_gist_idx ON test USING GIST (path gist_ltree_ops(siglen=100)); + + When such an index is used to match an lquery pattern, + the part of the index that is scanned can be narrowed in two ways. If + the pattern begins with one or more plain labels (labels without + modifiers, alternatives, quantifiers or !), the + search is limited to the part of the index holding paths that start + with those labels. In addition, labels that a matching path must + contain can be checked against the bitmap signature, which excludes + parts of the index where those labels do not occur. Since the + signature records only which labels occur somewhere in a path, and + not where, nothing else about the pattern restricts the search: star + symbols and their quantifiers, such as *{1,2}, and + the position of labels beyond the leading plain ones are checked only + when individual index entries are examined. Thus + Top.Science.*{1,2} scans the same index entries as + Top.Science.* does, and a pattern that does not + begin with a plain label, such as *.Science.*, can + be narrowed only by the signature. + -- 2.41.0.windows.3