GIN doesn't support full
index scans. The reason for this is that
extractValue is allowed to return zero keys, as
for example might happen with an empty string or empty array. In
such a case the indexed value will be unrepresented in the index.
It is therefore impossible for GIN to guarantee that a scan of the index can
find every row in the table.
Because of this limitation, when
extractQuery returns nkeys
= 0 to indicate that all values match the query,
GIN will emit an error. (If
there are multiple ANDed indexable operators in the query, this
happens only if they all return zero for nkeys.)
It is possible for an operator class to circumvent the
restriction against full index scan. To do that,
extractValue must return at least one (possibly
dummy) key for every indexed value, and
extractQuery must convert an unrestricted
search into a partial-match query that will scan the whole index.
This is inefficient but might be necessary to avoid corner-case
failures with operators such as LIKE or
GIN assumes that indexable
operators are strict. This means that
extractValue will not be called at all on a
NULL value (so the value will go unindexed), and
extractQuery will not be called on a NULL
comparison value either (instead, the query is presumed to be
A possibly more serious limitation is that GIN cannot handle NULL keys — for example, an array containing a NULL cannot be handled except by ignoring the NULL.
If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.