#include "postgres.h"
#include "access/gin_private.h"
#include "access/relscan.h"
#include "pgstat.h"
#include "utils/memutils.h"
#include "utils/rel.h"

Include dependency graph for ginscan.c:

Functions
IndexScanDesc	ginbeginscan (Relation rel, int nkeys, int norderbys)

static GinScanEntry	ginFillScanEntry (GinScanOpaque so, OffsetNumber attnum, StrategyNumber strategy, int32 searchMode, Datum queryKey, GinNullCategory queryCategory, bool isPartialMatch, Pointer extra_data)

static void	ginScanKeyAddHiddenEntry (GinScanOpaque so, GinScanKey key, GinNullCategory queryCategory)

static void	ginFillScanKey (GinScanOpaque so, OffsetNumber attnum, StrategyNumber strategy, int32 searchMode, Datum query, uint32 nQueryValues, Datum queryValues, GinNullCategory queryCategories, bool partial_matches, Pointer extra_data)

void	ginFreeScanKeys (GinScanOpaque so)

void	ginNewScanKey (IndexScanDesc scan)

void	ginrescan (IndexScanDesc scan, ScanKey scankey, int nscankeys, ScanKey orderbys, int norderbys)

void	ginendscan (IndexScanDesc scan)

Function Documentation

◆ ginbeginscan()

IndexScanDesc ginbeginscan	(	Relation	rel,
		int	nkeys,
		int	norderbys
	)

Definition at line 25 of file ginscan.c.

{
    IndexScanDesc scan;
    GinScanOpaque so;
 
    /* no order by operators allowed */
    Assert(norderbys == 0);
 
    scan = RelationGetIndexScan(rel, nkeys, norderbys);
 
    /* allocate private workspace */
    so = (GinScanOpaque) palloc_object(GinScanOpaqueData);
    so->keys = NULL;
    so->nkeys = 0;
    so->tempCtx = AllocSetContextCreate(CurrentMemoryContext,
                                        "Gin scan temporary context",
                                        ALLOCSET_DEFAULT_SIZES);
    so->keyCtx = AllocSetContextCreate(CurrentMemoryContext,
                                       "Gin scan key context",
                                       ALLOCSET_DEFAULT_SIZES);
    initGinState(&so->ginstate, scan->indexRelation);
 
    scan->opaque = so;
 
    return scan;
}

References ALLOCSET_DEFAULT_SIZES, AllocSetContextCreate, Assert(), CurrentMemoryContext, GinScanOpaqueData::ginstate, IndexScanDescData::indexRelation, initGinState(), GinScanOpaqueData::keyCtx, GinScanOpaqueData::keys, GinScanOpaqueData::nkeys, IndexScanDescData::opaque, palloc_object, RelationGetIndexScan(), and GinScanOpaqueData::tempCtx.

Referenced by ginhandler().

◆ ginendscan()

void ginendscan ( IndexScanDesc scan )

Definition at line 503 of file ginscan.c.

{
    GinScanOpaque so = (GinScanOpaque) scan->opaque;
 
    ginFreeScanKeys(so);
 
    MemoryContextDelete(so->tempCtx);
    MemoryContextDelete(so->keyCtx);
 
    pfree(so);
}

References ginFreeScanKeys(), GinScanOpaqueData::keyCtx, MemoryContextDelete(), IndexScanDescData::opaque, pfree(), and GinScanOpaqueData::tempCtx.

Referenced by ginhandler().

◆ ginFillScanEntry()

static GinScanEntry ginFillScanEntry	(	GinScanOpaque	so,
		OffsetNumber	attnum,
		StrategyNumber	strategy,
		int32	searchMode,
		Datum	queryKey,
		GinNullCategory	queryCategory,
		bool	isPartialMatch,
		Pointer	extra_data
	)

static

Definition at line 57 of file ginscan.c.

{
    GinState   *ginstate = &so->ginstate;
    GinScanEntry scanEntry;
    uint32      i;
 
    /*
     * Look for an existing equivalent entry.
     *
     * Entries with non-null extra_data are never considered identical, since
     * we can't know exactly what the opclass might be doing with that.
     *
     * Also, give up de-duplication once we have 100 entries.  That avoids
     * spending O(N^2) time on probably-fruitless de-duplication of large
     * search-key sets.  The threshold of 100 is arbitrary but matches
     * predtest.c's threshold for what's a large array.
     */
    if (extra_data == NULL && so->totalentries < 100)
    {
        for (i = 0; i < so->totalentries; i++)
        {
            GinScanEntry prevEntry = so->entries[i];
 
            if (prevEntry->extra_data == NULL &&
                prevEntry->isPartialMatch == isPartialMatch &&
                prevEntry->strategy == strategy &&
                prevEntry->searchMode == searchMode &&
                prevEntry->attnum == attnum &&
                ginCompareEntries(ginstate, attnum,
                                  prevEntry->queryKey,
                                  prevEntry->queryCategory,
                                  queryKey,
                                  queryCategory) == 0)
            {
                /* Successful match */
                return prevEntry;
            }
        }
    }
 
    /* Nope, create a new entry */
    scanEntry = palloc_object(GinScanEntryData);
    scanEntry->queryKey = queryKey;
    scanEntry->queryCategory = queryCategory;
    scanEntry->isPartialMatch = isPartialMatch;
    scanEntry->extra_data = extra_data;
    scanEntry->strategy = strategy;
    scanEntry->searchMode = searchMode;
    scanEntry->attnum = attnum;
 
    scanEntry->buffer = InvalidBuffer;
    ItemPointerSetMin(&scanEntry->curItem);
    scanEntry->matchBitmap = NULL;
    scanEntry->matchIterator = NULL;
    scanEntry->matchResult.blockno = InvalidBlockNumber;
    scanEntry->matchNtuples = -1;
    scanEntry->list = NULL;
    scanEntry->nlist = 0;
    scanEntry->offset = InvalidOffsetNumber;
    scanEntry->isFinished = false;
    scanEntry->reduceResult = false;
 
    /* Add it to so's array */
    if (so->totalentries >= so->allocentries)
    {
        so->allocentries *= 2;
        so->entries = repalloc_array(so->entries, GinScanEntry, so->allocentries);
    }
    so->entries[so->totalentries++] = scanEntry;
 
    return scanEntry;
}

References GinScanOpaqueData::allocentries, GinScanEntryData::attnum, attnum, TBMIterateResult::blockno, GinScanEntryData::buffer, GinScanEntryData::curItem, GinScanOpaqueData::entries, GinScanEntryData::extra_data, ginCompareEntries(), GinScanOpaqueData::ginstate, i, InvalidBlockNumber, InvalidBuffer, InvalidOffsetNumber, GinScanEntryData::isFinished, GinScanEntryData::isPartialMatch, ItemPointerSetMin, GinScanEntryData::list, GinScanEntryData::matchBitmap, GinScanEntryData::matchIterator, GinScanEntryData::matchNtuples, GinScanEntryData::matchResult, GinScanEntryData::nlist, GinScanEntryData::offset, palloc_object, GinScanEntryData::queryCategory, GinScanEntryData::queryKey, GinScanEntryData::reduceResult, repalloc_array, GinScanEntryData::searchMode, GinScanEntryData::strategy, and GinScanOpaqueData::totalentries.

Referenced by ginFillScanKey(), and ginScanKeyAddHiddenEntry().

◆ ginFillScanKey()

static void ginFillScanKey	(	GinScanOpaque	so,
		OffsetNumber	attnum,
		StrategyNumber	strategy,
		int32	searchMode,
		Datum	query,
		uint32	nQueryValues,
		Datum *	queryValues,
		GinNullCategory *	queryCategories,
		bool *	partial_matches,
		Pointer *	extra_data
	)

static

Definition at line 158 of file ginscan.c.

{
    GinScanKey  key = &(so->keys[so->nkeys++]);
    GinState   *ginstate = &so->ginstate;
    uint32      i;
 
    key->nentries = nQueryValues;
    key->nuserentries = nQueryValues;
 
    /* Allocate one extra array slot for possible "hidden" entry */
    key->scanEntry = palloc_array(GinScanEntry, nQueryValues + 1);
    key->entryRes = palloc0_array(GinTernaryValue, nQueryValues + 1);
 
    key->query = query;
    key->queryValues = queryValues;
    key->queryCategories = queryCategories;
    key->extra_data = extra_data;
    key->strategy = strategy;
    key->searchMode = searchMode;
    key->attnum = attnum;
 
    /*
     * Initially, scan keys of GIN_SEARCH_MODE_ALL mode are marked
     * excludeOnly.  This might get changed later.
     */
    key->excludeOnly = (searchMode == GIN_SEARCH_MODE_ALL);
 
    ItemPointerSetMin(&key->curItem);
    key->curItemMatches = false;
    key->recheckCurItem = false;
    key->isFinished = false;
    key->nrequired = 0;
    key->nadditional = 0;
    key->requiredEntries = NULL;
    key->additionalEntries = NULL;
 
    ginInitConsistentFunction(ginstate, key);
 
    /* Set up normal scan entries using extractQueryFn's outputs */
    for (i = 0; i < nQueryValues; i++)
    {
        Datum       queryKey;
        GinNullCategory queryCategory;
        bool        isPartialMatch;
        Pointer     this_extra;
 
        queryKey = queryValues[i];
        queryCategory = queryCategories[i];
        isPartialMatch =
            (ginstate->canPartialMatch[attnum - 1] && partial_matches)
            ? partial_matches[i] : false;
        this_extra = (extra_data) ? extra_data[i] : NULL;
 
        key->scanEntry[i] = ginFillScanEntry(so, attnum,
                                             strategy, searchMode,
                                             queryKey, queryCategory,
                                             isPartialMatch, this_extra);
    }
 
    /*
     * For GIN_SEARCH_MODE_INCLUDE_EMPTY and GIN_SEARCH_MODE_EVERYTHING search
     * modes, we add the "hidden" entry immediately.  GIN_SEARCH_MODE_ALL is
     * handled later, since we might be able to omit the hidden entry for it.
     */
    if (searchMode == GIN_SEARCH_MODE_INCLUDE_EMPTY)
        ginScanKeyAddHiddenEntry(so, key, GIN_CAT_EMPTY_ITEM);
    else if (searchMode == GIN_SEARCH_MODE_EVERYTHING)
        ginScanKeyAddHiddenEntry(so, key, GIN_CAT_EMPTY_QUERY);
}

References attnum, GinState::canPartialMatch, GIN_CAT_EMPTY_ITEM, GIN_CAT_EMPTY_QUERY, GIN_SEARCH_MODE_ALL, GIN_SEARCH_MODE_EVERYTHING, GIN_SEARCH_MODE_INCLUDE_EMPTY, ginFillScanEntry(), ginInitConsistentFunction(), ginScanKeyAddHiddenEntry(), GinScanOpaqueData::ginstate, i, ItemPointerSetMin, sort-test::key, GinScanOpaqueData::keys, GinScanOpaqueData::nkeys, palloc0_array, and palloc_array.

◆ ginFreeScanKeys()

void ginFreeScanKeys ( GinScanOpaque so )

Definition at line 236 of file ginscan.c.

{
    uint32      i;
 
    if (so->keys == NULL)
        return;
 
    for (i = 0; i < so->totalentries; i++)
    {
        GinScanEntry entry = so->entries[i];
 
        if (entry->buffer != InvalidBuffer)
            ReleaseBuffer(entry->buffer);
        if (entry->list)
            pfree(entry->list);
        if (entry->matchIterator)
            tbm_end_private_iterate(entry->matchIterator);
        if (entry->matchBitmap)
            tbm_free(entry->matchBitmap);
    }
 
    MemoryContextReset(so->keyCtx);
 
    so->keys = NULL;
    so->nkeys = 0;
    so->entries = NULL;
    so->totalentries = 0;
}

References GinScanEntryData::buffer, GinScanOpaqueData::entries, i, InvalidBuffer, GinScanOpaqueData::keyCtx, GinScanOpaqueData::keys, GinScanEntryData::list, GinScanEntryData::matchBitmap, GinScanEntryData::matchIterator, MemoryContextReset(), GinScanOpaqueData::nkeys, pfree(), ReleaseBuffer(), tbm_end_private_iterate(), tbm_free(), and GinScanOpaqueData::totalentries.

Referenced by ginendscan(), gingetbitmap(), and ginrescan().

◆ ginNewScanKey()

void ginNewScanKey ( IndexScanDesc scan )

Definition at line 266 of file ginscan.c.

{
    ScanKey     scankey = scan->keyData;
    GinScanOpaque so = (GinScanOpaque) scan->opaque;
    int         i;
    int         numExcludeOnly;
    bool        hasNullQuery = false;
    bool        attrHasNormalScan[INDEX_MAX_KEYS] = {false};
    MemoryContext oldCtx;
 
    /*
     * Allocate all the scan key information in the key context. (If
     * extractQuery leaks anything there, it won't be reset until the end of
     * scan or rescan, but that's OK.)
     */
    oldCtx = MemoryContextSwitchTo(so->keyCtx);
 
    /* if no scan keys provided, allocate extra EVERYTHING GinScanKey */
    so->keys = (GinScanKey)
        palloc(Max(scan->numberOfKeys, 1) * sizeof(GinScanKeyData));
    so->nkeys = 0;
 
    /* initialize expansible array of GinScanEntry pointers */
    so->totalentries = 0;
    so->allocentries = 32;
    so->entries = (GinScanEntry *)
        palloc(so->allocentries * sizeof(GinScanEntry));
 
    so->isVoidRes = false;
 
    for (i = 0; i < scan->numberOfKeys; i++)
    {
        ScanKey     skey = &scankey[i];
        Datum      *queryValues;
        int32       nQueryValues = 0;
        bool       *partial_matches = NULL;
        Pointer    *extra_data = NULL;
        bool       *nullFlags = NULL;
        GinNullCategory *categories;
        int32       searchMode = GIN_SEARCH_MODE_DEFAULT;
 
        /*
         * We assume that GIN-indexable operators are strict, so a null query
         * argument means an unsatisfiable query.
         */
        if (skey->sk_flags & SK_ISNULL)
        {
            so->isVoidRes = true;
            break;
        }
 
        /* OK to call the extractQueryFn */
        queryValues = (Datum *)
            DatumGetPointer(FunctionCall7Coll(&so->ginstate.extractQueryFn[skey->sk_attno - 1],
                                              so->ginstate.supportCollation[skey->sk_attno - 1],
                                              skey->sk_argument,
                                              PointerGetDatum(&nQueryValues),
                                              UInt16GetDatum(skey->sk_strategy),
                                              PointerGetDatum(&partial_matches),
                                              PointerGetDatum(&extra_data),
                                              PointerGetDatum(&nullFlags),
                                              PointerGetDatum(&searchMode)));
 
        /*
         * If bogus searchMode is returned, treat as GIN_SEARCH_MODE_ALL; note
         * in particular we don't allow extractQueryFn to select
         * GIN_SEARCH_MODE_EVERYTHING.
         */
        if (searchMode < GIN_SEARCH_MODE_DEFAULT ||
            searchMode > GIN_SEARCH_MODE_ALL)
            searchMode = GIN_SEARCH_MODE_ALL;
 
        /* Non-default modes require the index to have placeholders */
        if (searchMode != GIN_SEARCH_MODE_DEFAULT)
            hasNullQuery = true;
 
        /*
         * In default mode, no keys means an unsatisfiable query.
         */
        if (queryValues == NULL || nQueryValues <= 0)
        {
            if (searchMode == GIN_SEARCH_MODE_DEFAULT)
            {
                so->isVoidRes = true;
                break;
            }
            nQueryValues = 0;   /* ensure sane value */
        }
 
        /*
         * Create GinNullCategory representation.  If the extractQueryFn
         * didn't create a nullFlags array, we assume everything is non-null.
         * While at it, detect whether any null keys are present.
         */
        categories = (GinNullCategory *) palloc0(nQueryValues * sizeof(GinNullCategory));
        if (nullFlags)
        {
            int32       j;
 
            for (j = 0; j < nQueryValues; j++)
            {
                if (nullFlags[j])
                {
                    categories[j] = GIN_CAT_NULL_KEY;
                    hasNullQuery = true;
                }
            }
        }
 
        ginFillScanKey(so, skey->sk_attno,
                       skey->sk_strategy, searchMode,
                       skey->sk_argument, nQueryValues,
                       queryValues, categories,
                       partial_matches, extra_data);
 
        /* Remember if we had any non-excludeOnly keys */
        if (searchMode != GIN_SEARCH_MODE_ALL)
            attrHasNormalScan[skey->sk_attno - 1] = true;
    }
 
    /*
     * Processing GIN_SEARCH_MODE_ALL scan keys requires us to make a second
     * pass over the scan keys.  Above we marked each such scan key as
     * excludeOnly.  If the involved column has any normal (not excludeOnly)
     * scan key as well, then we can leave it like that.  Otherwise, one
     * excludeOnly scan key must receive a GIN_CAT_EMPTY_QUERY hidden entry
     * and be set to normal (excludeOnly = false).
     */
    numExcludeOnly = 0;
    for (i = 0; i < so->nkeys; i++)
    {
        GinScanKey  key = &so->keys[i];
 
        if (key->searchMode != GIN_SEARCH_MODE_ALL)
            continue;
 
        if (!attrHasNormalScan[key->attnum - 1])
        {
            key->excludeOnly = false;
            ginScanKeyAddHiddenEntry(so, key, GIN_CAT_EMPTY_QUERY);
            attrHasNormalScan[key->attnum - 1] = true;
        }
        else
            numExcludeOnly++;
    }
 
    /*
     * If we left any excludeOnly scan keys as-is, move them to the end of the
     * scan key array: they must appear after normal key(s).
     */
    if (numExcludeOnly > 0)
    {
        GinScanKey  tmpkeys;
        int         iNormalKey;
        int         iExcludeOnly;
 
        /* We'd better have made at least one normal key */
        Assert(numExcludeOnly < so->nkeys);
        /* Make a temporary array to hold the re-ordered scan keys */
        tmpkeys = (GinScanKey) palloc(so->nkeys * sizeof(GinScanKeyData));
        /* Re-order the keys ... */
        iNormalKey = 0;
        iExcludeOnly = so->nkeys - numExcludeOnly;
        for (i = 0; i < so->nkeys; i++)
        {
            GinScanKey  key = &so->keys[i];
 
            if (key->excludeOnly)
            {
                memcpy(tmpkeys + iExcludeOnly, key, sizeof(GinScanKeyData));
                iExcludeOnly++;
            }
            else
            {
                memcpy(tmpkeys + iNormalKey, key, sizeof(GinScanKeyData));
                iNormalKey++;
            }
        }
        Assert(iNormalKey == so->nkeys - numExcludeOnly);
        Assert(iExcludeOnly == so->nkeys);
        /* ... and copy them back to so->keys[] */
        memcpy(so->keys, tmpkeys, so->nkeys * sizeof(GinScanKeyData));
        pfree(tmpkeys);
    }
 
    /*
     * If there are no regular scan keys, generate an EVERYTHING scankey to
     * drive a full-index scan.
     */
    if (so->nkeys == 0 && !so->isVoidRes)
    {
        hasNullQuery = true;
        ginFillScanKey(so, FirstOffsetNumber,
                       InvalidStrategy, GIN_SEARCH_MODE_EVERYTHING,
                       (Datum) 0, 0,
                       NULL, NULL, NULL, NULL);
    }
 
    /*
     * If the index is version 0, it may be missing null and placeholder
     * entries, which would render searches for nulls and full-index scans
     * unreliable.  Throw an error if so.
     */
    if (hasNullQuery && !so->isVoidRes)
    {
        GinStatsData ginStats;
 
        ginGetStats(scan->indexRelation, &ginStats);
        if (ginStats.ginVersion < 1)
            ereport(ERROR,
                    (errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
                     errmsg("old GIN indexes do not support whole-index scans nor searches for nulls"),
                     errhint("To fix this, do REINDEX INDEX \"%s\".",
                             RelationGetRelationName(scan->indexRelation))));
    }
 
    MemoryContextSwitchTo(oldCtx);
 
    pgstat_count_index_scan(scan->indexRelation);
    if (scan->instrument)
        scan->instrument->nsearches++;
}

References i, INDEX_MAX_KEYS, IndexScanDescData::keyData, and IndexScanDescData::opaque.

Referenced by gingetbitmap().

◆ ginrescan()

void ginrescan	(	IndexScanDesc	scan,
		ScanKey	scankey,
		int	nscankeys,
		ScanKey	orderbys,
		int	norderbys
	)

Definition at line 490 of file ginscan.c.

{
    GinScanOpaque so = (GinScanOpaque) scan->opaque;
 
    ginFreeScanKeys(so);
 
    if (scankey && scan->numberOfKeys > 0)
        memcpy(scan->keyData, scankey, scan->numberOfKeys * sizeof(ScanKeyData));
}

References ginFreeScanKeys(), IndexScanDescData::keyData, IndexScanDescData::numberOfKeys, and IndexScanDescData::opaque.

Referenced by ginhandler().

◆ ginScanKeyAddHiddenEntry()

static void ginScanKeyAddHiddenEntry	(	GinScanOpaque	so,
		GinScanKey	key,
		GinNullCategory	queryCategory
	)

static

Definition at line 142 of file ginscan.c.

{
    int         i = key->nentries++;
 
    /* strategy is of no interest because this is not a partial-match item */
    key->scanEntry[i] = ginFillScanEntry(so, key->attnum,
                                         InvalidStrategy, key->searchMode,
                                         (Datum) 0, queryCategory,
                                         false, NULL);
}

References ginFillScanEntry(), i, InvalidStrategy, and sort-test::key.

Referenced by ginFillScanKey().

Functions

Function Documentation

◆ ginbeginscan()

◆ ginendscan()

◆ ginFillScanEntry()

◆ ginFillScanKey()

◆ ginFreeScanKeys()

◆ ginNewScanKey()

◆ ginrescan()

◆ ginScanKeyAddHiddenEntry()