src/whereInt.h

   1 /*
   2 ** 2013-11-12
   3 **
   4 ** The author disclaims copyright to this source code.  In place of
   5 ** a legal notice, here is a blessing:
   6 **
   7 **    May you do good and not evil.
   8 **    May you find forgiveness for yourself and forgive others.
   9 **    May you share freely, never taking more than you give.
  10 **
  11 *************************************************************************
  12 **
  13 ** This file contains structure and macro definitions for the query
  14 ** planner logic in "where.c".  These definitions are broken out into
  15 ** a separate source file for easier editing.
  16 */
  17 #ifndef SQLITE_WHEREINT_H
  18 #define SQLITE_WHEREINT_H
  19
  20 /*
  21 ** Trace output macros
  22 */
  23 #if defined(SQLITE_TEST) || defined(SQLITE_DEBUG)
  24 /***/ extern int sqlite3WhereTrace;
  25 #endif
  26 #if defined(SQLITE_DEBUG) \
  27     && (defined(SQLITE_TEST) || defined(SQLITE_ENABLE_WHERETRACE))
  28 # define WHERETRACE(K,X)  if(sqlite3WhereTrace&(K)) sqlite3DebugPrintf X
  29 # define WHERETRACE_ENABLED 1
  30 #else
  31 # define WHERETRACE(K,X)
  32 #endif
  33
  34 /* Forward references
  35 */
  36 typedef struct WhereClause WhereClause;
  37 typedef struct WhereMaskSet WhereMaskSet;
  38 typedef struct WhereOrInfo WhereOrInfo;
  39 typedef struct WhereAndInfo WhereAndInfo;
  40 typedef struct WhereLevel WhereLevel;
  41 typedef struct WhereLoop WhereLoop;
  42 typedef struct WherePath WherePath;
  43 typedef struct WhereTerm WhereTerm;
  44 typedef struct WhereLoopBuilder WhereLoopBuilder;
  45 typedef struct WhereScan WhereScan;
  46 typedef struct WhereOrCost WhereOrCost;
  47 typedef struct WhereOrSet WhereOrSet;
  48
  49 /*
  50 ** This object contains information needed to implement a single nested
  51 ** loop in WHERE clause.
  52 **
  53 ** Contrast this object with WhereLoop.  This object describes the
  54 ** implementation of the loop.  WhereLoop describes the algorithm.
  55 ** This object contains a pointer to the WhereLoop algorithm as one of
  56 ** its elements.
  57 **
  58 ** The WhereInfo object contains a single instance of this object for
  59 ** each term in the FROM clause (which is to say, for each of the
  60 ** nested loops as implemented).  The order of WhereLevel objects determines
  61 ** the loop nested order, with WhereInfo.a[0] being the outer loop and
  62 ** WhereInfo.a[WhereInfo.nLevel-1] being the inner loop.
  63 */
  64 struct WhereLevel {
  65   int iLeftJoin;        /* Memory cell used to implement LEFT OUTER JOIN */
  66   int iTabCur;          /* The VDBE cursor used to access the table */
  67   int iIdxCur;          /* The VDBE cursor used to access pIdx */
  68   int addrBrk;          /* Jump here to break out of the loop */
  69   int addrNxt;          /* Jump here to start the next IN combination */
  70   int addrSkip;         /* Jump here for next iteration of skip-scan */
  71   int addrCont;         /* Jump here to continue with the next loop cycle */
  72   int addrFirst;        /* First instruction of interior of the loop */
  73   int addrBody;         /* Beginning of the body of this loop */
  74   int regBignull;       /* big-null flag reg. True if a NULL-scan is needed */
  75   int addrBignull;      /* Jump here for next part of big-null scan */
  76 #ifndef SQLITE_LIKE_DOESNT_MATCH_BLOBS
  77   u32 iLikeRepCntr;     /* LIKE range processing counter register (times 2) */
  78   int addrLikeRep;      /* LIKE range processing address */
  79 #endif
  80   u8 iFrom;             /* Which entry in the FROM clause */
  81   u8 op, p3, p5;        /* Opcode, P3 & P5 of the opcode that ends the loop */
  82   int p1, p2;           /* Operands of the opcode used to end the loop */
  83   union {               /* Information that depends on pWLoop->wsFlags */
  84     struct {
  85       int nIn;              /* Number of entries in aInLoop[] */
  86       struct InLoop {
  87         int iCur;              /* The VDBE cursor used by this IN operator */
  88         int addrInTop;         /* Top of the IN loop */
  89         int iBase;             /* Base register of multi-key index record */
  90         int nPrefix;           /* Number of prior entires in the key */
  91         u8 eEndLoopOp;         /* IN Loop terminator. OP_Next or OP_Prev */
  92       } *aInLoop;           /* Information about each nested IN operator */
  93     } in;                 /* Used when pWLoop->wsFlags&WHERE_IN_ABLE */
  94     Index *pCovidx;       /* Possible covering index for WHERE_MULTI_OR */
  95   } u;
  96   struct WhereLoop *pWLoop;  /* The selected WhereLoop object */
  97   Bitmask notReady;          /* FROM entries not usable at this level */
  98 #ifdef SQLITE_ENABLE_STMT_SCANSTATUS
  99   int addrVisit;        /* Address at which row is visited */
 100 #endif
 101 };
 102
 103 /*
 104 ** Each instance of this object represents an algorithm for evaluating one
 105 ** term of a join.  Every term of the FROM clause will have at least
 106 ** one corresponding WhereLoop object (unless INDEXED BY constraints
 107 ** prevent a query solution - which is an error) and many terms of the
 108 ** FROM clause will have multiple WhereLoop objects, each describing a
 109 ** potential way of implementing that FROM-clause term, together with
 110 ** dependencies and cost estimates for using the chosen algorithm.
 111 **
 112 ** Query planning consists of building up a collection of these WhereLoop
 113 ** objects, then computing a particular sequence of WhereLoop objects, with
 114 ** one WhereLoop object per FROM clause term, that satisfy all dependencies
 115 ** and that minimize the overall cost.
 116 */
 117 struct WhereLoop {
 118   Bitmask prereq;       /* Bitmask of other loops that must run first */
 119   Bitmask maskSelf;     /* Bitmask identifying table iTab */
 120 #ifdef SQLITE_DEBUG
 121   char cId;             /* Symbolic ID of this loop for debugging use */
 122 #endif
 123   u8 iTab;              /* Position in FROM clause of table for this loop */
 124   u8 iSortIdx;          /* Sorting index number.  0==None */
 125   LogEst rSetup;        /* One-time setup cost (ex: create transient index) */
 126   LogEst rRun;          /* Cost of running each loop */
 127   LogEst nOut;          /* Estimated number of output rows */
 128   union {
 129     struct {               /* Information for internal btree tables */
 130       u16 nEq;               /* Number of equality constraints */
 131       u16 nBtm;              /* Size of BTM vector */
 132       u16 nTop;              /* Size of TOP vector */
 133       u16 nDistinctCol;      /* Index columns used to sort for DISTINCT */
 134       Index *pIndex;         /* Index used, or NULL */
 135     } btree;
 136     struct {               /* Information for virtual tables */
 137       int idxNum;            /* Index number */
 138       u8 needFree;           /* True if sqlite3_free(idxStr) is needed */
 139       i8 isOrdered;          /* True if satisfies ORDER BY */
 140       u16 omitMask;          /* Terms that may be omitted */
 141       char *idxStr;          /* Index identifier string */
 142     } vtab;
 143   } u;
 144   u32 wsFlags;          /* WHERE_* flags describing the plan */
 145   u16 nLTerm;           /* Number of entries in aLTerm[] */
 146   u16 nSkip;            /* Number of NULL aLTerm[] entries */
 147   /**** whereLoopXfer() copies fields above ***********************/
 148 # define WHERE_LOOP_XFER_SZ offsetof(WhereLoop,nLSlot)
 149   u16 nLSlot;           /* Number of slots allocated for aLTerm[] */
 150   WhereTerm **aLTerm;   /* WhereTerms used */
 151   WhereLoop *pNextLoop; /* Next WhereLoop object in the WhereClause */
 152   WhereTerm *aLTermSpace[3];  /* Initial aLTerm[] space */
 153 };
 154
 155 /* This object holds the prerequisites and the cost of running a
 156 ** subquery on one operand of an OR operator in the WHERE clause.
 157 ** See WhereOrSet for additional information
 158 */
 159 struct WhereOrCost {
 160   Bitmask prereq;     /* Prerequisites */
 161   LogEst rRun;        /* Cost of running this subquery */
 162   LogEst nOut;        /* Number of outputs for this subquery */
 163 };
 164
 165 /* The WhereOrSet object holds a set of possible WhereOrCosts that
 166 ** correspond to the subquery(s) of OR-clause processing.  Only the
 167 ** best N_OR_COST elements are retained.
 168 */
 169 #define N_OR_COST 3
 170 struct WhereOrSet {
 171   u16 n;                      /* Number of valid a[] entries */
 172   WhereOrCost a[N_OR_COST];   /* Set of best costs */
 173 };
 174
 175 /*
 176 ** Each instance of this object holds a sequence of WhereLoop objects
 177 ** that implement some or all of a query plan.
 178 **
 179 ** Think of each WhereLoop object as a node in a graph with arcs
 180 ** showing dependencies and costs for travelling between nodes.  (That is
 181 ** not a completely accurate description because WhereLoop costs are a
 182 ** vector, not a scalar, and because dependencies are many-to-one, not
 183 ** one-to-one as are graph nodes.  But it is a useful visualization aid.)
 184 ** Then a WherePath object is a path through the graph that visits some
 185 ** or all of the WhereLoop objects once.
 186 **
 187 ** The "solver" works by creating the N best WherePath objects of length
 188 ** 1.  Then using those as a basis to compute the N best WherePath objects
 189 ** of length 2.  And so forth until the length of WherePaths equals the
 190 ** number of nodes in the FROM clause.  The best (lowest cost) WherePath
 191 ** at the end is the chosen query plan.
 192 */
 193 struct WherePath {
 194   Bitmask maskLoop;     /* Bitmask of all WhereLoop objects in this path */
 195   Bitmask revLoop;      /* aLoop[]s that should be reversed for ORDER BY */
 196   LogEst nRow;          /* Estimated number of rows generated by this path */
 197   LogEst rCost;         /* Total cost of this path */
 198   LogEst rUnsorted;     /* Total cost of this path ignoring sorting costs */
 199   i8 isOrdered;         /* No. of ORDER BY terms satisfied. -1 for unknown */
 200   WhereLoop **aLoop;    /* Array of WhereLoop objects implementing this path */
 201 };
 202
 203 /*
 204 ** The query generator uses an array of instances of this structure to
 205 ** help it analyze the subexpressions of the WHERE clause.  Each WHERE
 206 ** clause subexpression is separated from the others by AND operators,
 207 ** usually, or sometimes subexpressions separated by OR.
 208 **
 209 ** All WhereTerms are collected into a single WhereClause structure.
 210 ** The following identity holds:
 211 **
 212 **        WhereTerm.pWC->a[WhereTerm.idx] == WhereTerm
 213 **
 214 ** When a term is of the form:
 215 **
 216 **              X <op> <expr>
 217 **
 218 ** where X is a column name and <op> is one of certain operators,
 219 ** then WhereTerm.leftCursor and WhereTerm.u.leftColumn record the
 220 ** cursor number and column number for X.  WhereTerm.eOperator records
 221 ** the <op> using a bitmask encoding defined by WO_xxx below.  The
 222 ** use of a bitmask encoding for the operator allows us to search
 223 ** quickly for terms that match any of several different operators.
 224 **
 225 ** A WhereTerm might also be two or more subterms connected by OR:
 226 **
 227 **         (t1.X <op> <expr>) OR (t1.Y <op> <expr>) OR ....
 228 **
 229 ** In this second case, wtFlag has the TERM_ORINFO bit set and eOperator==WO_OR
 230 ** and the WhereTerm.u.pOrInfo field points to auxiliary information that
 231 ** is collected about the OR clause.
 232 **
 233 ** If a term in the WHERE clause does not match either of the two previous
 234 ** categories, then eOperator==0.  The WhereTerm.pExpr field is still set
 235 ** to the original subexpression content and wtFlags is set up appropriately
 236 ** but no other fields in the WhereTerm object are meaningful.
 237 **
 238 ** When eOperator!=0, prereqRight and prereqAll record sets of cursor numbers,
 239 ** but they do so indirectly.  A single WhereMaskSet structure translates
 240 ** cursor number into bits and the translated bit is stored in the prereq
 241 ** fields.  The translation is used in order to maximize the number of
 242 ** bits that will fit in a Bitmask.  The VDBE cursor numbers might be
 243 ** spread out over the non-negative integers.  For example, the cursor
 244 ** numbers might be 3, 8, 9, 10, 20, 23, 41, and 45.  The WhereMaskSet
 245 ** translates these sparse cursor numbers into consecutive integers
 246 ** beginning with 0 in order to make the best possible use of the available
 247 ** bits in the Bitmask.  So, in the example above, the cursor numbers
 248 ** would be mapped into integers 0 through 7.
 249 **
 250 ** The number of terms in a join is limited by the number of bits
 251 ** in prereqRight and prereqAll.  The default is 64 bits, hence SQLite
 252 ** is only able to process joins with 64 or fewer tables.
 253 */
 254 struct WhereTerm {
 255   Expr *pExpr;            /* Pointer to the subexpression that is this term */
 256   WhereClause *pWC;       /* The clause this term is part of */
 257   LogEst truthProb;       /* Probability of truth for this expression */
 258   u16 wtFlags;            /* TERM_xxx bit flags.  See below */
 259   u16 eOperator;          /* A WO_xx value describing <op> */
 260   u8 nChild;              /* Number of children that must disable us */
 261   u8 eMatchOp;            /* Op for vtab MATCH/LIKE/GLOB/REGEXP terms */
 262   int iParent;            /* Disable pWC->a[iParent] when this term disabled */
 263   int leftCursor;         /* Cursor number of X in "X <op> <expr>" */
 264   int iField;             /* Field in (?,?,?) IN (SELECT...) vector */
 265   union {
 266     int leftColumn;         /* Column number of X in "X <op> <expr>" */
 267     WhereOrInfo *pOrInfo;   /* Extra information if (eOperator & WO_OR)!=0 */
 268     WhereAndInfo *pAndInfo; /* Extra information if (eOperator& WO_AND)!=0 */
 269   } u;
 270   Bitmask prereqRight;    /* Bitmask of tables used by pExpr->pRight */
 271   Bitmask prereqAll;      /* Bitmask of tables referenced by pExpr */
 272 };
 273
 274 /*
 275 ** Allowed values of WhereTerm.wtFlags
 276 */
 277 #define TERM_DYNAMIC    0x0001 /* Need to call sqlite3ExprDelete(db, pExpr) */
 278 #define TERM_VIRTUAL    0x0002 /* Added by the optimizer.  Do not code */
 279 #define TERM_CODED      0x0004 /* This term is already coded */
 280 #define TERM_COPIED     0x0008 /* Has a child */
 281 #define TERM_ORINFO     0x0010 /* Need to free the WhereTerm.u.pOrInfo object */
 282 #define TERM_ANDINFO    0x0020 /* Need to free the WhereTerm.u.pAndInfo obj */
 283 #define TERM_OR_OK      0x0040 /* Used during OR-clause processing */
 284 #ifdef SQLITE_ENABLE_STAT4
 285 #  define TERM_VNULL    0x0080 /* Manufactured x>NULL or x<=NULL term */
 286 #else
 287 #  define TERM_VNULL    0x0000 /* Disabled if not using stat4 */
 288 #endif
 289 #define TERM_LIKEOPT    0x0100 /* Virtual terms from the LIKE optimization */
 290 #define TERM_LIKECOND   0x0200 /* Conditionally this LIKE operator term */
 291 #define TERM_LIKE       0x0400 /* The original LIKE operator */
 292 #define TERM_IS         0x0800 /* Term.pExpr is an IS operator */
 293 #define TERM_VARSELECT  0x1000 /* Term.pExpr contains a correlated sub-query */
 294 #define TERM_HEURTRUTH  0x2000 /* Heuristic truthProb used */
 295 #ifdef SQLITE_ENABLE_STAT4
 296 #  define TERM_HIGHTRUTH  0x4000 /* Term excludes few rows */
 297 #else
 298 #  define TERM_HIGHTRUTH  0      /* Only used with STAT4 */
 299 #endif
 300
 301 /*
 302 ** An instance of the WhereScan object is used as an iterator for locating
 303 ** terms in the WHERE clause that are useful to the query planner.
 304 */
 305 struct WhereScan {
 306   WhereClause *pOrigWC;      /* Original, innermost WhereClause */
 307   WhereClause *pWC;          /* WhereClause currently being scanned */
 308   const char *zCollName;     /* Required collating sequence, if not NULL */
 309   Expr *pIdxExpr;            /* Search for this index expression */
 310   char idxaff;               /* Must match this affinity, if zCollName!=NULL */
 311   unsigned char nEquiv;      /* Number of entries in aEquiv[] */
 312   unsigned char iEquiv;      /* Next unused slot in aEquiv[] */
 313   u32 opMask;                /* Acceptable operators */
 314   int k;                     /* Resume scanning at this->pWC->a[this->k] */
 315   int aiCur[11];             /* Cursors in the equivalence class */
 316   i16 aiColumn[11];          /* Corresponding column number in the eq-class */
 317 };
 318
 319 /*
 320 ** An instance of the following structure holds all information about a
 321 ** WHERE clause.  Mostly this is a container for one or more WhereTerms.
 322 **
 323 ** Explanation of pOuter:  For a WHERE clause of the form
 324 **
 325 **           a AND ((b AND c) OR (d AND e)) AND f
 326 **
 327 ** There are separate WhereClause objects for the whole clause and for
 328 ** the subclauses "(b AND c)" and "(d AND e)".  The pOuter field of the
 329 ** subclauses points to the WhereClause object for the whole clause.
 330 */
 331 struct WhereClause {
 332   WhereInfo *pWInfo;       /* WHERE clause processing context */
 333   WhereClause *pOuter;     /* Outer conjunction */
 334   u8 op;                   /* Split operator.  TK_AND or TK_OR */
 335   u8 hasOr;                /* True if any a[].eOperator is WO_OR */
 336   int nTerm;               /* Number of terms */
 337   int nSlot;               /* Number of entries in a[] */
 338   WhereTerm *a;            /* Each a[] describes a term of the WHERE cluase */
 339 #if defined(SQLITE_SMALL_STACK)
 340   WhereTerm aStatic[1];    /* Initial static space for a[] */
 341 #else
 342   WhereTerm aStatic[8];    /* Initial static space for a[] */
 343 #endif
 344 };
 345
 346 /*
 347 ** A WhereTerm with eOperator==WO_OR has its u.pOrInfo pointer set to
 348 ** a dynamically allocated instance of the following structure.
 349 */
 350 struct WhereOrInfo {
 351   WhereClause wc;          /* Decomposition into subterms */
 352   Bitmask indexable;       /* Bitmask of all indexable tables in the clause */
 353 };
 354
 355 /*
 356 ** A WhereTerm with eOperator==WO_AND has its u.pAndInfo pointer set to
 357 ** a dynamically allocated instance of the following structure.
 358 */
 359 struct WhereAndInfo {
 360   WhereClause wc;          /* The subexpression broken out */
 361 };
 362
 363 /*
 364 ** An instance of the following structure keeps track of a mapping
 365 ** between VDBE cursor numbers and bits of the bitmasks in WhereTerm.
 366 **
 367 ** The VDBE cursor numbers are small integers contained in
 368 ** SrcList_item.iCursor and Expr.iTable fields.  For any given WHERE
 369 ** clause, the cursor numbers might not begin with 0 and they might
 370 ** contain gaps in the numbering sequence.  But we want to make maximum
 371 ** use of the bits in our bitmasks.  This structure provides a mapping
 372 ** from the sparse cursor numbers into consecutive integers beginning
 373 ** with 0.
 374 **
 375 ** If WhereMaskSet.ix[A]==B it means that The A-th bit of a Bitmask
 376 ** corresponds VDBE cursor number B.  The A-th bit of a bitmask is 1<<A.
 377 **
 378 ** For example, if the WHERE clause expression used these VDBE
 379 ** cursors:  4, 5, 8, 29, 57, 73.  Then the  WhereMaskSet structure
 380 ** would map those cursor numbers into bits 0 through 5.
 381 **
 382 ** Note that the mapping is not necessarily ordered.  In the example
 383 ** above, the mapping might go like this:  4->3, 5->1, 8->2, 29->0,
 384 ** 57->5, 73->4.  Or one of 719 other combinations might be used. It
 385 ** does not really matter.  What is important is that sparse cursor
 386 ** numbers all get mapped into bit numbers that begin with 0 and contain
 387 ** no gaps.
 388 */
 389 struct WhereMaskSet {
 390   int bVarSelect;               /* Used by sqlite3WhereExprUsage() */
 391   int n;                        /* Number of assigned cursor values */
 392   int ix[BMS];                  /* Cursor assigned to each bit */
 393 };
 394
 395 /*
 396 ** Initialize a WhereMaskSet object
 397 */
 398 #define initMaskSet(P)  (P)->n=0
 399
 400 /*
 401 ** This object is a convenience wrapper holding all information needed
 402 ** to construct WhereLoop objects for a particular query.
 403 */
 404 struct WhereLoopBuilder {
 405   WhereInfo *pWInfo;        /* Information about this WHERE */
 406   WhereClause *pWC;         /* WHERE clause terms */
 407   ExprList *pOrderBy;       /* ORDER BY clause */
 408   WhereLoop *pNew;          /* Template WhereLoop */
 409   WhereOrSet *pOrSet;       /* Record best loops here, if not NULL */
 410 #ifdef SQLITE_ENABLE_STAT4
 411   UnpackedRecord *pRec;     /* Probe for stat4 (if required) */
 412   int nRecValid;            /* Number of valid fields currently in pRec */
 413 #endif
 414   unsigned char bldFlags1;  /* First set of SQLITE_BLDF_* flags */
 415   unsigned char bldFlags2;  /* Second set of SQLITE_BLDF_* flags */
 416   unsigned int iPlanLimit;  /* Search limiter */
 417 };
 418
 419 /* Allowed values for WhereLoopBuider.bldFlags */
 420 #define SQLITE_BLDF1_INDEXED  0x0001   /* An index is used */
 421 #define SQLITE_BLDF1_UNIQUE   0x0002   /* All keys of a UNIQUE index used */
 422
 423 #define SQLITE_BLDF2_2NDPASS  0x0004   /* Second builder pass needed */
 424
 425 /* The WhereLoopBuilder.iPlanLimit is used to limit the number of
 426 ** index+constraint combinations the query planner will consider for a
 427 ** particular query.  If this parameter is unlimited, then certain
 428 ** pathological queries can spend excess time in the sqlite3WhereBegin()
 429 ** routine.  The limit is high enough that is should not impact real-world
 430 ** queries.
 431 **
 432 ** SQLITE_QUERY_PLANNER_LIMIT is the baseline limit.  The limit is
 433 ** increased by SQLITE_QUERY_PLANNER_LIMIT_INCR before each term of the FROM
 434 ** clause is processed, so that every table in a join is guaranteed to be
 435 ** able to propose a some index+constraint combinations even if the initial
 436 ** baseline limit was exhausted by prior tables of the join.
 437 */
 438 #ifndef SQLITE_QUERY_PLANNER_LIMIT
 439 # define SQLITE_QUERY_PLANNER_LIMIT 20000
 440 #endif
 441 #ifndef SQLITE_QUERY_PLANNER_LIMIT_INCR
 442 # define SQLITE_QUERY_PLANNER_LIMIT_INCR 1000
 443 #endif
 444
 445 /*
 446 ** Each instance of this object records a change to a single node
 447 ** in an expression tree to cause that node to point to a column
 448 ** of an index rather than an expression or a virtual column.  All
 449 ** such transformations need to be undone at the end of WHERE clause
 450 ** processing.
 451 */
 452 typedef struct WhereExprMod WhereExprMod;
 453 struct WhereExprMod {
 454   WhereExprMod *pNext;  /* Next translation on a list of them all */
 455   Expr *pExpr;          /* The Expr node that was transformed */
 456   Expr orig;            /* Original value of the Expr node */
 457 };
 458
 459 /*
 460 ** The WHERE clause processing routine has two halves.  The
 461 ** first part does the start of the WHERE loop and the second
 462 ** half does the tail of the WHERE loop.  An instance of
 463 ** this structure is returned by the first half and passed
 464 ** into the second half to give some continuity.
 465 **
 466 ** An instance of this object holds the complete state of the query
 467 ** planner.
 468 */
 469 struct WhereInfo {
 470   Parse *pParse;            /* Parsing and code generating context */
 471   SrcList *pTabList;        /* List of tables in the join */
 472   ExprList *pOrderBy;       /* The ORDER BY clause or NULL */
 473   ExprList *pResultSet;     /* Result set of the query */
 474   Expr *pWhere;             /* The complete WHERE clause */
 475   int aiCurOnePass[2];      /* OP_OpenWrite cursors for the ONEPASS opt */
 476   int iContinue;            /* Jump here to continue with next record */
 477   int iBreak;               /* Jump here to break out of the loop */
 478   int savedNQueryLoop;      /* pParse->nQueryLoop outside the WHERE loop */
 479   u16 wctrlFlags;           /* Flags originally passed to sqlite3WhereBegin() */
 480   LogEst iLimit;            /* LIMIT if wctrlFlags has WHERE_USE_LIMIT */
 481   u8 nLevel;                /* Number of nested loop */
 482   i8 nOBSat;                /* Number of ORDER BY terms satisfied by indices */
 483   u8 eOnePass;              /* ONEPASS_OFF, or _SINGLE, or _MULTI */
 484   u8 eDistinct;             /* One of the WHERE_DISTINCT_* values */
 485   unsigned bDeferredSeek :1;   /* Uses OP_DeferredSeek */
 486   unsigned untestedTerms :1;   /* Not all WHERE terms resolved by outer loop */
 487   unsigned bOrderedInnerLoop:1;/* True if only the inner-most loop is ordered */
 488   unsigned sorted :1;          /* True if really sorted (not just grouped) */
 489   LogEst nRowOut;           /* Estimated number of output rows */
 490   int iTop;                 /* The very beginning of the WHERE loop */
 491   WhereLoop *pLoops;        /* List of all WhereLoop objects */
 492   WhereExprMod *pExprMods;  /* Expression modifications */
 493   Bitmask revMask;          /* Mask of ORDER BY terms that need reversing */
 494   WhereClause sWC;          /* Decomposition of the WHERE clause */
 495   WhereMaskSet sMaskSet;    /* Map cursor numbers to bitmasks */
 496   WhereLevel a[1];          /* Information about each nest loop in WHERE */
 497 };
 498
 499 /*
 500 ** Private interfaces - callable only by other where.c routines.
 501 **
 502 ** where.c:
 503 */
 504 Bitmask sqlite3WhereGetMask(WhereMaskSet*,int);
 505 #ifdef WHERETRACE_ENABLED
 506 void sqlite3WhereClausePrint(WhereClause *pWC);
 507 void sqlite3WhereTermPrint(WhereTerm *pTerm, int iTerm);
 508 void sqlite3WhereLoopPrint(WhereLoop *p, WhereClause *pWC);
 509 #endif
 510 WhereTerm *sqlite3WhereFindTerm(
 511   WhereClause *pWC,     /* The WHERE clause to be searched */
 512   int iCur,             /* Cursor number of LHS */
 513   int iColumn,          /* Column number of LHS */
 514   Bitmask notReady,     /* RHS must not overlap with this mask */
 515   u32 op,               /* Mask of WO_xx values describing operator */
 516   Index *pIdx           /* Must be compatible with this index, if not NULL */
 517 );
 518
 519 /* wherecode.c: */
 520 #ifndef SQLITE_OMIT_EXPLAIN
 521 int sqlite3WhereExplainOneScan(
 522   Parse *pParse,                  /* Parse context */
 523   SrcList *pTabList,              /* Table list this loop refers to */
 524   WhereLevel *pLevel,             /* Scan to write OP_Explain opcode for */
 525   u16 wctrlFlags                  /* Flags passed to sqlite3WhereBegin() */
 526 );
 527 #else
 528 # define sqlite3WhereExplainOneScan(u,v,w,x) 0
 529 #endif /* SQLITE_OMIT_EXPLAIN */
 530 #ifdef SQLITE_ENABLE_STMT_SCANSTATUS
 531 void sqlite3WhereAddScanStatus(
 532   Vdbe *v,                        /* Vdbe to add scanstatus entry to */
 533   SrcList *pSrclist,              /* FROM clause pLvl reads data from */
 534   WhereLevel *pLvl,               /* Level to add scanstatus() entry for */
 535   int addrExplain                 /* Address of OP_Explain (or 0) */
 536 );
 537 #else
 538 # define sqlite3WhereAddScanStatus(a, b, c, d) ((void)d)
 539 #endif
 540 Bitmask sqlite3WhereCodeOneLoopStart(
 541   Parse *pParse,       /* Parsing context */
 542   Vdbe *v,             /* Prepared statement under construction */
 543   WhereInfo *pWInfo,   /* Complete information about the WHERE clause */
 544   int iLevel,          /* Which level of pWInfo->a[] should be coded */
 545   WhereLevel *pLevel,  /* The current level pointer */
 546   Bitmask notReady     /* Which tables are currently available */
 547 );
 548
 549 /* whereexpr.c: */
 550 void sqlite3WhereClauseInit(WhereClause*,WhereInfo*);
 551 void sqlite3WhereClauseClear(WhereClause*);
 552 void sqlite3WhereSplit(WhereClause*,Expr*,u8);
 553 Bitmask sqlite3WhereExprUsage(WhereMaskSet*, Expr*);
 554 Bitmask sqlite3WhereExprUsageNN(WhereMaskSet*, Expr*);
 555 Bitmask sqlite3WhereExprListUsage(WhereMaskSet*, ExprList*);
 556 void sqlite3WhereExprAnalyze(SrcList*, WhereClause*);
 557 void sqlite3WhereTabFuncArgs(Parse*, struct SrcList_item*, WhereClause*);
 558
 559
 560
 561
 562
 563 /*
 564 ** Bitmasks for the operators on WhereTerm objects.  These are all
 565 ** operators that are of interest to the query planner.  An
 566 ** OR-ed combination of these values can be used when searching for
 567 ** particular WhereTerms within a WhereClause.
 568 **
 569 ** Value constraints:
 570 **     WO_EQ    == SQLITE_INDEX_CONSTRAINT_EQ
 571 **     WO_LT    == SQLITE_INDEX_CONSTRAINT_LT
 572 **     WO_LE    == SQLITE_INDEX_CONSTRAINT_LE
 573 **     WO_GT    == SQLITE_INDEX_CONSTRAINT_GT
 574 **     WO_GE    == SQLITE_INDEX_CONSTRAINT_GE
 575 */
 576 #define WO_IN     0x0001
 577 #define WO_EQ     0x0002
 578 #define WO_LT     (WO_EQ<<(TK_LT-TK_EQ))
 579 #define WO_LE     (WO_EQ<<(TK_LE-TK_EQ))
 580 #define WO_GT     (WO_EQ<<(TK_GT-TK_EQ))
 581 #define WO_GE     (WO_EQ<<(TK_GE-TK_EQ))
 582 #define WO_AUX    0x0040       /* Op useful to virtual tables only */
 583 #define WO_IS     0x0080
 584 #define WO_ISNULL 0x0100
 585 #define WO_OR     0x0200       /* Two or more OR-connected terms */
 586 #define WO_AND    0x0400       /* Two or more AND-connected terms */
 587 #define WO_EQUIV  0x0800       /* Of the form A==B, both columns */
 588 #define WO_NOOP   0x1000       /* This term does not restrict search space */
 589
 590 #define WO_ALL    0x1fff       /* Mask of all possible WO_* values */
 591 #define WO_SINGLE 0x01ff       /* Mask of all non-compound WO_* values */
 592
 593 /*
 594 ** These are definitions of bits in the WhereLoop.wsFlags field.
 595 ** The particular combination of bits in each WhereLoop help to
 596 ** determine the algorithm that WhereLoop represents.
 597 */
 598 #define WHERE_COLUMN_EQ    0x00000001  /* x=EXPR */
 599 #define WHERE_COLUMN_RANGE 0x00000002  /* x<EXPR and/or x>EXPR */
 600 #define WHERE_COLUMN_IN    0x00000004  /* x IN (...) */
 601 #define WHERE_COLUMN_NULL  0x00000008  /* x IS NULL */
 602 #define WHERE_CONSTRAINT   0x0000000f  /* Any of the WHERE_COLUMN_xxx values */
 603 #define WHERE_TOP_LIMIT    0x00000010  /* x<EXPR or x<=EXPR constraint */
 604 #define WHERE_BTM_LIMIT    0x00000020  /* x>EXPR or x>=EXPR constraint */
 605 #define WHERE_BOTH_LIMIT   0x00000030  /* Both x>EXPR and x<EXPR */
 606 #define WHERE_IDX_ONLY     0x00000040  /* Use index only - omit table */
 607 #define WHERE_IPK          0x00000100  /* x is the INTEGER PRIMARY KEY */
 608 #define WHERE_INDEXED      0x00000200  /* WhereLoop.u.btree.pIndex is valid */
 609 #define WHERE_VIRTUALTABLE 0x00000400  /* WhereLoop.u.vtab is valid */
 610 #define WHERE_IN_ABLE      0x00000800  /* Able to support an IN operator */
 611 #define WHERE_ONEROW       0x00001000  /* Selects no more than one row */
 612 #define WHERE_MULTI_OR     0x00002000  /* OR using multiple indices */
 613 #define WHERE_AUTO_INDEX   0x00004000  /* Uses an ephemeral index */
 614 #define WHERE_SKIPSCAN     0x00008000  /* Uses the skip-scan algorithm */
 615 #define WHERE_UNQ_WANTED   0x00010000  /* WHERE_ONEROW would have been helpful*/
 616 #define WHERE_PARTIALIDX   0x00020000  /* The automatic index is partial */
 617 #define WHERE_IN_EARLYOUT  0x00040000  /* Perhaps quit IN loops early */
 618 #define WHERE_BIGNULL_SORT 0x00080000  /* Column nEq of index is BIGNULL */
 619
 620 #endif /* !defined(SQLITE_WHEREINT_H) */