ginscan.c File Reference

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

Include dependency graph for ginscan.c:

Go to the source code of this file.

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 26 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, fb(), IndexScanDescData::indexRelation, initGinState(), IndexScanDescData::opaque, palloc_object, and RelationGetIndexScan().

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 fb(), ginFreeScanKeys(), MemoryContextDelete(), IndexScanDescData::opaque, and pfree().

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 58 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 GinScanEntryData::attnum, attnum, TBMIterateResult::blockno, GinScanEntryData::buffer, GinScanEntryData::curItem, GinScanEntryData::extra_data, fb(), ginCompareEntries(), 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, and GinScanEntryData::strategy.

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 159 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, fb(), GIN_CAT_EMPTY_ITEM, GIN_CAT_EMPTY_QUERY, GIN_SEARCH_MODE_ALL, GIN_SEARCH_MODE_EVERYTHING, GIN_SEARCH_MODE_INCLUDE_EMPTY, ginFillScanEntry(), ginInitConsistentFunction(), ginScanKeyAddHiddenEntry(), i, ItemPointerSetMin, palloc0_array, and palloc_array.

Referenced by ginNewScanKey().

ginFreeScanKeys()

void ginFreeScanKeys

(

GinScanOpaque

so

)

Definition at line 237 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, fb(), i, InvalidBuffer, GinScanEntryData::list, GinScanEntryData::matchBitmap, GinScanEntryData::matchIterator, MemoryContextReset(), pfree(), ReleaseBuffer(), tbm_end_private_iterate(), and tbm_free().

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

ginNewScanKey()

void ginNewScanKey

(

IndexScanDesc

scan

)

Definition at line 267 of file ginscan.c.

{
    ScanKey     scankey = scan->keyData;
    GinScanOpaque so = (GinScanOpaque) scan->opaque;
    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 (int 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 (uint32 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 (uint32 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 Assert, DatumGetPointer(), ereport, errcode(), errhint(), errmsg, ERROR, fb(), FirstOffsetNumber, FunctionCall7Coll(), GIN_CAT_EMPTY_QUERY, GIN_CAT_NULL_KEY, GIN_SEARCH_MODE_ALL, GIN_SEARCH_MODE_DEFAULT, GIN_SEARCH_MODE_EVERYTHING, ginFillScanKey(), ginGetStats(), ginScanKeyAddHiddenEntry(), i, INDEX_MAX_KEYS, IndexScanDescData::indexRelation, IndexScanDescData::instrument, InvalidStrategy, j, IndexScanDescData::keyData, Max, memcpy(), MemoryContextSwitchTo(), IndexScanInstrumentation::nsearches, IndexScanDescData::numberOfKeys, IndexScanDescData::opaque, palloc(), palloc0(), pfree(), pgstat_count_index_scan, PointerGetDatum, RelationGetRelationName, SK_ISNULL, and UInt16GetDatum().

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 fb(), ginFreeScanKeys(), IndexScanDescData::keyData, memcpy(), IndexScanDescData::numberOfKeys, and IndexScanDescData::opaque.

Referenced by ginhandler().

ginScanKeyAddHiddenEntry()

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

static

Definition at line 143 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 fb(), ginFillScanEntry(), i, and InvalidStrategy.

Referenced by ginFillScanKey(), and ginNewScanKey().