System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 019854c2315a58c860b2afdce46146bb1ae069d6:


0000: 3c 21 44 4f 43 54 59 50 45 20 48 54 4d 4c 20 50  <!DOCTYPE HTML P
0010: 55 42 4c 49 43 20 22 2d 2f 2f 57 33 43 2f 2f 44  UBLIC "-//W3C//D
0020: 54 44 20 48 54 4d 4c 20 34 2e 30 31 2f 2f 45 4e  TD HTML 4.01//EN
0030: 22 20 22 68 74 74 70 3a 2f 2f 77 77 77 2e 77 33  " "http://www.w3
0040: 2e 6f 72 67 2f 54 52 2f 68 74 6d 6c 34 2f 73 74  .org/TR/html4/st
0050: 72 69 63 74 2e 64 74 64 22 3e 0a 3c 68 74 6d 6c  rict.dtd">.<html
0060: 3e 3c 68 65 61 64 3e 0a 3c 6d 65 74 61 20 68 74  ><head>.<meta ht
0070: 74 70 2d 65 71 75 69 76 3d 22 63 6f 6e 74 65 6e  tp-equiv="conten
0080: 74 2d 74 79 70 65 22 20 63 6f 6e 74 65 6e 74 3d  t-type" content=
0090: 22 74 65 78 74 2f 68 74 6d 6c 3b 20 63 68 61 72  "text/html; char
00a0: 73 65 74 3d 55 54 46 2d 38 22 3e 0a 3c 74 69 74  set=UTF-8">.<tit
00b0: 6c 65 3e 54 68 65 20 56 69 72 74 75 61 6c 20 54  le>The Virtual T
00c0: 61 62 6c 65 20 4d 65 63 68 61 6e 69 73 6d 20 4f  able Mechanism O
00d0: 66 20 53 51 4c 69 74 65 3c 2f 74 69 74 6c 65 3e  f SQLite</title>
00e0: 0a 3c 73 74 79 6c 65 20 74 79 70 65 3d 22 74 65  .<style type="te
00f0: 78 74 2f 63 73 73 22 3e 0a 62 6f 64 79 20 7b 0a  xt/css">.body {.
0100: 20 20 20 20 6d 61 72 67 69 6e 3a 20 61 75 74 6f      margin: auto
0110: 3b 0a 20 20 20 20 66 6f 6e 74 2d 66 61 6d 69 6c  ;.    font-famil
0120: 79 3a 20 56 65 72 64 61 6e 61 2c 20 73 61 6e 73  y: Verdana, sans
0130: 2d 73 65 72 69 66 3b 0a 20 20 20 20 70 61 64 64  -serif;.    padd
0140: 69 6e 67 3a 20 38 70 78 20 31 25 3b 0a 7d 0a 0a  ing: 8px 1%;.}..
0150: 61 20 7b 20 63 6f 6c 6f 72 3a 20 23 30 34 34 61  a { color: #044a
0160: 36 34 20 7d 0a 61 3a 76 69 73 69 74 65 64 20 7b  64 }.a:visited {
0170: 20 63 6f 6c 6f 72 3a 20 23 37 33 34 35 35 39 20   color: #734559 
0180: 7d 0a 0a 2e 6c 6f 67 6f 20 7b 20 70 6f 73 69 74  }...logo { posit
0190: 69 6f 6e 3a 61 62 73 6f 6c 75 74 65 3b 20 6d 61  ion:absolute; ma
01a0: 72 67 69 6e 3a 33 70 78 3b 20 7d 0a 2e 74 61 67  rgin:3px; }..tag
01b0: 6c 69 6e 65 20 7b 0a 20 20 66 6c 6f 61 74 3a 72  line {.  float:r
01c0: 69 67 68 74 3b 0a 20 20 74 65 78 74 2d 61 6c 69  ight;.  text-ali
01d0: 67 6e 3a 72 69 67 68 74 3b 0a 20 20 66 6f 6e 74  gn:right;.  font
01e0: 2d 73 74 79 6c 65 3a 69 74 61 6c 69 63 3b 0a 20  -style:italic;. 
01f0: 20 77 69 64 74 68 3a 33 30 30 70 78 3b 0a 20 20   width:300px;.  
0200: 6d 61 72 67 69 6e 3a 31 32 70 78 3b 0a 20 20 6d  margin:12px;.  m
0210: 61 72 67 69 6e 2d 74 6f 70 3a 35 38 70 78 3b 0a  argin-top:58px;.
0220: 7d 0a 0a 2e 6d 65 6e 75 62 61 72 20 7b 0a 20 20  }...menubar {.  
0230: 63 6c 65 61 72 3a 20 62 6f 74 68 3b 0a 20 20 62  clear: both;.  b
0240: 6f 72 64 65 72 2d 72 61 64 69 75 73 3a 20 38 70  order-radius: 8p
0250: 78 3b 0a 20 20 62 61 63 6b 67 72 6f 75 6e 64 3a  x;.  background:
0260: 20 23 30 34 34 61 36 34 3b 0a 20 20 70 61 64 64   #044a64;.  padd
0270: 69 6e 67 3a 20 30 70 78 3b 0a 20 20 6d 61 72 67  ing: 0px;.  marg
0280: 69 6e 3a 20 30 70 78 3b 0a 20 20 63 65 6c 6c 2d  in: 0px;.  cell-
0290: 73 70 61 63 69 6e 67 3a 20 30 70 78 3b 0a 7d 20  spacing: 0px;.} 
02a0: 20 20 20 0a 2e 74 6f 6f 6c 62 61 72 20 7b 0a 20     ..toolbar {. 
02b0: 20 74 65 78 74 2d 61 6c 69 67 6e 3a 20 63 65 6e   text-align: cen
02c0: 74 65 72 3b 0a 20 20 6c 69 6e 65 2d 68 65 69 67  ter;.  line-heig
02d0: 68 74 3a 20 31 2e 36 65 6d 3b 0a 20 20 6d 61 72  ht: 1.6em;.  mar
02e0: 67 69 6e 3a 20 30 3b 0a 20 20 70 61 64 64 69 6e  gin: 0;.  paddin
02f0: 67 3a 20 30 70 78 20 38 70 78 3b 0a 7d 0a 2e 74  g: 0px 8px;.}..t
0300: 6f 6f 6c 62 61 72 20 61 20 7b 20 63 6f 6c 6f 72  oolbar a { color
0310: 3a 20 77 68 69 74 65 3b 20 74 65 78 74 2d 64 65  : white; text-de
0320: 63 6f 72 61 74 69 6f 6e 3a 20 6e 6f 6e 65 3b 20  coration: none; 
0330: 70 61 64 64 69 6e 67 3a 20 36 70 78 20 31 32 70  padding: 6px 12p
0340: 78 3b 20 7d 0a 2e 74 6f 6f 6c 62 61 72 20 61 3a  x; }..toolbar a:
0350: 76 69 73 69 74 65 64 20 7b 20 63 6f 6c 6f 72 3a  visited { color:
0360: 20 77 68 69 74 65 3b 20 7d 0a 2e 74 6f 6f 6c 62   white; }..toolb
0370: 61 72 20 61 3a 68 6f 76 65 72 20 7b 20 63 6f 6c  ar a:hover { col
0380: 6f 72 3a 20 23 30 34 34 61 36 34 3b 20 62 61 63  or: #044a64; bac
0390: 6b 67 72 6f 75 6e 64 3a 20 77 68 69 74 65 3b 20  kground: white; 
03a0: 7d 0a 0a 2e 63 6f 6e 74 65 6e 74 20 20 20 20 7b  }...content    {
03b0: 20 6d 61 72 67 69 6e 3a 20 35 25 3b 20 7d 0a 2e   margin: 5%; }..
03c0: 63 6f 6e 74 65 6e 74 20 64 74 20 7b 20 66 6f 6e  content dt { fon
03d0: 74 2d 77 65 69 67 68 74 3a 62 6f 6c 64 3b 20 7d  t-weight:bold; }
03e0: 0a 2e 63 6f 6e 74 65 6e 74 20 64 64 20 7b 20 6d  ..content dd { m
03f0: 61 72 67 69 6e 2d 62 6f 74 74 6f 6d 3a 20 32 35  argin-bottom: 25
0400: 70 78 3b 20 6d 61 72 67 69 6e 2d 6c 65 66 74 3a  px; margin-left:
0410: 32 30 25 3b 20 7d 0a 2e 63 6f 6e 74 65 6e 74 20  20%; }..content 
0420: 75 6c 20 7b 20 70 61 64 64 69 6e 67 3a 30 70 78  ul { padding:0px
0430: 3b 20 70 61 64 64 69 6e 67 2d 6c 65 66 74 3a 20  ; padding-left: 
0440: 31 35 70 78 3b 20 6d 61 72 67 69 6e 3a 30 70 78  15px; margin:0px
0450: 3b 20 7d 0a 0a 2f 2a 20 54 68 69 6e 67 73 20 66  ; }../* Things f
0460: 6f 72 20 22 66 61 6e 63 79 66 6f 72 6d 61 74 22  or "fancyformat"
0470: 20 64 6f 63 75 6d 65 6e 74 73 20 73 74 61 72 74   documents start
0480: 20 68 65 72 65 2e 20 2a 2f 0a 2e 66 61 6e 63 79   here. */..fancy
0490: 20 69 6d 67 2b 70 20 7b 66 6f 6e 74 2d 73 74 79   img+p {font-sty
04a0: 6c 65 3a 69 74 61 6c 69 63 7d 0a 2e 66 61 6e 63  le:italic}..fanc
04b0: 79 20 2e 63 6f 64 65 62 6c 6f 63 6b 20 69 20 7b  y .codeblock i {
04c0: 20 63 6f 6c 6f 72 3a 20 64 61 72 6b 62 6c 75 65   color: darkblue
04d0: 3b 20 7d 0a 2e 66 61 6e 63 79 20 68 31 2c 2e 66  ; }..fancy h1,.f
04e0: 61 6e 63 79 20 68 32 2c 2e 66 61 6e 63 79 20 68  ancy h2,.fancy h
04f0: 33 2c 2e 66 61 6e 63 79 20 68 34 20 7b 66 6f 6e  3,.fancy h4 {fon
0500: 74 2d 77 65 69 67 68 74 3a 6e 6f 72 6d 61 6c 3b  t-weight:normal;
0510: 63 6f 6c 6f 72 3a 23 30 34 34 61 36 34 7d 0a 2e  color:#044a64}..
0520: 66 61 6e 63 79 20 68 32 20 7b 20 6d 61 72 67 69  fancy h2 { margi
0530: 6e 2d 6c 65 66 74 3a 20 31 30 70 78 20 7d 0a 2e  n-left: 10px }..
0540: 66 61 6e 63 79 20 68 33 20 7b 20 6d 61 72 67 69  fancy h3 { margi
0550: 6e 2d 6c 65 66 74 3a 20 32 30 70 78 20 7d 0a 2e  n-left: 20px }..
0560: 66 61 6e 63 79 20 68 34 20 7b 20 6d 61 72 67 69  fancy h4 { margi
0570: 6e 2d 6c 65 66 74 3a 20 33 30 70 78 20 7d 0a 2e  n-left: 30px }..
0580: 66 61 6e 63 79 20 74 68 20 7b 77 68 69 74 65 2d  fancy th {white-
0590: 73 70 61 63 65 3a 6e 6f 77 72 61 70 3b 74 65 78  space:nowrap;tex
05a0: 74 2d 61 6c 69 67 6e 3a 6c 65 66 74 3b 62 6f 72  t-align:left;bor
05b0: 64 65 72 2d 62 6f 74 74 6f 6d 3a 73 6f 6c 69 64  der-bottom:solid
05c0: 20 31 70 78 20 23 34 34 34 7d 0a 2e 66 61 6e 63   1px #444}..fanc
05d0: 79 20 74 68 2c 20 2e 66 61 6e 63 79 20 74 64 20  y th, .fancy td 
05e0: 7b 70 61 64 64 69 6e 67 3a 20 30 2e 32 65 6d 20  {padding: 0.2em 
05f0: 31 65 78 3b 20 76 65 72 74 69 63 61 6c 2d 61 6c  1ex; vertical-al
0600: 69 67 6e 3a 74 6f 70 7d 0a 2e 66 61 6e 63 79 20  ign:top}..fancy 
0610: 23 74 6f 63 20 61 20 20 20 20 20 20 20 20 7b 20  #toc a        { 
0620: 63 6f 6c 6f 72 3a 20 64 61 72 6b 62 6c 75 65 20  color: darkblue 
0630: 3b 20 74 65 78 74 2d 64 65 63 6f 72 61 74 69 6f  ; text-decoratio
0640: 6e 3a 20 6e 6f 6e 65 20 7d 0a 2e 66 61 6e 63 79  n: none }..fancy
0650: 20 2e 74 6f 64 6f 20 20 20 20 20 20 20 20 20 7b   .todo         {
0660: 20 63 6f 6c 6f 72 3a 20 23 41 41 33 33 33 33 20   color: #AA3333 
0670: 3b 20 66 6f 6e 74 2d 73 74 79 6c 65 20 3a 20 69  ; font-style : i
0680: 74 61 6c 69 63 20 7d 0a 2e 66 61 6e 63 79 20 2e  talic }..fancy .
0690: 74 6f 64 6f 3a 62 65 66 6f 72 65 20 20 7b 20 63  todo:before  { c
06a0: 6f 6e 74 65 6e 74 3a 20 27 54 4f 44 4f 3a 27 20  ontent: 'TODO:' 
06b0: 7d 0a 2e 66 61 6e 63 79 20 70 2e 74 6f 64 6f 20  }..fancy p.todo 
06c0: 20 20 20 20 20 20 20 7b 20 62 6f 72 64 65 72 3a         { border:
06d0: 20 73 6f 6c 69 64 20 23 41 41 33 33 33 33 20 31   solid #AA3333 1
06e0: 70 78 3b 20 70 61 64 64 69 6e 67 3a 20 31 65 78  px; padding: 1ex
06f0: 20 7d 0a 2e 66 61 6e 63 79 20 69 6d 67 20 7b 20   }..fancy img { 
0700: 64 69 73 70 6c 61 79 3a 62 6c 6f 63 6b 3b 20 7d  display:block; }
0710: 0a 2e 66 61 6e 63 79 20 3a 6c 69 6e 6b 3a 68 6f  ..fancy :link:ho
0720: 76 65 72 2c 20 2e 66 61 6e 63 79 20 3a 76 69 73  ver, .fancy :vis
0730: 69 74 65 64 3a 68 6f 76 65 72 20 7b 20 62 61 63  ited:hover { bac
0740: 6b 67 72 6f 75 6e 64 3a 20 77 68 65 61 74 20 7d  kground: wheat }
0750: 0a 2e 66 61 6e 63 79 20 70 2c 2e 66 61 6e 63 79  ..fancy p,.fancy
0760: 20 75 6c 2c 2e 66 61 6e 63 79 20 6f 6c 2c 2e 66   ul,.fancy ol,.f
0770: 61 6e 63 79 20 64 6c 20 7b 20 6d 61 72 67 69 6e  ancy dl { margin
0780: 3a 20 31 65 6d 20 35 65 78 20 7d 0a 2e 66 61 6e  : 1em 5ex }..fan
0790: 63 79 20 6c 69 20 70 20 7b 20 6d 61 72 67 69 6e  cy li p { margin
07a0: 3a 20 31 65 6d 20 30 20 7d 0a 2f 2a 20 45 6e 64  : 1em 0 }./* End
07b0: 20 6f 66 20 22 66 61 6e 63 79 66 6f 72 6d 61 74   of "fancyformat
07c0: 22 20 73 70 65 63 69 66 69 63 20 72 75 6c 65 73  " specific rules
07d0: 2e 20 2a 2f 0a 0a 2e 79 79 74 65 72 6d 20 7b 0a  . */...yyterm {.
07e0: 20 20 62 61 63 6b 67 72 6f 75 6e 64 3a 20 23 66    background: #f
07f0: 66 66 3b 0a 20 20 62 6f 72 64 65 72 3a 20 31 70  ff;.  border: 1p
0800: 78 20 73 6f 6c 69 64 20 23 30 30 30 3b 0a 20 20  x solid #000;.  
0810: 62 6f 72 64 65 72 2d 72 61 64 69 75 73 3a 20 31  border-radius: 1
0820: 31 70 78 3b 0a 20 20 70 61 64 64 69 6e 67 2d 6c  1px;.  padding-l
0830: 65 66 74 3a 20 34 70 78 3b 0a 20 20 70 61 64 64  eft: 4px;.  padd
0840: 69 6e 67 2d 72 69 67 68 74 3a 20 34 70 78 3b 0a  ing-right: 4px;.
0850: 7d 0a 3c 2f 73 74 79 6c 65 3e 0a 20 20 0a 3c 2f  }.</style>.  .</
0860: 68 65 61 64 3e 0a 3c 62 6f 64 79 3e 0a 3c 64 69  head>.<body>.<di
0870: 76 3e 3c 21 2d 2d 20 63 6f 6e 74 61 69 6e 65 72  v><!-- container
0880: 20 64 69 76 20 74 6f 20 73 61 74 69 73 66 79 20   div to satisfy 
0890: 76 61 6c 69 64 61 74 6f 72 20 2d 2d 3e 0a 0a 3c  validator -->..<
08a0: 61 20 68 72 65 66 3d 22 69 6e 64 65 78 2e 68 74  a href="index.ht
08b0: 6d 6c 22 3e 0a 3c 69 6d 67 20 63 6c 61 73 73 3d  ml">.<img class=
08c0: 22 6c 6f 67 6f 22 20 73 72 63 3d 22 69 6d 61 67  "logo" src="imag
08d0: 65 73 2f 73 71 6c 69 74 65 33 37 30 5f 62 61 6e  es/sqlite370_ban
08e0: 6e 65 72 2e 67 69 66 22 20 61 6c 74 3d 22 53 51  ner.gif" alt="SQ
08f0: 4c 69 74 65 20 4c 6f 67 6f 22 0a 20 62 6f 72 64  Lite Logo". bord
0900: 65 72 3d 22 30 22 3e 3c 2f 61 3e 0a 3c 64 69 76  er="0"></a>.<div
0910: 3e 3c 21 2d 2d 20 49 45 20 68 61 63 6b 20 74 6f  ><!-- IE hack to
0920: 20 70 72 65 76 65 6e 74 20 64 69 73 61 70 70 65   prevent disappe
0930: 61 72 69 6e 67 20 6c 6f 67 6f 2d 2d 3e 3c 2f 64  aring logo--></d
0940: 69 76 3e 0a 3c 64 69 76 20 63 6c 61 73 73 3d 22  iv>.<div class="
0950: 74 61 67 6c 69 6e 65 22 3e 53 6d 61 6c 6c 2e 20  tagline">Small. 
0960: 46 61 73 74 2e 20 52 65 6c 69 61 62 6c 65 2e 3c  Fast. Reliable.<
0970: 62 72 3e 43 68 6f 6f 73 65 20 61 6e 79 20 74 68  br>Choose any th
0980: 72 65 65 2e 3c 2f 64 69 76 3e 0a 0a 3c 74 61 62  ree.</div>..<tab
0990: 6c 65 20 77 69 64 74 68 3d 31 30 30 25 20 63 6c  le width=100% cl
09a0: 61 73 73 3d 22 6d 65 6e 75 62 61 72 22 3e 3c 74  ass="menubar"><t
09b0: 72 3e 0a 20 20 3c 74 64 20 77 69 64 74 68 3d 31  r>.  <td width=1
09c0: 30 30 25 3e 0a 20 20 3c 64 69 76 20 63 6c 61 73  00%>.  <div clas
09d0: 73 3d 22 74 6f 6f 6c 62 61 72 22 3e 0a 20 20 20  s="toolbar">.   
09e0: 20 3c 61 20 68 72 65 66 3d 22 61 62 6f 75 74 2e   <a href="about.
09f0: 68 74 6d 6c 22 3e 41 62 6f 75 74 3c 2f 61 3e 0a  html">About</a>.
0a00: 20 20 20 20 3c 61 20 68 72 65 66 3d 22 64 6f 63      <a href="doc
0a10: 73 2e 68 74 6d 6c 22 3e 44 6f 63 75 6d 65 6e 74  s.html">Document
0a20: 61 74 69 6f 6e 3c 2f 61 3e 0a 20 20 20 20 3c 61  ation</a>.    <a
0a30: 20 68 72 65 66 3d 22 64 6f 77 6e 6c 6f 61 64 2e   href="download.
0a40: 68 74 6d 6c 22 3e 44 6f 77 6e 6c 6f 61 64 3c 2f  html">Download</
0a50: 61 3e 0a 20 20 20 20 3c 61 20 68 72 65 66 3d 22  a>.    <a href="
0a60: 63 6f 70 79 72 69 67 68 74 2e 68 74 6d 6c 22 3e  copyright.html">
0a70: 4c 69 63 65 6e 73 65 3c 2f 61 3e 0a 20 20 20 20  License</a>.    
0a80: 3c 61 20 68 72 65 66 3d 22 73 75 70 70 6f 72 74  <a href="support
0a90: 2e 68 74 6d 6c 22 3e 53 75 70 70 6f 72 74 3c 2f  .html">Support</
0aa0: 61 3e 0a 20 20 20 20 3c 61 20 68 72 65 66 3d 22  a>.    <a href="
0ab0: 68 74 74 70 3a 2f 2f 77 77 77 2e 68 77 61 63 69  http://www.hwaci
0ac0: 2e 63 6f 6d 2f 73 77 2f 73 71 6c 69 74 65 2f 70  .com/sw/sqlite/p
0ad0: 72 6f 73 75 70 70 6f 72 74 2e 68 74 6d 6c 22 3e  rosupport.html">
0ae0: 50 75 72 63 68 61 73 65 3c 2f 61 3e 0a 20 20 3c  Purchase</a>.  <
0af0: 2f 64 69 76 3e 0a 3c 73 63 72 69 70 74 3e 0a 20  /div>.<script>. 
0b00: 20 67 4d 73 67 20 3d 20 22 53 65 61 72 63 68 20   gMsg = "Search 
0b10: 53 51 4c 69 74 65 20 44 6f 63 73 2e 2e 2e 22 0a  SQLite Docs...".
0b20: 20 20 66 75 6e 63 74 69 6f 6e 20 65 6e 74 65 72    function enter
0b30: 73 65 61 72 63 68 28 29 20 7b 0a 20 20 20 20 76  search() {.    v
0b40: 61 72 20 71 20 3d 20 64 6f 63 75 6d 65 6e 74 2e  ar q = document.
0b50: 67 65 74 45 6c 65 6d 65 6e 74 42 79 49 64 28 22  getElementById("
0b60: 71 22 29 3b 0a 20 20 20 20 69 66 28 20 71 2e 76  q");.    if( q.v
0b70: 61 6c 75 65 20 3d 3d 20 67 4d 73 67 20 29 20 7b  alue == gMsg ) {
0b80: 20 71 2e 76 61 6c 75 65 20 3d 20 22 22 20 7d 0a   q.value = "" }.
0b90: 20 20 20 20 71 2e 73 74 79 6c 65 2e 63 6f 6c 6f      q.style.colo
0ba0: 72 20 3d 20 22 62 6c 61 63 6b 22 0a 20 20 20 20  r = "black".    
0bb0: 71 2e 73 74 79 6c 65 2e 66 6f 6e 74 53 74 79 6c  q.style.fontStyl
0bc0: 65 20 3d 20 22 6e 6f 72 6d 61 6c 22 0a 20 20 7d  e = "normal".  }
0bd0: 0a 20 20 66 75 6e 63 74 69 6f 6e 20 6c 65 61 76  .  function leav
0be0: 65 73 65 61 72 63 68 28 29 20 7b 0a 20 20 20 20  esearch() {.    
0bf0: 76 61 72 20 71 20 3d 20 64 6f 63 75 6d 65 6e 74  var q = document
0c00: 2e 67 65 74 45 6c 65 6d 65 6e 74 42 79 49 64 28  .getElementById(
0c10: 22 71 22 29 3b 0a 20 20 20 20 69 66 28 20 71 2e  "q");.    if( q.
0c20: 76 61 6c 75 65 20 3d 3d 20 22 22 20 29 20 7b 20  value == "" ) { 
0c30: 0a 20 20 20 20 20 20 71 2e 76 61 6c 75 65 20 3d  .      q.value =
0c40: 20 67 4d 73 67 0a 20 20 20 20 20 20 71 2e 73 74   gMsg.      q.st
0c50: 79 6c 65 2e 63 6f 6c 6f 72 20 3d 20 22 23 30 34  yle.color = "#04
0c60: 34 61 36 34 22 0a 20 20 20 20 20 20 71 2e 73 74  4a64".      q.st
0c70: 79 6c 65 2e 66 6f 6e 74 53 74 79 6c 65 20 3d 20  yle.fontStyle = 
0c80: 22 69 74 61 6c 69 63 22 0a 20 20 20 20 7d 0a 20  "italic".    }. 
0c90: 20 7d 0a 20 20 66 75 6e 63 74 69 6f 6e 20 68 69   }.  function hi
0ca0: 64 65 6f 72 73 68 6f 77 28 62 74 6e 2c 6f 62 6a  deorshow(btn,obj
0cb0: 29 7b 0a 20 20 20 20 76 61 72 20 78 20 3d 20 64  ){.    var x = d
0cc0: 6f 63 75 6d 65 6e 74 2e 67 65 74 45 6c 65 6d 65  ocument.getEleme
0cd0: 6e 74 42 79 49 64 28 6f 62 6a 29 3b 0a 20 20 20  ntById(obj);.   
0ce0: 20 76 61 72 20 62 20 3d 20 64 6f 63 75 6d 65 6e   var b = documen
0cf0: 74 2e 67 65 74 45 6c 65 6d 65 6e 74 42 79 49 64  t.getElementById
0d00: 28 62 74 6e 29 3b 0a 20 20 20 20 69 66 28 20 78  (btn);.    if( x
0d10: 2e 73 74 79 6c 65 2e 64 69 73 70 6c 61 79 21 3d  .style.display!=
0d20: 27 6e 6f 6e 65 27 20 29 7b 0a 20 20 20 20 20 20  'none' ){.      
0d30: 78 2e 73 74 79 6c 65 2e 64 69 73 70 6c 61 79 20  x.style.display 
0d40: 3d 20 27 6e 6f 6e 65 27 3b 0a 20 20 20 20 20 20  = 'none';.      
0d50: 62 2e 69 6e 6e 65 72 48 54 4d 4c 3d 27 73 68 6f  b.innerHTML='sho
0d60: 77 27 3b 0a 20 20 20 20 7d 65 6c 73 65 7b 0a 20  w';.    }else{. 
0d70: 20 20 20 20 20 78 2e 73 74 79 6c 65 2e 64 69 73       x.style.dis
0d80: 70 6c 61 79 20 3d 20 27 27 3b 0a 20 20 20 20 20  play = '';.     
0d90: 20 62 2e 69 6e 6e 65 72 48 54 4d 4c 3d 27 68 69   b.innerHTML='hi
0da0: 64 65 27 3b 0a 20 20 20 20 7d 0a 20 20 20 20 72  de';.    }.    r
0db0: 65 74 75 72 6e 20 66 61 6c 73 65 3b 0a 20 20 7d  eturn false;.  }
0dc0: 0a 3c 2f 73 63 72 69 70 74 3e 0a 3c 74 64 3e 0a  .</script>.<td>.
0dd0: 20 20 20 20 3c 64 69 76 20 73 74 79 6c 65 3d 22      <div style="
0de0: 70 61 64 64 69 6e 67 3a 30 20 31 65 6d 20 30 70  padding:0 1em 0p
0df0: 78 20 30 3b 77 68 69 74 65 2d 73 70 61 63 65 3a  x 0;white-space:
0e00: 6e 6f 77 72 61 70 22 3e 0a 20 20 20 20 3c 66 6f  nowrap">.    <fo
0e10: 72 6d 20 6e 61 6d 65 3d 66 20 6d 65 74 68 6f 64  rm name=f method
0e20: 3d 22 47 45 54 22 20 61 63 74 69 6f 6e 3d 22 68  ="GET" action="h
0e30: 74 74 70 73 3a 2f 2f 77 77 77 2e 73 71 6c 69 74  ttps://www.sqlit
0e40: 65 2e 6f 72 67 2f 73 65 61 72 63 68 22 3e 0a 20  e.org/search">. 
0e50: 20 20 20 20 20 3c 69 6e 70 75 74 20 69 64 3d 71       <input id=q
0e60: 20 6e 61 6d 65 3d 71 20 74 79 70 65 3d 74 65 78   name=q type=tex
0e70: 74 0a 20 20 20 20 20 20 20 6f 6e 66 6f 63 75 73  t.       onfocus
0e80: 3d 22 65 6e 74 65 72 73 65 61 72 63 68 28 29 22  ="entersearch()"
0e90: 20 6f 6e 62 6c 75 72 3d 22 6c 65 61 76 65 73 65   onblur="leavese
0ea0: 61 72 63 68 28 29 22 20 73 74 79 6c 65 3d 22 77  arch()" style="w
0eb0: 69 64 74 68 3a 32 34 65 78 3b 70 61 64 64 69 6e  idth:24ex;paddin
0ec0: 67 3a 31 70 78 20 31 65 78 3b 20 62 6f 72 64 65  g:1px 1ex; borde
0ed0: 72 3a 73 6f 6c 69 64 20 77 68 69 74 65 20 31 70  r:solid white 1p
0ee0: 78 3b 20 66 6f 6e 74 2d 73 69 7a 65 3a 30 2e 39  x; font-size:0.9
0ef0: 65 6d 20 3b 20 66 6f 6e 74 2d 73 74 79 6c 65 3a  em ; font-style:
0f00: 69 74 61 6c 69 63 3b 63 6f 6c 6f 72 3a 23 30 34  italic;color:#04
0f10: 34 61 36 34 3b 22 20 76 61 6c 75 65 3d 22 53 65  4a64;" value="Se
0f20: 61 72 63 68 20 53 51 4c 69 74 65 20 44 6f 63 73  arch SQLite Docs
0f30: 2e 2e 2e 22 3e 0a 20 20 20 20 20 20 3c 69 6e 70  ...">.      <inp
0f40: 75 74 20 74 79 70 65 3d 73 75 62 6d 69 74 20 76  ut type=submit v
0f50: 61 6c 75 65 3d 22 47 6f 22 20 73 74 79 6c 65 3d  alue="Go" style=
0f60: 22 62 6f 72 64 65 72 3a 73 6f 6c 69 64 20 77 68  "border:solid wh
0f70: 69 74 65 20 31 70 78 3b 62 61 63 6b 67 72 6f 75  ite 1px;backgrou
0f80: 6e 64 2d 63 6f 6c 6f 72 3a 23 30 34 34 61 36 34  nd-color:#044a64
0f90: 3b 63 6f 6c 6f 72 3a 77 68 69 74 65 3b 66 6f 6e  ;color:white;fon
0fa0: 74 2d 73 69 7a 65 3a 30 2e 39 65 6d 3b 70 61 64  t-size:0.9em;pad
0fb0: 64 69 6e 67 3a 30 20 31 65 78 22 3e 0a 20 20 20  ding:0 1ex">.   
0fc0: 20 3c 2f 66 6f 72 6d 3e 0a 20 20 20 20 3c 2f 64   </form>.    </d
0fd0: 69 76 3e 0a 20 20 3c 2f 74 61 62 6c 65 3e 0a 0a  iv>.  </table>..
0fe0: 3c 64 69 76 20 63 6c 61 73 73 3d 73 74 61 72 74  <div class=start
0ff0: 73 65 61 72 63 68 3e 3c 2f 64 69 76 3e 0a 20 20  search></div>.  
1000: 0a 0a 0a 3c 68 31 20 61 6c 69 67 6e 3d 22 63 65  ...<h1 align="ce
1010: 6e 74 65 72 22 3e 54 68 65 20 56 69 72 74 75 61  nter">The Virtua
1020: 6c 20 54 61 62 6c 65 20 4d 65 63 68 61 6e 69 73  l Table Mechanis
1030: 6d 20 4f 66 20 53 51 4c 69 74 65 3c 2f 68 31 3e  m Of SQLite</h1>
1040: 0a 0a 0a 3c 68 32 3e 31 2e 30 20 49 6e 74 72 6f  ...<h2>1.0 Intro
1050: 64 75 63 74 69 6f 6e 3c 2f 68 32 3e 0a 0a 3c 70  duction</h2>..<p
1060: 3e 41 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  >A virtual table
1070: 20 69 73 20 61 6e 20 6f 62 6a 65 63 74 20 74 68   is an object th
1080: 61 74 20 69 73 20 72 65 67 69 73 74 65 72 65 64  at is registered
1090: 20 77 69 74 68 20 61 6e 20 6f 70 65 6e 20 53 51   with an open SQ
10a0: 4c 69 74 65 0a 3c 61 20 68 72 65 66 3d 22 63 33  Lite.<a href="c3
10b0: 72 65 66 2f 73 71 6c 69 74 65 33 2e 68 74 6d 6c  ref/sqlite3.html
10c0: 22 3e 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  ">database conne
10d0: 63 74 69 6f 6e 3c 2f 61 3e 2e 20 46 72 6f 6d 20  ction</a>. From 
10e0: 74 68 65 20 70 65 72 73 70 65 63 74 69 76 65 20  the perspective 
10f0: 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  of an SQL statem
1100: 65 6e 74 2c 0a 74 68 65 20 76 69 72 74 75 61 6c  ent,.the virtual
1110: 20 74 61 62 6c 65 20 6f 62 6a 65 63 74 20 6c 6f   table object lo
1120: 6f 6b 73 20 6c 69 6b 65 20 61 6e 79 20 6f 74 68  oks like any oth
1130: 65 72 20 74 61 62 6c 65 20 6f 72 20 76 69 65 77  er table or view
1140: 2e 20 0a 42 75 74 20 62 65 68 69 6e 64 20 74 68  . .But behind th
1150: 65 20 73 63 65 6e 65 73 2c 20 71 75 65 72 69 65  e scenes, querie
1160: 73 20 61 6e 64 20 75 70 64 61 74 65 73 20 6f 6e  s and updates on
1170: 20 61 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65   a virtual table
1180: 0a 69 6e 76 6f 6b 65 20 63 61 6c 6c 62 61 63 6b  .invoke callback
1190: 20 6d 65 74 68 6f 64 73 20 6f 66 20 74 68 65 20   methods of the 
11a0: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6f 62  virtual table ob
11b0: 6a 65 63 74 20 69 6e 73 74 65 61 64 20 6f 66 0a  ject instead of.
11c0: 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
11d0: 69 6e 67 20 74 6f 20 74 68 65 20 64 61 74 61 62  ing to the datab
11e0: 61 73 65 20 66 69 6c 65 2e 0a 0a 3c 70 3e 54 68  ase file...<p>Th
11f0: 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  e virtual table 
1200: 6d 65 63 68 61 6e 69 73 6d 20 61 6c 6c 6f 77 73  mechanism allows
1210: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
1220: 74 6f 20 70 75 62 6c 69 73 68 0a 69 6e 74 65 72  to publish.inter
1230: 66 61 63 65 73 20 74 68 61 74 20 61 72 65 20 61  faces that are a
1240: 63 63 65 73 73 69 62 6c 65 20 66 72 6f 6d 20 53  ccessible from S
1250: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73  QL statements as
1260: 20 69 66 20 74 68 65 79 20 77 65 72 65 0a 74 61   if they were.ta
1270: 62 6c 65 73 2e 20 53 51 4c 20 73 74 61 74 65 6d  bles. SQL statem
1280: 65 6e 74 73 20 63 61 6e 20 64 6f 20 61 6c 6d 6f  ents can do almo
1290: 73 74 20 61 6e 79 74 68 69 6e 67 20 74 6f 20 61  st anything to a
12a0: 0a 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 74  .virtual table t
12b0: 68 61 74 20 74 68 65 79 20 63 61 6e 20 64 6f 20  hat they can do 
12c0: 74 6f 20 61 20 72 65 61 6c 20 74 61 62 6c 65 2c  to a real table,
12d0: 20 77 69 74 68 20 74 68 65 20 66 6f 6c 6c 6f 77   with the follow
12e0: 69 6e 67 0a 65 78 63 65 70 74 69 6f 6e 73 3a 0a  ing.exceptions:.
12f0: 0a 3c 70 3e 0a 3c 75 6c 3e 0a 3c 6c 69 3e 20 4f  .<p>.<ul>.<li> O
1300: 6e 65 20 63 61 6e 6e 6f 74 20 63 72 65 61 74 65  ne cannot create
1310: 20 61 20 74 72 69 67 67 65 72 20 6f 6e 20 61 20   a trigger on a 
1320: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 0a 3c  virtual table..<
1330: 6c 69 3e 20 4f 6e 65 20 63 61 6e 6e 6f 74 20 63  li> One cannot c
1340: 72 65 61 74 65 20 61 64 64 69 74 69 6f 6e 61 6c  reate additional
1350: 20 69 6e 64 69 63 65 73 20 6f 6e 20 61 20 76 69   indices on a vi
1360: 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 0a 20 20  rtual table. .  
1370: 20 20 20 28 56 69 72 74 75 61 6c 20 74 61 62 6c     (Virtual tabl
1380: 65 73 20 63 61 6e 20 68 61 76 65 20 69 6e 64 69  es can have indi
1390: 63 65 73 20 62 75 74 20 74 68 61 74 20 6d 75 73  ces but that mus
13a0: 74 20 62 65 20 62 75 69 6c 74 20 69 6e 74 6f 0a  t be built into.
13b0: 20 20 20 20 20 74 68 65 20 76 69 72 74 75 61 6c       the virtual
13c0: 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74   table implement
13d0: 61 74 69 6f 6e 2e 20 20 49 6e 64 69 63 65 73 20  ation.  Indices 
13e0: 63 61 6e 6e 6f 74 20 62 65 20 61 64 64 65 64 0a  cannot be added.
13f0: 20 20 20 20 20 73 65 70 61 72 61 74 65 6c 79 20       separately 
1400: 75 73 69 6e 67 20 3c 61 20 68 72 65 66 3d 22 6c  using <a href="l
1410: 61 6e 67 5f 63 72 65 61 74 65 69 6e 64 65 78 2e  ang_createindex.
1420: 68 74 6d 6c 22 3e 43 52 45 41 54 45 20 49 4e 44  html">CREATE IND
1430: 45 58 3c 2f 61 3e 20 73 74 61 74 65 6d 65 6e 74  EX</a> statement
1440: 73 2e 29 0a 3c 6c 69 3e 20 4f 6e 65 20 63 61 6e  s.).<li> One can
1450: 6e 6f 74 20 72 75 6e 20 3c 61 20 68 72 65 66 3d  not run <a href=
1460: 22 6c 61 6e 67 5f 61 6c 74 65 72 74 61 62 6c 65  "lang_altertable
1470: 2e 68 74 6d 6c 22 3e 41 4c 54 45 52 20 54 41 42  .html">ALTER TAB
1480: 4c 45 20 2e 2e 2e 20 41 44 44 20 43 4f 4c 55 4d  LE ... ADD COLUM
1490: 4e 3c 2f 61 3e 0a 20 20 20 20 20 63 6f 6d 6d 61  N</a>.     comma
14a0: 6e 64 73 20 61 67 61 69 6e 73 74 20 61 20 76 69  nds against a vi
14b0: 72 74 75 61 6c 20 74 61 62 6c 65 2e 0a 3c 2f 75  rtual table..</u
14c0: 6c 3e 0a 0a 3c 70 3e 49 6e 64 69 76 69 64 75 61  l>..<p>Individua
14d0: 6c 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  l virtual table 
14e0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
14f0: 6d 69 67 68 74 20 69 6d 70 6f 73 65 20 61 64 64  might impose add
1500: 69 74 69 6f 6e 61 6c 0a 63 6f 6e 73 74 72 61 69  itional.constrai
1510: 6e 74 73 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65  nts. For example
1520: 2c 20 73 6f 6d 65 20 76 69 72 74 75 61 6c 20 69  , some virtual i
1530: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
1540: 69 67 68 74 20 70 72 6f 76 69 64 65 0a 72 65 61  ight provide.rea
1550: 64 2d 6f 6e 6c 79 20 74 61 62 6c 65 73 2e 20 4f  d-only tables. O
1560: 72 20 73 6f 6d 65 20 76 69 72 74 75 61 6c 20 74  r some virtual t
1570: 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
1580: 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 6c 6f 77  ions might allow
1590: 0a 3c 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f 69  .<a href="lang_i
15a0: 6e 73 65 72 74 2e 68 74 6d 6c 22 3e 49 4e 53 45  nsert.html">INSE
15b0: 52 54 3c 2f 61 3e 20 6f 72 20 3c 61 20 68 72 65  RT</a> or <a hre
15c0: 66 3d 22 6c 61 6e 67 5f 64 65 6c 65 74 65 2e 68  f="lang_delete.h
15d0: 74 6d 6c 22 3e 44 45 4c 45 54 45 3c 2f 61 3e 20  tml">DELETE</a> 
15e0: 62 75 74 20 6e 6f 74 20 3c 61 20 68 72 65 66 3d  but not <a href=
15f0: 22 6c 61 6e 67 5f 75 70 64 61 74 65 2e 68 74 6d  "lang_update.htm
1600: 6c 22 3e 55 50 44 41 54 45 3c 2f 61 3e 2e 20 20  l">UPDATE</a>.  
1610: 4f 72 20 73 6f 6d 65 20 76 69 72 74 75 61 6c 20  Or some virtual 
1620: 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
1630: 74 69 6f 6e 73 0a 6d 69 67 68 74 20 6c 69 6d 69  tions.might limi
1640: 74 20 74 68 65 20 6b 69 6e 64 73 20 6f 66 20 55  t the kinds of U
1650: 50 44 41 54 45 73 20 74 68 61 74 20 63 61 6e 20  PDATEs that can 
1660: 62 65 20 6d 61 64 65 2e 0a 0a 3c 70 3e 41 20 76  be made...<p>A v
1670: 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 69 67  irtual table mig
1680: 68 74 20 72 65 70 72 65 73 65 6e 74 20 61 6e 20  ht represent an 
1690: 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 20 73  in-memory data s
16a0: 74 72 75 63 74 75 72 65 73 2e 20 0a 4f 72 20 69  tructures. .Or i
16b0: 74 20 6d 69 67 68 74 20 72 65 70 72 65 73 65 6e  t might represen
16c0: 74 20 61 20 76 69 65 77 20 6f 66 20 64 61 74 61  t a view of data
16d0: 20 6f 6e 20 64 69 73 6b 20 74 68 61 74 20 69 73   on disk that is
16e0: 20 6e 6f 74 20 69 6e 20 74 68 65 0a 53 51 4c 69   not in the.SQLi
16f0: 74 65 20 66 6f 72 6d 61 74 2e 20 4f 72 20 74 68  te format. Or th
1700: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69  e application mi
1710: 67 68 74 20 63 6f 6d 70 75 74 65 20 74 68 65 20  ght compute the 
1720: 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 0a  content of the .
1730: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6f 6e  virtual table on
1740: 20 64 65 6d 61 6e 64 2e 0a 0a 3c 70 3e 48 65 72   demand...<p>Her
1750: 65 20 61 72 65 20 73 6f 6d 65 20 65 78 69 73 74  e are some exist
1760: 69 6e 67 20 61 6e 64 20 70 6f 73 74 75 6c 61 74  ing and postulat
1770: 65 64 20 75 73 65 73 20 66 6f 72 20 76 69 72 74  ed uses for virt
1780: 75 61 6c 20 74 61 62 6c 65 73 3a 0a 0a 3c 75 6c  ual tables:..<ul
1790: 3e 0a 3c 6c 69 3e 20 41 20 3c 61 20 68 72 65 66  >.<li> A <a href
17a0: 3d 22 66 74 73 33 2e 68 74 6d 6c 22 3e 66 75 6c  ="fts3.html">ful
17b0: 6c 2d 74 65 78 74 20 73 65 61 72 63 68 3c 2f 61  l-text search</a
17c0: 3e 20 69 6e 74 65 72 66 61 63 65 0a 3c 6c 69 3e  > interface.<li>
17d0: 20 53 70 61 74 69 61 6c 20 69 6e 64 69 63 65 73   Spatial indices
17e0: 20 75 73 69 6e 67 20 3c 61 20 68 72 65 66 3d 22   using <a href="
17f0: 72 74 72 65 65 2e 68 74 6d 6c 22 3e 52 2d 54 72  rtree.html">R-Tr
1800: 65 65 73 3c 2f 61 3e 0a 3c 6c 69 3e 20 49 6e 74  ees</a>.<li> Int
1810: 72 6f 73 70 65 63 74 20 74 68 65 20 64 69 73 6b  rospect the disk
1820: 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61 6e 20 53   content of an S
1830: 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
1840: 69 6c 65 0a 20 20 20 20 20 28 74 68 65 20 3c 61  ile.     (the <a
1850: 20 68 72 65 66 3d 22 64 62 73 74 61 74 2e 68 74   href="dbstat.ht
1860: 6d 6c 22 3e 64 62 73 74 61 74 20 76 69 72 74 75  ml">dbstat virtu
1870: 61 6c 20 74 61 62 6c 65 3c 2f 61 3e 29 0a 3c 6c  al table</a>).<l
1880: 69 3e 20 52 65 61 64 20 61 6e 64 2f 6f 72 20 77  i> Read and/or w
1890: 72 69 74 65 20 74 68 65 20 63 6f 6e 74 65 6e 74  rite the content
18a0: 20 6f 66 20 61 20 63 6f 6d 6d 61 2d 73 65 70 61   of a comma-sepa
18b0: 72 61 74 65 64 20 76 61 6c 75 65 20 28 43 53 56  rated value (CSV
18c0: 29 0a 20 20 20 20 20 66 69 6c 65 0a 3c 6c 69 3e  ).     file.<li>
18d0: 20 41 63 63 65 73 73 20 74 68 65 20 66 69 6c 65   Access the file
18e0: 73 79 73 74 65 6d 20 6f 66 20 74 68 65 20 68 6f  system of the ho
18f0: 73 74 20 63 6f 6d 70 75 74 65 72 20 61 73 20 69  st computer as i
1900: 66 20 69 74 20 77 65 72 65 20 61 20 64 61 74 61  f it were a data
1910: 62 61 73 65 20 74 61 62 6c 65 0a 3c 6c 69 3e 20  base table.<li> 
1920: 45 6e 61 62 6c 69 6e 67 20 53 51 4c 20 6d 61 6e  Enabling SQL man
1930: 69 70 75 6c 61 74 69 6f 6e 20 6f 66 20 64 61 74  ipulation of dat
1940: 61 20 69 6e 20 73 74 61 74 69 73 74 69 63 73 20  a in statistics 
1950: 70 61 63 6b 61 67 65 73 20 6c 69 6b 65 20 52 0a  packages like R.
1960: 3c 2f 75 6c 3e 0a 0a 3c 68 33 3e 31 2e 31 20 55  </ul>..<h3>1.1 U
1970: 73 61 67 65 3c 2f 68 33 3e 0a 0a 3c 70 3e 41 20  sage</h3>..<p>A 
1980: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 73  virtual table is
1990: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 61   created using a
19a0: 20 3c 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f 63   <a href="lang_c
19b0: 72 65 61 74 65 76 74 61 62 2e 68 74 6d 6c 22 3e  reatevtab.html">
19c0: 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20 54  CREATE VIRTUAL T
19d0: 41 42 4c 45 3c 2f 61 3e 20 73 74 61 74 65 6d 65  ABLE</a> stateme
19e0: 6e 74 2e 0a 0a 3c 70 3e 3c 62 3e 3c 61 20 68 72  nt...<p><b><a hr
19f0: 65 66 3d 22 73 79 6e 74 61 78 2f 63 72 65 61 74  ef="syntax/creat
1a00: 65 2d 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 2d  e-virtual-table-
1a10: 73 74 6d 74 2e 68 74 6d 6c 22 3e 63 72 65 61 74  stmt.html">creat
1a20: 65 2d 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 2d  e-virtual-table-
1a30: 73 74 6d 74 3a 3c 2f 61 3e 3c 2f 62 3e 0a 3c 62  stmt:</a></b>.<b
1a40: 75 74 74 6f 6e 20 69 64 3d 27 78 31 34 37 35 27  utton id='x1475'
1a50: 20 6f 6e 63 6c 69 63 6b 3d 27 68 69 64 65 6f 72   onclick='hideor
1a60: 73 68 6f 77 28 22 78 31 34 37 35 22 2c 22 78 31  show("x1475","x1
1a70: 34 37 36 22 29 27 3e 68 69 64 65 3c 2f 62 75 74  476")'>hide</but
1a80: 74 6f 6e 3e 3c 2f 70 3e 0a 20 3c 62 6c 6f 63 6b  ton></p>. <block
1a90: 71 75 6f 74 65 20 69 64 3d 27 78 31 34 37 36 27  quote id='x1476'
1aa0: 3e 0a 20 3c 69 6d 67 20 61 6c 74 3d 22 73 79 6e  >. <img alt="syn
1ab0: 74 61 78 20 64 69 61 67 72 61 6d 20 63 72 65 61  tax diagram crea
1ac0: 74 65 2d 76 69 72 74 75 61 6c 2d 74 61 62 6c 65  te-virtual-table
1ad0: 2d 73 74 6d 74 22 20 73 72 63 3d 22 69 6d 61 67  -stmt" src="imag
1ae0: 65 73 2f 73 79 6e 74 61 78 2f 63 72 65 61 74 65  es/syntax/create
1af0: 2d 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 2d 73  -virtual-table-s
1b00: 74 6d 74 2e 67 69 66 22 20 2f 3e 0a 3c 2f 62 6c  tmt.gif" />.</bl
1b10: 6f 63 6b 71 75 6f 74 65 3e 0a 0a 0a 3c 70 3e 54  ockquote>...<p>T
1b20: 68 65 20 43 52 45 41 54 45 20 56 49 52 54 55 41  he CREATE VIRTUA
1b30: 4c 20 54 41 42 4c 45 20 73 74 61 74 65 6d 65 6e  L TABLE statemen
1b40: 74 20 63 72 65 61 74 65 73 20 61 20 6e 65 77 20  t creates a new 
1b50: 74 61 62 6c 65 0a 63 61 6c 6c 65 64 20 3c 73 70  table.called <sp
1b60: 61 6e 20 63 6c 61 73 73 3d 27 79 79 74 65 72 6d  an class='yyterm
1b70: 27 3e 74 61 62 6c 65 2d 6e 61 6d 65 3c 2f 73 70  '>table-name</sp
1b80: 61 6e 3e 20 64 65 72 69 76 65 64 20 66 72 6f 6d  an> derived from
1b90: 20 74 68 65 20 63 6c 61 73 73 0a 63 6c 61 73 73   the class.class
1ba0: 20 3c 73 70 61 6e 20 63 6c 61 73 73 3d 27 79 79   <span class='yy
1bb0: 74 65 72 6d 27 3e 6d 6f 64 75 6c 65 2d 6e 61 6d  term'>module-nam
1bc0: 65 3c 2f 73 70 61 6e 3e 2e 20 20 54 68 65 20 3c  e</span>.  The <
1bd0: 73 70 61 6e 20 63 6c 61 73 73 3d 27 79 79 74 65  span class='yyte
1be0: 72 6d 27 3e 6d 6f 64 75 6c 65 2d 6e 61 6d 65 3c  rm'>module-name<
1bf0: 2f 73 70 61 6e 3e 0a 69 73 20 74 68 65 20 6e 61  /span>.is the na
1c00: 6d 65 20 74 68 61 74 20 69 73 20 72 65 67 69 73  me that is regis
1c10: 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 76 69  tered for the vi
1c20: 72 74 75 61 6c 20 74 61 62 6c 65 20 62 79 0a 74  rtual table by.t
1c30: 68 65 20 3c 61 20 68 72 65 66 3d 22 63 33 72 65  he <a href="c3re
1c40: 66 2f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 2e  f/create_module.
1c50: 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 63 72  html">sqlite3_cr
1c60: 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 3c 2f 61  eate_module()</a
1c70: 3e 20 69 6e 74 65 72 66 61 63 65 2e 0a 0a 3c 62  > interface...<b
1c80: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1c90: 20 20 20 43 52 45 41 54 45 20 56 49 52 54 55 41     CREATE VIRTUA
1ca0: 4c 20 54 41 42 4c 45 20 74 61 62 6c 65 6e 61 6d  L TABLE tablenam
1cb0: 65 20 55 53 49 4e 47 20 6d 6f 64 75 6c 65 6e 61  e USING modulena
1cc0: 6d 65 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  me;.</pre></bloc
1cd0: 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 4f 6e 65 20  kquote>..<p>One 
1ce0: 63 61 6e 20 61 6c 73 6f 20 70 72 6f 76 69 64 65  can also provide
1cf0: 20 63 6f 6d 6d 61 2d 73 65 70 61 72 61 74 65 64   comma-separated
1d00: 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
1d10: 65 20 6d 6f 64 75 6c 65 20 66 6f 6c 6c 6f 77 69  e module followi
1d20: 6e 67 20 0a 74 68 65 20 6d 6f 64 75 6c 65 20 6e  ng .the module n
1d30: 61 6d 65 3a 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74  ame:..<blockquot
1d40: 65 3e 3c 70 72 65 3e 0a 20 20 20 43 52 45 41 54  e><pre>.   CREAT
1d50: 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20  E VIRTUAL TABLE 
1d60: 74 61 62 6c 65 6e 61 6d 65 20 55 53 49 4e 47 20  tablename USING 
1d70: 6d 6f 64 75 6c 65 6e 61 6d 65 28 61 72 67 31 2c  modulename(arg1,
1d80: 20 61 72 67 32 2c 20 2e 2e 2e 29 3b 0a 3c 2f 70   arg2, ...);.</p
1d90: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1da0: 0a 0a 3c 70 3e 54 68 65 20 66 6f 72 6d 61 74 20  ..<p>The format 
1db0: 6f 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 73  of the arguments
1dc0: 20 74 6f 20 74 68 65 20 6d 6f 64 75 6c 65 20 69   to the module i
1dd0: 73 20 76 65 72 79 20 67 65 6e 65 72 61 6c 2e 20  s very general. 
1de0: 45 61 63 68 20 0a 3c 73 70 61 6e 20 63 6c 61 73  Each .<span clas
1df0: 73 3d 27 79 79 74 65 72 6d 27 3e 6d 6f 64 75 6c  s='yyterm'>modul
1e00: 65 2d 61 72 67 75 6d 65 6e 74 3c 2f 73 70 61 6e  e-argument</span
1e10: 3e 0a 6d 61 79 20 63 6f 6e 74 61 69 6e 20 6b 65  >.may contain ke
1e20: 79 77 6f 72 64 73 2c 20 73 74 72 69 6e 67 20 6c  ywords, string l
1e30: 69 74 65 72 61 6c 73 2c 20 69 64 65 6e 74 69 66  iterals, identif
1e40: 69 65 72 73 2c 20 6e 75 6d 62 65 72 73 2c 20 61  iers, numbers, a
1e50: 6e 64 20 0a 70 75 6e 63 74 75 61 74 69 6f 6e 2e  nd .punctuation.
1e60: 20 45 61 63 68 20 3c 73 70 61 6e 20 63 6c 61 73   Each <span clas
1e70: 73 3d 27 79 79 74 65 72 6d 27 3e 6d 6f 64 75 6c  s='yyterm'>modul
1e80: 65 2d 61 72 67 75 6d 65 6e 74 3c 2f 73 70 61 6e  e-argument</span
1e90: 3e 20 69 73 20 70 61 73 73 65 64 20 61 73 20 0a  > is passed as .
1ea0: 77 72 69 74 74 65 6e 20 28 61 73 20 74 65 78 74  written (as text
1eb0: 29 20 69 6e 74 6f 20 74 68 65 0a 3c 61 20 68 72  ) into the.<a hr
1ec0: 65 66 3d 22 76 74 61 62 2e 68 74 6d 6c 23 78 63  ef="vtab.html#xc
1ed0: 72 65 61 74 65 22 3e 63 6f 6e 73 74 72 75 63 74  reate">construct
1ee0: 6f 72 20 6d 65 74 68 6f 64 3c 2f 61 3e 20 6f 66  or method</a> of
1ef0: 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
1f00: 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
1f10: 6e 20 0a 77 68 65 6e 20 74 68 65 20 76 69 72 74  n .when the virt
1f20: 75 61 6c 20 0a 74 61 62 6c 65 20 69 73 20 63 72  ual .table is cr
1f30: 65 61 74 65 64 20 61 6e 64 20 74 68 61 74 20 63  eated and that c
1f40: 6f 6e 73 74 72 75 63 74 6f 72 20 69 73 20 72 65  onstructor is re
1f50: 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 70 61  sponsible for pa
1f60: 72 73 69 6e 67 20 61 6e 64 20 0a 69 6e 74 65 72  rsing and .inter
1f70: 70 72 65 74 69 6e 67 20 74 68 65 20 61 72 67 75  preting the argu
1f80: 6d 65 6e 74 73 2e 20 54 68 65 20 61 72 67 75 6d  ments. The argum
1f90: 65 6e 74 20 73 79 6e 74 61 78 20 69 73 20 73 75  ent syntax is su
1fa0: 66 66 69 63 69 65 6e 74 6c 79 20 67 65 6e 65 72  fficiently gener
1fb0: 61 6c 20 0a 74 68 61 74 20 61 20 76 69 72 74 75  al .that a virtu
1fc0: 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  al table impleme
1fd0: 6e 74 61 74 69 6f 6e 20 63 61 6e 2c 20 69 66 20  ntation can, if 
1fe0: 69 74 20 77 61 6e 74 73 20 74 6f 2c 20 69 6e 74  it wants to, int
1ff0: 65 72 70 72 65 74 20 69 74 73 0a 61 72 67 75 6d  erpret its.argum
2000: 65 6e 74 73 20 61 73 20 3c 61 20 68 72 65 66 3d  ents as <a href=
2010: 22 6c 61 6e 67 5f 63 72 65 61 74 65 74 61 62 6c  "lang_createtabl
2020: 65 2e 68 74 6d 6c 23 74 61 62 6c 65 63 6f 6c 64  e.html#tablecold
2030: 65 66 22 3e 63 6f 6c 75 6d 6e 20 64 65 66 69 6e  ef">column defin
2040: 69 74 69 6f 6e 73 3c 2f 61 3e 20 69 6e 20 61 6e  itions</a> in an
2050: 20 6f 72 64 69 6e 61 72 79 20 3c 61 20 68 72 65   ordinary <a hre
2060: 66 3d 22 6c 61 6e 67 5f 63 72 65 61 74 65 74 61  f="lang_createta
2070: 62 6c 65 2e 68 74 6d 6c 22 3e 43 52 45 41 54 45  ble.html">CREATE
2080: 20 54 41 42 4c 45 3c 2f 61 3e 20 73 74 61 74 65   TABLE</a> state
2090: 6d 65 6e 74 2e 20 0a 54 68 65 20 69 6d 70 6c 65  ment. .The imple
20a0: 6d 65 6e 74 61 74 69 6f 6e 20 63 6f 75 6c 64 20  mentation could 
20b0: 61 6c 73 6f 20 69 6d 70 6f 73 65 20 73 6f 6d 65  also impose some
20c0: 20 6f 74 68 65 72 20 69 6e 74 65 72 70 72 65 74   other interpret
20d0: 61 74 69 6f 6e 20 6f 6e 20 74 68 65 20 0a 61 72  ation on the .ar
20e0: 67 75 6d 65 6e 74 73 2e 0a 0a 3c 70 3e 4f 6e 63  guments...<p>Onc
20f0: 65 20 61 20 76 69 72 74 75 61 6c 20 74 61 62 6c  e a virtual tabl
2100: 65 20 68 61 73 20 62 65 65 6e 20 63 72 65 61 74  e has been creat
2110: 65 64 2c 20 69 74 20 63 61 6e 20 62 65 20 75 73  ed, it can be us
2120: 65 64 20 6c 69 6b 65 20 61 6e 79 20 6f 74 68 65  ed like any othe
2130: 72 20 0a 74 61 62 6c 65 20 77 69 74 68 20 74 68  r .table with th
2140: 65 20 65 78 63 65 70 74 69 6f 6e 73 20 6e 6f 74  e exceptions not
2150: 65 64 20 61 62 6f 76 65 20 61 6e 64 20 69 6d 70  ed above and imp
2160: 6f 73 65 64 20 62 79 20 73 70 65 63 69 66 69 63  osed by specific
2170: 20 76 69 72 74 75 61 6c 0a 74 61 62 6c 65 20 69   virtual.table i
2180: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 20  mplementations. 
2190: 41 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  A virtual table 
21a0: 69 73 20 64 65 73 74 72 6f 79 65 64 20 75 73 69  is destroyed usi
21b0: 6e 67 20 74 68 65 20 6f 72 64 69 6e 61 72 79 0a  ng the ordinary.
21c0: 3c 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f 64 72  <a href="lang_dr
21d0: 6f 70 74 61 62 6c 65 2e 68 74 6d 6c 22 3e 44 52  optable.html">DR
21e0: 4f 50 20 54 41 42 4c 45 3c 2f 61 3e 20 73 79 6e  OP TABLE</a> syn
21f0: 74 61 78 2e 0a 0a 3c 68 34 3e 31 2e 31 2e 31 20  tax...<h4>1.1.1 
2200: 54 65 6d 70 6f 72 61 72 79 20 76 69 72 74 75 61  Temporary virtua
2210: 6c 20 74 61 62 6c 65 73 3c 2f 68 34 3e 0a 0a 3c  l tables</h4>..<
2220: 70 3e 54 68 65 72 65 20 69 73 20 6e 6f 20 22 43  p>There is no "C
2230: 52 45 41 54 45 20 54 45 4d 50 20 56 49 52 54 55  REATE TEMP VIRTU
2240: 41 4c 20 54 41 42 4c 45 22 20 73 74 61 74 65 6d  AL TABLE" statem
2250: 65 6e 74 2e 20 20 54 6f 20 63 72 65 61 74 65 20  ent.  To create 
2260: 61 0a 74 65 6d 70 6f 72 61 72 79 20 76 69 72 74  a.temporary virt
2270: 75 61 6c 20 74 61 62 6c 65 2c 20 61 64 64 20 74  ual table, add t
2280: 68 65 20 22 74 65 6d 70 22 20 73 63 68 65 6d 61  he "temp" schema
2290: 0a 62 65 66 6f 72 65 20 74 68 65 20 76 69 72 74  .before the virt
22a0: 75 61 6c 20 74 61 62 6c 65 20 6e 61 6d 65 2e 0a  ual table name..
22b0: 0a 3c 62 6c 6f 63 6b 63 75 71 6f 74 65 3e 3c 70  .<blockcuqote><p
22c0: 72 65 3e 0a 20 20 20 43 52 45 41 54 45 20 56 49  re>.   CREATE VI
22d0: 52 54 55 41 4c 20 54 41 42 4c 45 20 3c 62 3e 74  RTUAL TABLE <b>t
22e0: 65 6d 70 2e 3c 2f 62 3e 74 61 62 6c 65 6e 61 6d  emp.</b>tablenam
22f0: 65 20 55 53 49 4e 47 20 6d 6f 64 75 6c 65 28 61  e USING module(a
2300: 72 67 31 2c 20 2e 2e 2e 29 3b 0a 3c 2f 70 72 65  rg1, ...);.</pre
2310: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a  ></blockquote>..
2320: 3c 61 20 6e 61 6d 65 3d 22 65 70 6f 76 74 61 62  <a name="epovtab
2330: 22 3e 3c 2f 61 3e 0a 0a 3c 68 34 3e 31 2e 31 2e  "></a>..<h4>1.1.
2340: 32 20 45 70 6f 6e 79 6d 6f 75 73 20 76 69 72 74  2 Eponymous virt
2350: 75 61 6c 20 74 61 62 6c 65 73 3c 2f 68 34 3e 0a  ual tables</h4>.
2360: 0a 3c 70 3e 53 6f 6d 65 20 76 69 72 74 75 61 6c  .<p>Some virtual
2370: 20 74 61 62 6c 65 73 20 65 78 69 73 74 20 61 75   tables exist au
2380: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74  tomatically in t
2390: 68 65 20 22 6d 61 69 6e 22 20 73 63 68 65 6d 61  he "main" schema
23a0: 20 6f 66 0a 65 76 65 72 79 20 64 61 74 61 62 61   of.every databa
23b0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 6e  se connection in
23c0: 20 77 68 69 63 68 20 74 68 65 69 72 0a 6d 6f 64   which their.mod
23d0: 75 6c 65 20 69 73 20 72 65 67 69 73 74 65 72 65  ule is registere
23e0: 64 2c 20 65 76 65 6e 20 77 69 74 68 6f 75 74 20  d, even without 
23f0: 61 20 3c 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f  a <a href="lang_
2400: 63 72 65 61 74 65 76 74 61 62 2e 68 74 6d 6c 22  createvtab.html"
2410: 3e 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20  >CREATE VIRTUAL 
2420: 54 41 42 4c 45 3c 2f 61 3e 20 73 74 61 74 65 6d  TABLE</a> statem
2430: 65 6e 74 2e 0a 53 75 63 68 20 76 69 72 74 75 61  ent..Such virtua
2440: 6c 20 74 61 62 6c 65 73 20 61 72 65 20 63 61 6c  l tables are cal
2450: 6c 65 64 20 22 65 70 6f 6e 79 6d 6f 75 73 20 76  led "eponymous v
2460: 69 72 74 75 61 6c 20 74 61 62 6c 65 73 22 2e 0a  irtual tables"..
2470: 54 6f 20 75 73 65 20 61 6e 20 65 70 6f 6e 79 6d  To use an eponym
2480: 6f 75 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c  ous virtual tabl
2490: 65 2c 20 73 69 6d 70 6c 79 20 75 73 65 20 74 68  e, simply use th
24a0: 65 20 0a 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 61  e .module name a
24b0: 73 20 69 66 20 69 74 20 77 65 72 65 20 61 20 74  s if it were a t
24c0: 61 62 6c 65 2e 0a 45 70 6f 6e 79 6d 6f 75 73 20  able..Eponymous 
24d0: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 65  virtual tables e
24e0: 78 69 73 74 20 69 6e 20 74 68 65 20 22 6d 61 69  xist in the "mai
24f0: 6e 22 20 73 63 68 65 6d 61 20 6f 6e 6c 79 2c 20  n" schema only, 
2500: 73 6f 20 74 68 65 79 20 77 69 6c 6c 0a 6e 6f 74  so they will.not
2510: 20 77 6f 72 6b 20 69 66 20 70 72 65 66 69 78 65   work if prefixe
2520: 64 20 77 69 74 68 20 61 20 64 69 66 66 65 72 65  d with a differe
2530: 6e 74 20 73 63 68 65 6d 61 20 6e 61 6d 65 2e 0a  nt schema name..
2540: 0a 3c 70 3e 41 6e 20 65 78 61 6d 70 6c 65 20 6f  .<p>An example o
2550: 66 20 61 6e 20 65 70 6f 6e 79 6d 6f 75 73 20 76  f an eponymous v
2560: 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 73 20  irtual table is 
2570: 74 68 65 20 3c 61 20 68 72 65 66 3d 22 64 62 73  the <a href="dbs
2580: 74 61 74 2e 68 74 6d 6c 22 3e 64 62 73 74 61 74  tat.html">dbstat
2590: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 3c 2f   virtual table</
25a0: 61 3e 2e 0a 54 6f 20 75 73 65 20 74 68 65 20 64  a>..To use the d
25b0: 62 73 74 61 74 20 76 69 72 74 75 61 6c 20 74 61  bstat virtual ta
25c0: 62 6c 65 20 61 73 20 61 6e 20 65 70 6f 6e 79 6d  ble as an eponym
25d0: 6f 75 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c  ous virtual tabl
25e0: 65 2c 20 0a 73 69 6d 70 6c 79 20 71 75 65 72 79  e, .simply query
25f0: 20 61 67 61 69 6e 73 74 20 74 68 65 20 22 64 62   against the "db
2600: 73 74 61 74 22 0a 6d 6f 64 75 6c 65 20 6e 61 6d  stat".module nam
2610: 65 2c 20 61 73 20 69 66 20 69 74 20 77 65 72 65  e, as if it were
2620: 20 61 6e 20 6f 72 64 69 6e 61 72 79 20 74 61 62   an ordinary tab
2630: 6c 65 2e 20 20 28 4e 6f 74 65 20 74 68 61 74 20  le.  (Note that 
2640: 53 51 4c 69 74 65 0a 6d 75 73 74 20 62 65 20 63  SQLite.must be c
2650: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
2660: 20 3c 61 20 68 72 65 66 3d 22 63 6f 6d 70 69 6c   <a href="compil
2670: 65 2e 68 74 6d 6c 23 65 6e 61 62 6c 65 5f 64 62  e.html#enable_db
2680: 73 74 61 74 5f 76 74 61 62 22 3e 53 51 4c 49 54  stat_vtab">SQLIT
2690: 45 5f 45 4e 41 42 4c 45 5f 44 42 53 54 41 54 5f  E_ENABLE_DBSTAT_
26a0: 56 54 41 42 3c 2f 61 3e 20 6f 70 74 69 6f 6e 20  VTAB</a> option 
26b0: 74 6f 20 69 6e 63 6c 75 64 65 0a 74 68 65 20 64  to include.the d
26c0: 62 73 74 61 74 20 76 69 72 74 75 61 6c 20 74 61  bstat virtual ta
26d0: 62 6c 65 20 69 6e 20 74 68 65 20 62 75 69 6c 64  ble in the build
26e0: 2e 29 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .)..<blockquote>
26f0: 3c 70 72 65 3e 0a 20 20 20 53 45 4c 45 43 54 20  <pre>.   SELECT 
2700: 2a 20 46 52 4f 4d 20 64 62 73 74 61 74 3b 0a 3c  * FROM dbstat;.<
2710: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
2720: 65 3e 0a 0a 3c 70 3e 41 20 76 69 72 74 75 61 6c  e>..<p>A virtual
2730: 20 74 61 62 6c 65 20 69 73 20 65 70 6f 6e 79 6d   table is eponym
2740: 6f 75 73 20 69 66 20 69 74 73 20 3c 61 20 68 72  ous if its <a hr
2750: 65 66 3d 22 76 74 61 62 2e 68 74 6d 6c 23 78 63  ef="vtab.html#xc
2760: 72 65 61 74 65 22 3e 78 43 72 65 61 74 65 3c 2f  reate">xCreate</
2770: 61 3e 20 6d 65 74 68 6f 64 20 69 73 20 74 68 65  a> method is the
2780: 20 65 78 61 63 74 20 73 61 6d 65 0a 66 75 6e 63   exact same.func
2790: 74 69 6f 6e 20 61 73 20 74 68 65 20 3c 61 20 68  tion as the <a h
27a0: 72 65 66 3d 22 76 74 61 62 2e 68 74 6d 6c 23 78  ref="vtab.html#x
27b0: 63 6f 6e 6e 65 63 74 22 3e 78 43 6f 6e 6e 65 63  connect">xConnec
27c0: 74 3c 2f 61 3e 20 6d 65 74 68 6f 64 2c 20 6f 72  t</a> method, or
27d0: 20 69 66 20 74 68 65 20 3c 61 20 68 72 65 66 3d   if the <a href=
27e0: 22 76 74 61 62 2e 68 74 6d 6c 23 78 63 72 65 61  "vtab.html#xcrea
27f0: 74 65 22 3e 78 43 72 65 61 74 65 3c 2f 61 3e 20  te">xCreate</a> 
2800: 6d 65 74 68 6f 64 20 69 73 20 4e 55 4c 4c 2e 0a  method is NULL..
2810: 54 68 65 20 3c 61 20 68 72 65 66 3d 22 76 74 61  The <a href="vta
2820: 62 2e 68 74 6d 6c 23 78 63 72 65 61 74 65 22 3e  b.html#xcreate">
2830: 78 43 72 65 61 74 65 3c 2f 61 3e 20 6d 65 74 68  xCreate</a> meth
2840: 6f 64 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65  od is called whe
2850: 6e 20 61 20 76 69 72 74 75 61 6c 20 74 61 62 6c  n a virtual tabl
2860: 65 20 69 73 20 66 69 72 73 74 20 63 72 65 61 74  e is first creat
2870: 65 64 0a 75 73 69 6e 67 20 74 68 65 20 3c 61 20  ed.using the <a 
2880: 68 72 65 66 3d 22 6c 61 6e 67 5f 63 72 65 61 74  href="lang_creat
2890: 65 76 74 61 62 2e 68 74 6d 6c 22 3e 43 52 45 41  evtab.html">CREA
28a0: 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45  TE VIRTUAL TABLE
28b0: 3c 2f 61 3e 20 73 74 61 74 65 6d 65 6e 74 2e 20  </a> statement. 
28c0: 20 54 68 65 20 3c 61 20 68 72 65 66 3d 22 76 74   The <a href="vt
28d0: 61 62 2e 68 74 6d 6c 23 78 63 6f 6e 6e 65 63 74  ab.html#xconnect
28e0: 22 3e 78 43 6f 6e 6e 65 63 74 3c 2f 61 3e 20 6d  ">xConnect</a> m
28f0: 65 74 68 6f 64 20 77 68 65 6e 65 76 65 72 0a 61  ethod whenever.a
2900: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2910: 74 69 6f 6e 20 61 74 74 61 63 68 65 73 20 74 6f  tion attaches to
2920: 20 6f 72 20 72 65 70 61 72 73 65 73 20 61 20 73   or reparses a s
2930: 63 68 65 6d 61 2e 20 57 68 65 6e 20 74 68 65 73  chema. When thes
2940: 65 20 74 77 6f 20 6d 65 74 68 6f 64 73 0a 61 72  e two methods.ar
2950: 65 20 74 68 65 20 73 61 6d 65 2c 20 74 68 61 74  e the same, that
2960: 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
2970: 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
2980: 65 20 68 61 73 20 6e 6f 20 70 65 72 73 69 73 74  e has no persist
2990: 65 6e 74 0a 73 74 61 74 65 20 74 68 61 74 20 6e  ent.state that n
29a0: 65 65 64 73 20 74 6f 20 62 65 20 63 72 65 61 74  eeds to be creat
29b0: 65 64 20 61 6e 64 20 64 65 73 74 72 6f 79 65 64  ed and destroyed
29c0: 2e 0a 0a 3c 61 20 6e 61 6d 65 3d 22 65 70 6f 6f  ...<a name="epoo
29d0: 6e 6c 79 76 74 61 62 22 3e 3c 2f 61 3e 0a 0a 3c  nlyvtab"></a>..<
29e0: 68 35 3e 31 2e 31 2e 32 2e 31 20 45 70 6f 6e 79  h5>1.1.2.1 Epony
29f0: 6d 6f 75 73 2d 6f 6e 6c 79 20 76 69 72 74 75 61  mous-only virtua
2a00: 6c 20 74 61 62 6c 65 73 3c 2f 68 35 3e 0a 3c 70  l tables</h5>.<p
2a10: 3e 49 66 20 74 68 65 20 3c 61 20 68 72 65 66 3d  >If the <a href=
2a20: 22 76 74 61 62 2e 68 74 6d 6c 23 78 63 72 65 61  "vtab.html#xcrea
2a30: 74 65 22 3e 78 43 72 65 61 74 65 3c 2f 61 3e 20  te">xCreate</a> 
2a40: 6d 65 74 68 6f 64 20 69 73 20 4e 55 4c 4c 2c 20  method is NULL, 
2a50: 74 68 65 6e 0a 3c 61 20 68 72 65 66 3d 22 6c 61  then.<a href="la
2a60: 6e 67 5f 63 72 65 61 74 65 76 74 61 62 2e 68 74  ng_createvtab.ht
2a70: 6d 6c 22 3e 43 52 45 41 54 45 20 56 49 52 54 55  ml">CREATE VIRTU
2a80: 41 4c 20 54 41 42 4c 45 3c 2f 61 3e 20 73 74 61  AL TABLE</a> sta
2a90: 74 65 6d 65 6e 74 73 20 61 72 65 20 70 72 6f 68  tements are proh
2aa0: 69 62 69 74 65 64 20 66 6f 72 20 74 68 61 74 20  ibited for that 
2ab0: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2c 0a 61  virtual table,.a
2ac0: 6e 64 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  nd the virtual t
2ad0: 61 62 6c 65 20 69 73 20 61 6e 20 22 65 70 6f 6e  able is an "epon
2ae0: 79 6d 6f 75 73 2d 6f 6e 6c 79 20 76 69 72 74 75  ymous-only virtu
2af0: 61 6c 20 74 61 62 6c 65 22 2e 0a 45 70 6f 6e 79  al table"..Epony
2b00: 6d 6f 75 73 2d 6f 6e 6c 79 20 76 69 72 74 75 61  mous-only virtua
2b10: 6c 20 74 61 62 6c 65 73 20 61 72 65 20 75 73 65  l tables are use
2b20: 66 75 6c 20 61 73 20 0a 3c 61 20 68 72 65 66 3d  ful as .<a href=
2b30: 22 76 74 61 62 2e 68 74 6d 6c 23 74 61 62 66 75  "vtab.html#tabfu
2b40: 6e 63 32 22 3e 74 61 62 6c 65 2d 76 61 6c 75 65  nc2">table-value
2b50: 64 20 66 75 6e 63 74 69 6f 6e 73 3c 2f 61 3e 2e  d functions</a>.
2b60: 0a 0a 3c 70 3e 0a 4e 6f 74 65 20 74 68 61 74 20  ..<p>.Note that 
2b70: 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 73 20  SQLite versions 
2b80: 70 72 69 6f 72 20 74 6f 20 33 2e 39 2e 30 20 64  prior to 3.9.0 d
2b90: 69 64 20 6e 6f 74 20 63 68 65 63 6b 20 74 68 65  id not check the
2ba0: 20 78 43 72 65 61 74 65 20 6d 65 74 68 6f 64 0a   xCreate method.
2bb0: 66 6f 72 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20  for NULL before 
2bc0: 69 6e 76 6f 6b 69 6e 67 20 69 74 2e 20 20 53 6f  invoking it.  So
2bd0: 20 69 66 20 61 6e 20 65 70 6f 6e 79 6d 6f 75 73   if an eponymous
2be0: 2d 6f 6e 6c 79 20 76 69 72 74 75 61 6c 20 74 61  -only virtual ta
2bf0: 62 6c 65 20 69 73 0a 72 65 67 69 73 74 65 72 65  ble is.registere
2c00: 64 20 77 69 74 68 20 53 51 4c 69 74 65 20 76 65  d with SQLite ve
2c10: 72 73 69 6f 6e 20 33 2e 38 2e 31 31 2e 31 20 6f  rsion 3.8.11.1 o
2c20: 72 20 65 61 72 6c 69 65 72 20 61 6e 64 20 61 20  r earlier and a 
2c30: 3c 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f 63 72  <a href="lang_cr
2c40: 65 61 74 65 76 74 61 62 2e 68 74 6d 6c 22 3e 43  eatevtab.html">C
2c50: 52 45 41 54 45 20 56 49 52 54 55 41 4c 20 54 41  REATE VIRTUAL TA
2c60: 42 4c 45 3c 2f 61 3e 0a 63 6f 6d 6d 61 6e 64 20  BLE</a>.command 
2c70: 69 73 20 61 74 74 65 6d 70 74 65 64 20 61 67 61  is attempted aga
2c80: 69 6e 73 74 20 74 68 61 74 20 76 69 72 74 75 61  inst that virtua
2c90: 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 2c 20  l table module, 
2ca0: 61 20 6a 75 6d 70 20 74 6f 20 61 20 4e 55 4c 4c  a jump to a NULL
2cb0: 0a 70 6f 69 6e 74 65 72 20 77 69 6c 6c 20 6f 63  .pointer will oc
2cc0: 63 75 72 2c 20 72 65 73 75 6c 74 69 6e 67 20 69  cur, resulting i
2cd0: 6e 20 61 20 63 72 61 73 68 2e 0a 0a 3c 68 33 3e  n a crash...<h3>
2ce0: 31 2e 32 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69  1.2 Implementati
2cf0: 6f 6e 3c 2f 68 33 3e 0a 0a 3c 70 3e 53 65 76 65  on</h3>..<p>Seve
2d00: 72 61 6c 20 6e 65 77 20 43 2d 6c 65 76 65 6c 20  ral new C-level 
2d10: 6f 62 6a 65 63 74 73 20 61 72 65 20 75 73 65 64  objects are used
2d20: 20 62 79 20 74 68 65 20 76 69 72 74 75 61 6c 20   by the virtual 
2d30: 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
2d40: 74 69 6f 6e 3a 0a 0a 3c 62 6c 6f 63 6b 71 75 6f  tion:..<blockquo
2d50: 74 65 3e 3c 70 72 65 3e 0a 20 20 74 79 70 65 64  te><pre>.  typed
2d60: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
2d70: 33 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76  3_vtab sqlite3_v
2d80: 74 61 62 3b 0a 20 20 74 79 70 65 64 65 66 20 73  tab;.  typedef s
2d90: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e  truct sqlite3_in
2da0: 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33  dex_info sqlite3
2db0: 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 20 20 74  _index_info;.  t
2dc0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
2dd0: 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
2de0: 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  r sqlite3_vtab_c
2df0: 75 72 73 6f 72 3b 0a 20 20 74 79 70 65 64 65 66  ursor;.  typedef
2e00: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
2e10: 6d 6f 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d  module sqlite3_m
2e20: 6f 64 75 6c 65 3b 0a 3c 2f 70 72 65 3e 3c 2f 62  odule;.</pre></b
2e30: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54  lockquote>..<p>T
2e40: 68 65 20 3c 61 20 68 72 65 66 3d 22 63 33 72 65  he <a href="c3re
2e50: 66 2f 6d 6f 64 75 6c 65 2e 68 74 6d 6c 22 3e 73  f/module.html">s
2e60: 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3c 2f 61  qlite3_module</a
2e70: 3e 20 73 74 72 75 63 74 75 72 65 20 64 65 66 69  > structure defi
2e80: 6e 65 73 20 61 20 6d 6f 64 75 6c 65 20 6f 62 6a  nes a module obj
2e90: 65 63 74 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  ect used to impl
2ea0: 65 6d 65 6e 74 0a 61 20 76 69 72 74 75 61 6c 20  ement.a virtual 
2eb0: 74 61 62 6c 65 2e 20 54 68 69 6e 6b 20 6f 66 20  table. Think of 
2ec0: 61 20 6d 6f 64 75 6c 65 20 61 73 20 61 20 63 6c  a module as a cl
2ed0: 61 73 73 20 66 72 6f 6d 20 77 68 69 63 68 20 6f  ass from which o
2ee0: 6e 65 20 63 61 6e 20 0a 63 6f 6e 73 74 72 75 63  ne can .construc
2ef0: 74 20 6d 75 6c 74 69 70 6c 65 20 76 69 72 74 75  t multiple virtu
2f00: 61 6c 20 74 61 62 6c 65 73 20 68 61 76 69 6e 67  al tables having
2f10: 20 73 69 6d 69 6c 61 72 20 70 72 6f 70 65 72 74   similar propert
2f20: 69 65 73 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65  ies. For example
2f30: 2c 0a 6f 6e 65 20 6d 69 67 68 74 20 68 61 76 65  ,.one might have
2f40: 20 61 20 6d 6f 64 75 6c 65 20 74 68 61 74 20 70   a module that p
2f50: 72 6f 76 69 64 65 73 20 72 65 61 64 2d 6f 6e 6c  rovides read-onl
2f60: 79 20 61 63 63 65 73 73 20 74 6f 20 0a 63 6f 6d  y access to .com
2f70: 6d 61 2d 73 65 70 61 72 61 74 65 64 2d 76 61 6c  ma-separated-val
2f80: 75 65 20 28 43 53 56 29 20 66 69 6c 65 73 20 6f  ue (CSV) files o
2f90: 6e 20 64 69 73 6b 2e 20 54 68 61 74 20 6f 6e 65  n disk. That one
2fa0: 20 6d 6f 64 75 6c 65 20 63 61 6e 20 74 68 65 6e   module can then
2fb0: 20 62 65 0a 75 73 65 64 20 74 6f 20 63 72 65 61   be.used to crea
2fc0: 74 65 20 73 65 76 65 72 61 6c 20 76 69 72 74 75  te several virtu
2fd0: 61 6c 20 74 61 62 6c 65 73 20 77 68 65 72 65 20  al tables where 
2fe0: 65 61 63 68 20 76 69 72 74 75 61 6c 20 74 61 62  each virtual tab
2ff0: 6c 65 20 72 65 66 65 72 73 0a 74 6f 20 61 20 64  le refers.to a d
3000: 69 66 66 65 72 65 6e 74 20 43 53 56 20 66 69 6c  ifferent CSV fil
3010: 65 2e 0a 0a 3c 70 3e 54 68 65 20 6d 6f 64 75 6c  e...<p>The modul
3020: 65 20 73 74 72 75 63 74 75 72 65 20 63 6f 6e 74  e structure cont
3030: 61 69 6e 73 20 6d 65 74 68 6f 64 73 20 74 68 61  ains methods tha
3040: 74 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79  t are invoked by
3050: 20 53 51 4c 69 74 65 20 74 6f 0a 70 65 72 66 6f   SQLite to.perfo
3060: 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f  rm various actio
3070: 6e 73 20 6f 6e 20 74 68 65 20 76 69 72 74 75 61  ns on the virtua
3080: 6c 20 74 61 62 6c 65 20 73 75 63 68 20 61 73 20  l table such as 
3090: 63 72 65 61 74 69 6e 67 20 6e 65 77 0a 69 6e 73  creating new.ins
30a0: 74 61 6e 63 65 73 20 6f 66 20 61 20 76 69 72 74  tances of a virt
30b0: 75 61 6c 20 74 61 62 6c 65 20 6f 72 20 64 65 73  ual table or des
30c0: 74 72 6f 79 69 6e 67 20 6f 6c 64 20 6f 6e 65 73  troying old ones
30d0: 2c 20 72 65 61 64 69 6e 67 20 61 6e 64 0a 77 72  , reading and.wr
30e0: 69 74 69 6e 67 20 64 61 74 61 2c 20 73 65 61 72  iting data, sear
30f0: 63 68 69 6e 67 20 66 6f 72 20 61 6e 64 20 64 65  ching for and de
3100: 6c 65 74 69 6e 67 2c 20 75 70 64 61 74 69 6e 67  leting, updating
3110: 2c 20 6f 72 20 69 6e 73 65 72 74 69 6e 67 20 72  , or inserting r
3120: 6f 77 73 2e 20 0a 54 68 65 20 6d 6f 64 75 6c 65  ows. .The module
3130: 20 73 74 72 75 63 74 75 72 65 20 69 73 20 65 78   structure is ex
3140: 70 6c 61 69 6e 65 64 20 69 6e 20 6d 6f 72 65 20  plained in more 
3150: 64 65 74 61 69 6c 20 62 65 6c 6f 77 2e 0a 0a 3c  detail below...<
3160: 70 3e 45 61 63 68 20 76 69 72 74 75 61 6c 20 74  p>Each virtual t
3170: 61 62 6c 65 20 69 6e 73 74 61 6e 63 65 20 69 73  able instance is
3180: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
3190: 61 6e 20 3c 61 20 68 72 65 66 3d 22 63 33 72 65  an <a href="c3re
31a0: 66 2f 76 74 61 62 2e 68 74 6d 6c 22 3e 73 71 6c  f/vtab.html">sql
31b0: 69 74 65 33 5f 76 74 61 62 3c 2f 61 3e 20 73 74  ite3_vtab</a> st
31c0: 72 75 63 74 75 72 65 2e 20 0a 54 68 65 20 73 71  ructure. .The sq
31d0: 6c 69 74 65 33 5f 76 74 61 62 20 73 74 72 75 63  lite3_vtab struc
31e0: 74 75 72 65 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20  ture looks like 
31f0: 74 68 69 73 3a 0a 0a 3c 62 6c 6f 63 6b 71 75 6f  this:..<blockquo
3200: 74 65 3e 3c 70 72 65 3e 0a 20 20 73 74 72 75 63  te><pre>.  struc
3210: 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 7b  t sqlite3_vtab {
3220: 0a 20 20 20 20 63 6f 6e 73 74 20 73 71 6c 69 74  .    const sqlit
3230: 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64 75  e3_module *pModu
3240: 6c 65 3b 0a 20 20 20 20 69 6e 74 20 6e 52 65 66  le;.    int nRef
3250: 3b 0a 20 20 20 20 63 68 61 72 20 2a 7a 45 72 72  ;.    char *zErr
3260: 4d 73 67 3b 0a 20 20 7d 3b 0a 3c 2f 70 72 65 3e  Msg;.  };.</pre>
3270: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c  </blockquote>..<
3280: 70 3e 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20  p>Virtual table 
3290: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
32a0: 77 69 6c 6c 20 6e 6f 72 6d 61 6c 6c 79 20 73 75  will normally su
32b0: 62 63 6c 61 73 73 20 74 68 69 73 20 73 74 72 75  bclass this stru
32c0: 63 74 75 72 65 20 0a 74 6f 20 61 64 64 20 61 64  cture .to add ad
32d0: 64 69 74 69 6f 6e 61 6c 20 70 72 69 76 61 74 65  ditional private
32e0: 20 61 6e 64 20 69 6d 70 6c 65 6d 65 6e 74 61 74   and implementat
32f0: 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 66 69 65  ion-specific fie
3300: 6c 64 73 2e 20 0a 54 68 65 20 6e 52 65 66 20 66  lds. .The nRef f
3310: 69 65 6c 64 20 69 73 20 75 73 65 64 20 69 6e 74  ield is used int
3320: 65 72 6e 61 6c 6c 79 20 62 79 20 74 68 65 20 53  ernally by the S
3330: 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 73  QLite core and s
3340: 68 6f 75 6c 64 20 6e 6f 74 20 0a 62 65 20 61 6c  hould not .be al
3350: 74 65 72 65 64 20 62 79 20 74 68 65 20 76 69 72  tered by the vir
3360: 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65  tual table imple
3370: 6d 65 6e 74 61 74 69 6f 6e 2e 20 54 68 65 20 76  mentation. The v
3380: 69 72 74 75 61 6c 20 74 61 62 6c 65 20 0a 69 6d  irtual table .im
3390: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 61 79  plementation may
33a0: 20 70 61 73 73 20 65 72 72 6f 72 20 6d 65 73 73   pass error mess
33b0: 61 67 65 20 74 65 78 74 20 74 6f 20 74 68 65 20  age text to the 
33c0: 63 6f 72 65 20 62 79 20 70 75 74 74 69 6e 67 20  core by putting 
33d0: 0a 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67  .an error messag
33e0: 65 20 73 74 72 69 6e 67 20 69 6e 20 7a 45 72 72  e string in zErr
33f0: 4d 73 67 2e 0a 53 70 61 63 65 20 74 6f 20 68 6f  Msg..Space to ho
3400: 6c 64 20 74 68 69 73 20 65 72 72 6f 72 20 6d 65  ld this error me
3410: 73 73 61 67 65 20 73 74 72 69 6e 67 20 6d 75 73  ssage string mus
3420: 74 20 62 65 20 6f 62 74 61 69 6e 65 64 20 66 72  t be obtained fr
3430: 6f 6d 20 61 6e 0a 53 51 4c 69 74 65 20 6d 65 6d  om an.SQLite mem
3440: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
3450: 75 6e 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20  unction such as 
3460: 3c 61 20 68 72 65 66 3d 22 63 33 72 65 66 2f 6d  <a href="c3ref/m
3470: 70 72 69 6e 74 66 2e 68 74 6d 6c 22 3e 73 71 6c  printf.html">sql
3480: 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 3c 2f  ite3_mprintf()</
3490: 61 3e 20 6f 72 0a 3c 61 20 68 72 65 66 3d 22 63  a> or.<a href="c
34a0: 33 72 65 66 2f 66 72 65 65 2e 68 74 6d 6c 22 3e  3ref/free.html">
34b0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
34c0: 3c 2f 61 3e 2e 0a 50 72 69 6f 72 20 74 6f 20 61  </a>..Prior to a
34d0: 73 73 69 67 6e 69 6e 67 20 61 20 6e 65 77 20 76  ssigning a new v
34e0: 61 6c 75 65 20 74 6f 20 7a 45 72 72 4d 73 67 2c  alue to zErrMsg,
34f0: 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
3500: 6c 65 20 0a 69 6d 70 6c 65 6d 65 6e 74 61 74 69  le .implementati
3510: 6f 6e 20 6d 75 73 74 20 66 72 65 65 20 61 6e 79  on must free any
3520: 20 70 72 65 65 78 69 73 74 69 6e 67 20 63 6f 6e   preexisting con
3530: 74 65 6e 74 20 6f 66 20 7a 45 72 72 4d 73 67 20  tent of zErrMsg 
3540: 75 73 69 6e 67 20 0a 3c 61 20 68 72 65 66 3d 22  using .<a href="
3550: 63 33 72 65 66 2f 66 72 65 65 2e 68 74 6d 6c 22  c3ref/free.html"
3560: 3e 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 3c  >sqlite3_free()<
3570: 2f 61 3e 2e 20 46 61 69 6c 75 72 65 20 74 6f 20  /a>. Failure to 
3580: 64 6f 20 74 68 69 73 20 77 69 6c 6c 20 72 65 73  do this will res
3590: 75 6c 74 20 69 6e 20 61 20 6d 65 6d 6f 72 79 20  ult in a memory 
35a0: 6c 65 61 6b 2e 20 0a 54 68 65 20 53 51 4c 69 74  leak. .The SQLit
35b0: 65 20 63 6f 72 65 20 77 69 6c 6c 20 66 72 65 65  e core will free
35c0: 20 61 6e 64 20 7a 65 72 6f 20 74 68 65 20 63 6f   and zero the co
35d0: 6e 74 65 6e 74 20 6f 66 20 7a 45 72 72 4d 73 67  ntent of zErrMsg
35e0: 20 77 68 65 6e 20 69 74 20 0a 64 65 6c 69 76 65   when it .delive
35f0: 72 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  rs the error mes
3600: 73 61 67 65 20 74 65 78 74 20 74 6f 20 74 68 65  sage text to the
3610: 20 63 6c 69 65 6e 74 20 61 70 70 6c 69 63 61 74   client applicat
3620: 69 6f 6e 20 6f 72 20 77 68 65 6e 20 0a 69 74 20  ion or when .it 
3630: 64 65 73 74 72 6f 79 73 20 74 68 65 20 76 69 72  destroys the vir
3640: 74 75 61 6c 20 74 61 62 6c 65 2e 20 54 68 65 20  tual table. The 
3650: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d  virtual table im
3660: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 6c  plementation onl
3670: 79 20 0a 6e 65 65 64 73 20 74 6f 20 77 6f 72 72  y .needs to worr
3680: 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20  y about freeing 
3690: 74 68 65 20 7a 45 72 72 4d 73 67 20 63 6f 6e 74  the zErrMsg cont
36a0: 65 6e 74 20 77 68 65 6e 20 69 74 20 6f 76 65 72  ent when it over
36b0: 77 72 69 74 65 73 20 0a 74 68 65 20 63 6f 6e 74  writes .the cont
36c0: 65 6e 74 20 77 69 74 68 20 61 20 6e 65 77 2c 20  ent with a new, 
36d0: 64 69 66 66 65 72 65 6e 74 20 65 72 72 6f 72 20  different error 
36e0: 6d 65 73 73 61 67 65 2e 0a 0a 3c 70 3e 54 68 65  message...<p>The
36f0: 20 3c 61 20 68 72 65 66 3d 22 63 33 72 65 66 2f   <a href="c3ref/
3700: 76 74 61 62 5f 63 75 72 73 6f 72 2e 68 74 6d 6c  vtab_cursor.html
3710: 22 3e 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  ">sqlite3_vtab_c
3720: 75 72 73 6f 72 3c 2f 61 3e 20 73 74 72 75 63 74  ursor</a> struct
3730: 75 72 65 20 72 65 70 72 65 73 65 6e 74 73 20 61  ure represents a
3740: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 70   pointer to a sp
3750: 65 63 69 66 69 63 0a 72 6f 77 20 6f 66 20 61 20  ecific.row of a 
3760: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 54  virtual table. T
3770: 68 69 73 20 69 73 20 77 68 61 74 20 61 6e 20 73  his is what an s
3780: 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
3790: 6f 72 20 6c 6f 6f 6b 73 20 6c 69 6b 65 3a 0a 0a  or looks like:..
37a0: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
37b0: 3e 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74  >.  struct sqlit
37c0: 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b  e3_vtab_cursor {
37d0: 0a 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61  .    sqlite3_vta
37e0: 62 20 2a 70 56 74 61 62 3b 0a 20 20 7d 3b 0a 3c  b *pVtab;.  };.<
37f0: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
3800: 65 3e 0a 0a 3c 70 3e 4f 6e 63 65 20 61 67 61 69  e>..<p>Once agai
3810: 6e 2c 20 70 72 61 63 74 69 63 61 6c 20 69 6d 70  n, practical imp
3820: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c  lementations wil
3830: 6c 20 6c 69 6b 65 6c 79 20 73 75 62 63 6c 61 73  l likely subclas
3840: 73 20 74 68 69 73 20 0a 73 74 72 75 63 74 75 72  s this .structur
3850: 65 20 74 6f 20 61 64 64 20 61 64 64 69 74 69 6f  e to add additio
3860: 6e 61 6c 20 70 72 69 76 61 74 65 20 66 69 65 6c  nal private fiel
3870: 64 73 2e 0a 0a 3c 70 3e 54 68 65 20 3c 61 20 68  ds...<p>The <a h
3880: 72 65 66 3d 22 63 33 72 65 66 2f 69 6e 64 65 78  ref="c3ref/index
3890: 5f 69 6e 66 6f 2e 68 74 6d 6c 22 3e 73 71 6c 69  _info.html">sqli
38a0: 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3c 2f  te3_index_info</
38b0: 61 3e 20 73 74 72 75 63 74 75 72 65 20 69 73 20  a> structure is 
38c0: 75 73 65 64 20 74 6f 20 70 61 73 73 20 69 6e 66  used to pass inf
38d0: 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 0a 61 6e  ormation into.an
38e0: 64 20 6f 75 74 20 6f 66 20 74 68 65 20 78 42 65  d out of the xBe
38f0: 73 74 49 6e 64 65 78 20 6d 65 74 68 6f 64 20 6f  stIndex method o
3900: 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 74 68 61  f the module tha
3910: 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 61 20 0a  t implements a .
3920: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 0a 0a  virtual table...
3930: 3c 70 3e 42 65 66 6f 72 65 20 61 20 3c 61 20 68  <p>Before a <a h
3940: 72 65 66 3d 22 6c 61 6e 67 5f 63 72 65 61 74 65  ref="lang_create
3950: 76 74 61 62 2e 68 74 6d 6c 22 3e 43 52 45 41 54  vtab.html">CREAT
3960: 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 3c  E VIRTUAL TABLE<
3970: 2f 61 3e 20 73 74 61 74 65 6d 65 6e 74 20 63 61  /a> statement ca
3980: 6e 20 62 65 20 72 75 6e 2c 20 74 68 65 20 6d 6f  n be run, the mo
3990: 64 75 6c 65 20 0a 73 70 65 63 69 66 69 65 64 20  dule .specified 
39a0: 69 6e 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  in that statemen
39b0: 74 20 6d 75 73 74 20 62 65 20 72 65 67 69 73 74  t must be regist
39c0: 65 72 65 64 20 77 69 74 68 20 74 68 65 20 64 61  ered with the da
39d0: 74 61 62 61 73 65 20 0a 63 6f 6e 6e 65 63 74 69  tabase .connecti
39e0: 6f 6e 2e 20 54 68 69 73 20 69 73 20 61 63 63 6f  on. This is acco
39f0: 6d 70 6c 69 73 68 65 64 20 75 73 69 6e 67 20 65  mplished using e
3a00: 69 74 68 65 72 20 6f 66 20 74 68 65 20 3c 61 20  ither of the <a 
3a10: 68 72 65 66 3d 22 63 33 72 65 66 2f 63 72 65 61  href="c3ref/crea
3a20: 74 65 5f 6d 6f 64 75 6c 65 2e 68 74 6d 6c 22 3e  te_module.html">
3a30: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
3a40: 6f 64 75 6c 65 28 29 3c 2f 61 3e 0a 6f 72 20 3c  odule()</a>.or <
3a50: 61 20 68 72 65 66 3d 22 63 33 72 65 66 2f 63 72  a href="c3ref/cr
3a60: 65 61 74 65 5f 6d 6f 64 75 6c 65 2e 68 74 6d 6c  eate_module.html
3a70: 22 3e 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  ">sqlite3_create
3a80: 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 3c 2f 61 3e  _module_v2()</a>
3a90: 20 69 6e 74 65 72 66 61 63 65 73 3a 0a 0a 3c 62   interfaces:..<b
3aa0: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
3ab0: 20 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72    int sqlite3_cr
3ac0: 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 20  eate_module(.   
3ad0: 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
3ae0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
3af0: 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  QLite connection
3b00: 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64   to register mod
3b10: 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 20 20  ule with */.    
3b20: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
3b30: 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61  e,         /* Na
3b40: 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  me of the module
3b50: 20 2a 2f 0a 20 20 20 20 63 6f 6e 73 74 20 73 71   */.    const sq
3b60: 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 2c 20  lite3_module *, 
3b70: 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f     /* Methods fo
3b80: 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a  r the module */.
3b90: 20 20 20 20 76 6f 69 64 20 2a 20 20 20 20 20 20      void *      
3ba0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
3bb0: 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f  * Client data fo
3bc0: 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65  r xCreate/xConne
3bd0: 63 74 20 2a 2f 0a 20 20 29 3b 0a 20 20 69 6e 74  ct */.  );.  int
3be0: 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
3bf0: 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20 20 20 73  module_v2(.    s
3c00: 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
3c10: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c            /* SQL
3c20: 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ite connection t
3c30: 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c  o register modul
3c40: 65 20 77 69 74 68 20 2a 2f 0a 20 20 20 20 63 6f  e with */.    co
3c50: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
3c60: 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65           /* Name
3c70: 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a   of the module *
3c80: 2f 0a 20 20 20 20 63 6f 6e 73 74 20 73 71 6c 69  /.    const sqli
3c90: 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20 20  te3_module *,   
3ca0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20   /* Methods for 
3cb0: 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20  the module */.  
3cc0: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
3cd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3ce0: 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20  Client data for 
3cf0: 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74  xCreate/xConnect
3d00: 20 2a 2f 0a 20 20 20 20 76 6f 69 64 28 2a 78 44   */.    void(*xD
3d10: 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 20 20  estroy)(void*)  
3d20: 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74     /* Client dat
3d30: 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e  a destructor fun
3d40: 63 74 69 6f 6e 20 2a 2f 0a 20 20 29 3b 0a 3c 2f  ction */.  );.</
3d50: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
3d60: 3e 0a 0a 3c 70 3e 54 68 65 20 3c 61 20 68 72 65  >..<p>The <a hre
3d70: 66 3d 22 63 33 72 65 66 2f 63 72 65 61 74 65 5f  f="c3ref/create_
3d80: 6d 6f 64 75 6c 65 2e 68 74 6d 6c 22 3e 73 71 6c  module.html">sql
3d90: 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
3da0: 6c 65 28 29 3c 2f 61 3e 20 61 6e 64 20 3c 61 20  le()</a> and <a 
3db0: 68 72 65 66 3d 22 63 33 72 65 66 2f 63 72 65 61  href="c3ref/crea
3dc0: 74 65 5f 6d 6f 64 75 6c 65 2e 68 74 6d 6c 22 3e  te_module.html">
3dd0: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
3de0: 6f 64 75 6c 65 5f 76 32 28 29 3c 2f 61 3e 0a 72  odule_v2()</a>.r
3df0: 6f 75 74 69 6e 65 73 20 61 73 73 6f 63 69 61 74  outines associat
3e00: 65 73 20 61 20 6d 6f 64 75 6c 65 20 6e 61 6d 65  es a module name
3e10: 20 77 69 74 68 20 0a 61 6e 20 3c 61 20 68 72 65   with .an <a hre
3e20: 66 3d 22 63 33 72 65 66 2f 6d 6f 64 75 6c 65 2e  f="c3ref/module.
3e30: 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 6d 6f  html">sqlite3_mo
3e40: 64 75 6c 65 3c 2f 61 3e 20 73 74 72 75 63 74 75  dule</a> structu
3e50: 72 65 20 61 6e 64 20 61 20 73 65 70 61 72 61 74  re and a separat
3e60: 65 20 63 6c 69 65 6e 74 20 64 61 74 61 20 74 68  e client data th
3e70: 61 74 20 69 73 20 73 70 65 63 69 66 69 63 20 0a  at is specific .
3e80: 74 6f 20 65 61 63 68 20 6d 6f 64 75 6c 65 2e 20  to each module. 
3e90: 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72   The only differ
3ea0: 65 6e 63 65 20 62 65 74 77 65 65 6e 20 74 68 65  ence between the
3eb0: 20 74 77 6f 20 63 72 65 61 74 65 5f 6d 6f 64 75   two create_modu
3ec0: 6c 65 20 6d 65 74 68 6f 64 73 0a 69 73 20 74 68  le methods.is th
3ed0: 61 74 20 74 68 65 20 5f 76 32 20 6d 65 74 68 6f  at the _v2 metho
3ee0: 64 20 69 6e 63 6c 75 64 65 73 20 61 6e 20 65 78  d includes an ex
3ef0: 74 72 61 20 70 61 72 61 6d 65 74 65 72 20 74 68  tra parameter th
3f00: 61 74 20 73 70 65 63 69 66 69 65 73 20 61 0a 64  at specifies a.d
3f10: 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 63 6c  estructor for cl
3f20: 69 65 6e 74 20 64 61 74 61 20 70 6f 69 6e 74 65  ient data pointe
3f30: 72 2e 20 20 54 68 65 20 6d 6f 64 75 6c 65 20 73  r.  The module s
3f40: 74 72 75 63 74 75 72 65 20 69 73 20 77 68 61 74  tructure is what
3f50: 20 64 65 66 69 6e 65 73 0a 74 68 65 20 62 65 68   defines.the beh
3f60: 61 76 69 6f 72 20 6f 66 20 61 20 76 69 72 74 75  avior of a virtu
3f70: 61 6c 20 74 61 62 6c 65 2e 20 20 54 68 65 20 6d  al table.  The m
3f80: 6f 64 75 6c 65 20 73 74 72 75 63 74 75 72 65 20  odule structure 
3f90: 6c 6f 6f 6b 73 20 6c 69 6b 65 20 74 68 69 73 3a  looks like this:
3fa0: 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  ..<blockquote><p
3fb0: 72 65 3e 20 20 0a 20 20 73 74 72 75 63 74 20 73  re>  .  struct s
3fc0: 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a  qlite3_module {.
3fd0: 20 20 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e      int iVersion
3fe0: 3b 0a 20 20 20 20 69 6e 74 20 28 2a 78 43 72 65  ;.    int (*xCre
3ff0: 61 74 65 29 28 73 71 6c 69 74 65 33 2a 2c 20 76  ate)(sqlite3*, v
4000: 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20  oid *pAux,.     
4010: 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
4020: 61 72 67 63 2c 20 63 68 61 72 20 2a 2a 61 72 67  argc, char **arg
4030: 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  v,.             
4040: 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62      sqlite3_vtab
4050: 20 2a 2a 70 70 56 54 61 62 2c 0a 20 20 20 20 20   **ppVTab,.     
4060: 20 20 20 20 20 20 20 20 20 20 20 20 63 68 61 72              char
4070: 20 2a 2a 70 7a 45 72 72 29 3b 0a 20 20 20 20 69   **pzErr);.    i
4080: 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 74 29 28 73  nt (*xConnect)(s
4090: 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70  qlite3*, void *p
40a0: 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20  Aux,.           
40b0: 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20        int argc, 
40c0: 63 68 61 72 20 2a 2a 61 72 67 76 2c 0a 20 20 20  char **argv,.   
40d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71                sq
40e0: 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56  lite3_vtab **ppV
40f0: 54 61 62 2c 0a 20 20 20 20 20 20 20 20 20 20 20  Tab,.           
4100: 20 20 20 20 20 20 63 68 61 72 20 2a 2a 70 7a 45        char **pzE
4110: 72 72 29 3b 0a 20 20 20 20 69 6e 74 20 28 2a 78  rr);.    int (*x
4120: 42 65 73 74 49 6e 64 65 78 29 28 73 71 6c 69 74  BestIndex)(sqlit
4130: 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20  e3_vtab *pVTab, 
4140: 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
4150: 66 6f 2a 29 3b 0a 20 20 20 20 69 6e 74 20 28 2a  fo*);.    int (*
4160: 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c  xDisconnect)(sql
4170: 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
4180: 29 3b 0a 20 20 20 20 69 6e 74 20 28 2a 78 44 65  );.    int (*xDe
4190: 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76  stroy)(sqlite3_v
41a0: 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 20  tab *pVTab);.   
41b0: 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71   int (*xOpen)(sq
41c0: 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
41d0: 62 2c 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  b, sqlite3_vtab_
41e0: 63 75 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f  cursor **ppCurso
41f0: 72 29 3b 0a 20 20 20 20 69 6e 74 20 28 2a 78 43  r);.    int (*xC
4200: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74  lose)(sqlite3_vt
4210: 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 20  ab_cursor*);.   
4220: 20 69 6e 74 20 28 2a 78 46 69 6c 74 65 72 29 28   int (*xFilter)(
4230: 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
4240: 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d  sor*, int idxNum
4250: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 69 64  , const char *id
4260: 78 53 74 72 2c 0a 20 20 20 20 20 20 20 20 20 20  xStr,.          
4270: 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63          int argc
4280: 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  , sqlite3_value 
4290: 2a 2a 61 72 67 76 29 3b 0a 20 20 20 20 69 6e 74  **argv);.    int
42a0: 20 28 2a 78 4e 65 78 74 29 28 73 71 6c 69 74 65   (*xNext)(sqlite
42b0: 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b  3_vtab_cursor*);
42c0: 0a 20 20 20 20 69 6e 74 20 28 2a 78 45 6f 66 29  .    int (*xEof)
42d0: 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
42e0: 72 73 6f 72 2a 29 3b 0a 20 20 20 20 69 6e 74 20  rsor*);.    int 
42f0: 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74  (*xColumn)(sqlit
4300: 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c  e3_vtab_cursor*,
4310: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
4320: 2a 2c 20 69 6e 74 29 3b 0a 20 20 20 20 69 6e 74  *, int);.    int
4330: 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74   (*xRowid)(sqlit
4340: 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c  e3_vtab_cursor*,
4350: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 2a 70   sqlite_int64 *p
4360: 52 6f 77 69 64 29 3b 0a 20 20 20 20 69 6e 74 20  Rowid);.    int 
4370: 28 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69 74  (*xUpdate)(sqlit
4380: 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20  e3_vtab *, int, 
4390: 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a  sqlite3_value **
43a0: 2c 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 2a  , sqlite_int64 *
43b0: 29 3b 0a 20 20 20 20 69 6e 74 20 28 2a 78 42 65  );.    int (*xBe
43c0: 67 69 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61  gin)(sqlite3_vta
43d0: 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 20 20 69  b *pVTab);.    i
43e0: 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69  nt (*xSync)(sqli
43f0: 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
4400: 3b 0a 20 20 20 20 69 6e 74 20 28 2a 78 43 6f 6d  ;.    int (*xCom
4410: 6d 69 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61  mit)(sqlite3_vta
4420: 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 20 20 69  b *pVTab);.    i
4430: 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 28  nt (*xRollback)(
4440: 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
4450: 54 61 62 29 3b 0a 20 20 20 20 69 6e 74 20 28 2a  Tab);.    int (*
4460: 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 29 28 73  xFindFunction)(s
4470: 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74  qlite3_vtab *pVt
4480: 61 62 2c 20 69 6e 74 20 6e 41 72 67 2c 20 63 6f  ab, int nArg, co
4490: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
44a0: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
44b0: 20 20 20 20 20 20 20 20 76 6f 69 64 20 28 2a 2a          void (**
44c0: 70 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  pxFunc)(sqlite3_
44d0: 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
44e0: 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
44f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4500: 20 20 20 20 20 20 76 6f 69 64 20 2a 2a 70 70 41        void **ppA
4510: 72 67 29 3b 0a 20 20 20 20 69 6e 74 20 28 2a 52  rg);.    int (*R
4520: 65 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  ename)(sqlite3_v
4530: 74 61 62 20 2a 70 56 74 61 62 2c 20 63 6f 6e 73  tab *pVtab, cons
4540: 74 20 63 68 61 72 20 2a 7a 4e 65 77 29 3b 0a 20  t char *zNew);. 
4550: 20 20 20 2f 2a 20 54 68 65 20 6d 65 74 68 6f 64     /* The method
4560: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
4570: 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20  ersion 1 of the 
4580: 73 71 6c 69 74 65 5f 6d 6f 64 75 6c 65 20 6f 62  sqlite_module ob
4590: 6a 65 63 74 2e 20 54 68 6f 73 65 20 0a 20 20 20  ject. Those .   
45a0: 20 2a 2a 20 62 65 6c 6f 77 20 61 72 65 20 66 6f   ** below are fo
45b0: 72 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20  r version 2 and 
45c0: 67 72 65 61 74 65 72 2e 20 2a 2f 0a 20 20 20 20  greater. */.    
45d0: 69 6e 74 20 28 2a 78 53 61 76 65 70 6f 69 6e 74  int (*xSavepoint
45e0: 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
45f0: 70 56 54 61 62 2c 20 69 6e 74 29 3b 0a 20 20 20  pVTab, int);.   
4600: 20 69 6e 74 20 28 2a 78 52 65 6c 65 61 73 65 29   int (*xRelease)
4610: 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
4620: 56 54 61 62 2c 20 69 6e 74 29 3b 0a 20 20 20 20  VTab, int);.    
4630: 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 54  int (*xRollbackT
4640: 6f 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  o)(sqlite3_vtab 
4650: 2a 70 56 54 61 62 2c 20 69 6e 74 29 3b 0a 20 20  *pVTab, int);.  
4660: 7d 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  };.</pre></block
4670: 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68 65 20 6d  quote>..<p>The m
4680: 6f 64 75 6c 65 20 73 74 72 75 63 74 75 72 65 20  odule structure 
4690: 64 65 66 69 6e 65 73 20 61 6c 6c 20 6f 66 20 74  defines all of t
46a0: 68 65 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 65  he methods for e
46b0: 61 63 68 20 76 69 72 74 75 61 6c 20 0a 74 61 62  ach virtual .tab
46c0: 6c 65 20 6f 62 6a 65 63 74 2e 20 54 68 65 20 6d  le object. The m
46d0: 6f 64 75 6c 65 20 73 74 72 75 63 74 75 72 65 20  odule structure 
46e0: 61 6c 73 6f 20 63 6f 6e 74 61 69 6e 73 20 74 68  also contains th
46f0: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64  e iVersion field
4700: 20 77 68 69 63 68 0a 64 65 66 69 6e 65 73 20 74   which.defines t
4710: 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 65 64  he particular ed
4720: 69 74 69 6f 6e 20 6f 66 20 74 68 65 20 6d 6f 64  ition of the mod
4730: 75 6c 65 20 74 61 62 6c 65 20 73 74 72 75 63 74  ule table struct
4740: 75 72 65 2e 20 43 75 72 72 65 6e 74 6c 79 2c 20  ure. Currently, 
4750: 0a 69 56 65 72 73 69 6f 6e 20 69 73 20 61 6c 77  .iVersion is alw
4760: 61 79 73 20 31 2c 20 62 75 74 20 69 6e 20 66 75  ays 1, but in fu
4770: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
4780: 20 53 51 4c 69 74 65 20 74 68 65 20 6d 6f 64 75   SQLite the modu
4790: 6c 65 20 73 74 72 75 63 74 75 72 65 20 0a 64 65  le structure .de
47a0: 66 69 6e 69 74 69 6f 6e 20 6d 69 67 68 74 20 62  finition might b
47b0: 65 20 65 78 74 65 6e 64 65 64 20 77 69 74 68 20  e extended with 
47c0: 61 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f  additional metho
47d0: 64 73 20 61 6e 64 20 69 6e 20 74 68 61 74 20 63  ds and in that c
47e0: 61 73 65 20 0a 74 68 65 20 69 56 65 72 73 69 6f  ase .the iVersio
47f0: 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20  n value will be 
4800: 69 6e 63 72 65 61 73 65 64 2e 0a 0a 3c 70 3e 54  increased...<p>T
4810: 68 65 20 72 65 73 74 20 6f 66 20 74 68 65 20 6d  he rest of the m
4820: 6f 64 75 6c 65 20 73 74 72 75 63 74 75 72 65 20  odule structure 
4830: 63 6f 6e 73 69 73 74 73 20 6f 66 20 6d 65 74 68  consists of meth
4840: 6f 64 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  ods used to impl
4850: 65 6d 65 6e 74 0a 76 61 72 69 6f 75 73 20 66 65  ement.various fe
4860: 61 74 75 72 65 73 20 6f 66 20 74 68 65 20 76 69  atures of the vi
4870: 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 44 65 74  rtual table. Det
4880: 61 69 6c 73 20 6f 6e 20 77 68 61 74 20 65 61 63  ails on what eac
4890: 68 20 6f 66 20 74 68 65 73 65 20 0a 6d 65 74 68  h of these .meth
48a0: 6f 64 73 20 64 6f 20 61 72 65 20 70 72 6f 76 69  ods do are provi
48b0: 64 65 64 20 69 6e 20 74 68 65 20 73 65 71 75 65  ded in the seque
48c0: 6c 2e 0a 0a 3c 68 33 3e 31 2e 33 20 56 69 72 74  l...<h3>1.3 Virt
48d0: 75 61 6c 20 54 61 62 6c 65 73 20 41 6e 64 20 53  ual Tables And S
48e0: 68 61 72 65 64 20 43 61 63 68 65 3c 2f 68 33 3e  hared Cache</h3>
48f0: 0a 0a 3c 70 3e 50 72 69 6f 72 20 74 6f 20 53 51  ..<p>Prior to SQ
4900: 4c 69 74 65 20 3c 61 20 68 72 65 66 3d 22 72 65  Lite <a href="re
4910: 6c 65 61 73 65 6c 6f 67 2f 33 5f 36 5f 31 37 2e  leaselog/3_6_17.
4920: 68 74 6d 6c 22 3e 76 65 72 73 69 6f 6e 20 33 2e  html">version 3.
4930: 36 2e 31 37 3c 2f 61 3e 2c 20 74 68 65 20 76 69  6.17</a>, the vi
4940: 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 63 68  rtual table mech
4950: 61 6e 69 73 6d 20 61 73 73 75 6d 65 73 20 0a 74  anism assumes .t
4960: 68 61 74 20 65 61 63 68 20 3c 61 20 68 72 65 66  hat each <a href
4970: 3d 22 63 33 72 65 66 2f 73 71 6c 69 74 65 33 2e  ="c3ref/sqlite3.
4980: 68 74 6d 6c 22 3e 64 61 74 61 62 61 73 65 20 63  html">database c
4990: 6f 6e 6e 65 63 74 69 6f 6e 3c 2f 61 3e 20 6b 65  onnection</a> ke
49a0: 70 74 0a 69 74 73 20 6f 77 6e 20 63 6f 70 79 20  pt.its own copy 
49b0: 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
49c0: 73 63 68 65 6d 61 2e 20 48 65 6e 63 65 2c 20 74  schema. Hence, t
49d0: 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
49e0: 20 6d 65 63 68 61 6e 69 73 6d 0a 63 6f 75 6c 64   mechanism.could
49f0: 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 6e 20   not be used in 
4a00: 61 20 64 61 74 61 62 61 73 65 20 74 68 61 74 20  a database that 
4a10: 68 61 73 20 3c 61 20 68 72 65 66 3d 22 73 68 61  has <a href="sha
4a20: 72 65 64 63 61 63 68 65 2e 68 74 6d 6c 22 3e 73  redcache.html">s
4a30: 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
4a40: 3c 2f 61 3e 20 65 6e 61 62 6c 65 64 2e 20 0a 54  </a> enabled. .T
4a50: 68 65 20 3c 61 20 68 72 65 66 3d 22 63 33 72 65  he <a href="c3re
4a60: 66 2f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 2e  f/create_module.
4a70: 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 63 72  html">sqlite3_cr
4a80: 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 3c 2f 61  eate_module()</a
4a90: 3e 20 69 6e 74 65 72 66 61 63 65 20 77 6f 75 6c  > interface woul
4aa0: 64 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f  d return an erro
4ab0: 72 20 69 66 20 0a 3c 61 20 68 72 65 66 3d 22 73  r if .<a href="s
4ac0: 68 61 72 65 64 63 61 63 68 65 2e 68 74 6d 6c 22  haredcache.html"
4ad0: 3e 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  >shared cache mo
4ae0: 64 65 3c 2f 61 3e 20 69 73 20 65 6e 61 62 6c 65  de</a> is enable
4af0: 64 2e 20 20 54 68 61 74 20 72 65 73 74 72 69 63  d.  That restric
4b00: 74 69 6f 6e 20 77 61 73 20 72 65 6c 61 78 65 64  tion was relaxed
4b10: 0a 62 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 20  .beginning with 
4b20: 53 51 4c 69 74 65 20 3c 61 20 68 72 65 66 3d 22  SQLite <a href="
4b30: 72 65 6c 65 61 73 65 6c 6f 67 2f 33 5f 36 5f 31  releaselog/3_6_1
4b40: 37 2e 68 74 6d 6c 22 3e 76 65 72 73 69 6f 6e 20  7.html">version 
4b50: 33 2e 36 2e 31 37 3c 2f 61 3e 2e 0a 0a 3c 68 33  3.6.17</a>...<h3
4b60: 3e 31 2e 34 20 43 72 65 61 74 69 6e 67 20 4e 65  >1.4 Creating Ne
4b70: 77 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  w Virtual Table 
4b80: 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 3c  Implementations<
4b90: 2f 68 33 3e 0a 0a 3c 70 3e 46 6f 6c 6c 6f 77 20  /h3>..<p>Follow 
4ba0: 74 68 65 73 65 20 73 74 65 70 73 20 74 6f 20 63  these steps to c
4bb0: 72 65 61 74 65 20 79 6f 75 72 20 6f 77 6e 20 76  reate your own v
4bc0: 69 72 74 75 61 6c 20 74 61 62 6c 65 3a 0a 0a 3c  irtual table:..<
4bd0: 70 3e 0a 3c 6f 6c 3e 0a 3c 6c 69 3e 20 57 72 69  p>.<ol>.<li> Wri
4be0: 74 65 20 61 6c 6c 20 6e 65 63 65 73 73 61 72 79  te all necessary
4bf0: 20 6d 65 74 68 6f 64 73 2e 0a 3c 6c 69 3e 20 43   methods..<li> C
4c00: 72 65 61 74 65 20 61 6e 20 69 6e 73 74 61 6e 63  reate an instanc
4c10: 65 20 6f 66 20 74 68 65 20 3c 61 20 68 72 65 66  e of the <a href
4c20: 3d 22 63 33 72 65 66 2f 6d 6f 64 75 6c 65 2e 68  ="c3ref/module.h
4c30: 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 6d 6f 64  tml">sqlite3_mod
4c40: 75 6c 65 3c 2f 61 3e 20 73 74 72 75 63 74 75 72  ule</a> structur
4c50: 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 70 6f 69  e containing poi
4c60: 6e 74 65 72 73 0a 20 20 20 20 20 74 6f 20 61 6c  nters.     to al
4c70: 6c 20 74 68 65 20 6d 65 74 68 6f 64 73 20 66 72  l the methods fr
4c80: 6f 6d 20 73 74 65 70 20 31 2e 0a 3c 6c 69 3e 20  om step 1..<li> 
4c90: 52 65 67 69 73 74 65 72 20 79 6f 75 72 20 3c 61  Register your <a
4ca0: 20 68 72 65 66 3d 22 63 33 72 65 66 2f 6d 6f 64   href="c3ref/mod
4cb0: 75 6c 65 2e 68 74 6d 6c 22 3e 73 71 6c 69 74 65  ule.html">sqlite
4cc0: 33 5f 6d 6f 64 75 6c 65 3c 2f 61 3e 20 73 74 72  3_module</a> str
4cd0: 75 63 74 75 72 65 20 75 73 69 6e 67 20 6f 6e 65  ucture using one
4ce0: 20 6f 66 20 74 68 65 0a 20 20 20 20 20 3c 61 20   of the.     <a 
4cf0: 68 72 65 66 3d 22 63 33 72 65 66 2f 63 72 65 61  href="c3ref/crea
4d00: 74 65 5f 6d 6f 64 75 6c 65 2e 68 74 6d 6c 22 3e  te_module.html">
4d10: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
4d20: 6f 64 75 6c 65 28 29 3c 2f 61 3e 20 6f 72 20 3c  odule()</a> or <
4d30: 61 20 68 72 65 66 3d 22 63 33 72 65 66 2f 63 72  a href="c3ref/cr
4d40: 65 61 74 65 5f 6d 6f 64 75 6c 65 2e 68 74 6d 6c  eate_module.html
4d50: 22 3e 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  ">sqlite3_create
4d60: 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 3c 2f 61 3e  _module_v2()</a>
4d70: 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 3c 6c 69   interfaces..<li
4d80: 3e 20 52 75 6e 20 61 20 3c 61 20 68 72 65 66 3d  > Run a <a href=
4d90: 22 6c 61 6e 67 5f 63 72 65 61 74 65 76 74 61 62  "lang_createvtab
4da0: 2e 68 74 6d 6c 22 3e 43 52 45 41 54 45 20 56 49  .html">CREATE VI
4db0: 52 54 55 41 4c 20 54 41 42 4c 45 3c 2f 61 3e 20  RTUAL TABLE</a> 
4dc0: 63 6f 6d 6d 61 6e 64 20 74 68 61 74 20 73 70 65  command that spe
4dd0: 63 69 66 69 65 73 20 74 68 65 20 6e 65 77 20 6d  cifies the new m
4de0: 6f 64 75 6c 65 20 69 6e 20 0a 20 20 20 20 20 74  odule in .     t
4df0: 68 65 20 55 53 49 4e 47 20 63 6c 61 75 73 65 2e  he USING clause.
4e00: 20 0a 3c 2f 6f 6c 3e 0a 0a 3c 70 3e 54 68 65 20   .</ol>..<p>The 
4e10: 6f 6e 6c 79 20 72 65 61 6c 6c 79 20 68 61 72 64  only really hard
4e20: 20 70 61 72 74 20 69 73 20 73 74 65 70 20 31 2e   part is step 1.
4e30: 20 59 6f 75 20 6d 69 67 68 74 20 77 61 6e 74 20   You might want 
4e40: 74 6f 20 73 74 61 72 74 20 77 69 74 68 20 61 6e  to start with an
4e50: 20 0a 65 78 69 73 74 69 6e 67 20 76 69 72 74 75   .existing virtu
4e60: 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  al table impleme
4e70: 6e 74 61 74 69 6f 6e 20 61 6e 64 20 6d 6f 64 69  ntation and modi
4e80: 66 79 20 69 74 20 74 6f 20 73 75 69 74 20 79 6f  fy it to suit yo
4e90: 75 72 20 6e 65 65 64 73 2e 0a 54 68 65 72 65 20  ur needs..There 
4ea0: 61 72 65 20 73 65 76 65 72 61 6c 20 76 69 72 74  are several virt
4eb0: 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
4ec0: 65 6e 74 61 74 69 6f 6e 73 20 69 6e 20 74 68 65  entations in the
4ed0: 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74   SQLite source t
4ee0: 72 65 65 20 0a 28 66 6f 72 20 74 65 73 74 69 6e  ree .(for testin
4ef0: 67 20 70 75 72 70 6f 73 65 73 29 2e 20 59 6f 75  g purposes). You
4f00: 20 6d 69 67 68 74 20 75 73 65 20 6f 6e 65 20 6f   might use one o
4f10: 66 20 74 68 6f 73 65 20 61 73 20 61 20 67 75 69  f those as a gui
4f20: 64 65 2e 20 4c 6f 63 61 74 65 20 0a 74 68 65 73  de. Locate .thes
4f30: 65 20 74 65 73 74 20 76 69 72 74 75 61 6c 20 74  e test virtual t
4f40: 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
4f50: 69 6f 6e 73 20 62 79 20 73 65 61 72 63 68 69 6e  ions by searchin
4f60: 67 20 0a 66 6f 72 20 22 73 71 6c 69 74 65 33 5f  g .for "sqlite3_
4f70: 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 22 2e 0a  create_module"..
4f80: 0a 3c 70 3e 59 6f 75 20 6d 69 67 68 74 20 61 6c  .<p>You might al
4f90: 73 6f 20 77 61 6e 74 20 74 6f 20 69 6d 70 6c 65  so want to imple
4fa0: 6d 65 6e 74 20 79 6f 75 72 20 6e 65 77 20 76 69  ment your new vi
4fb0: 72 74 75 61 6c 20 74 61 62 6c 65 20 61 73 20 61  rtual table as a
4fc0: 20 0a 3c 61 20 68 72 65 66 3d 22 63 33 72 65 66   .<a href="c3ref
4fd0: 2f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 2e  /load_extension.
4fe0: 68 74 6d 6c 22 3e 6c 6f 61 64 61 62 6c 65 20 65  html">loadable e
4ff0: 78 74 65 6e 73 69 6f 6e 3c 2f 61 3e 2e 0a 0a 3c  xtension</a>...<
5000: 68 32 3e 32 2e 30 20 56 69 72 74 75 61 6c 20 54  h2>2.0 Virtual T
5010: 61 62 6c 65 20 4d 65 74 68 6f 64 73 3c 2f 68 32  able Methods</h2
5020: 3e 0a 0a 3c 61 20 6e 61 6d 65 3d 22 78 63 72 65  >..<a name="xcre
5030: 61 74 65 22 3e 3c 2f 61 3e 0a 0a 3c 68 33 3e 32  ate"></a>..<h3>2
5040: 2e 31 20 54 68 65 20 78 43 72 65 61 74 65 20 4d  .1 The xCreate M
5050: 65 74 68 6f 64 3c 2f 68 33 3e 0a 0a 3c 62 6c 6f  ethod</h3>..<blo
5060: 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 20 20  ckquote><pre>.  
5070: 69 6e 74 20 28 2a 78 43 72 65 61 74 65 29 28 73  int (*xCreate)(s
5080: 71 6c 69 74 65 33 20 2a 64 62 2c 20 76 6f 69 64  qlite3 *db, void
5090: 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20   *pAux,.        
50a0: 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c         int argc,
50b0: 20 63 68 61 72 20 2a 2a 61 72 67 76 2c 0a 20 20   char **argv,.  
50c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c               sql
50d0: 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54  ite3_vtab **ppVT
50e0: 61 62 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  ab,.            
50f0: 20 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 29     char **pzErr)
5100: 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  ;.</pre></blockq
5110: 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68 69 73 20 6d  uote>..<p>This m
5120: 65 74 68 6f 64 20 69 73 20 63 61 6c 6c 65 64 20  ethod is called 
5130: 74 6f 20 63 72 65 61 74 65 20 61 20 6e 65 77 20  to create a new 
5140: 69 6e 73 74 61 6e 63 65 20 6f 66 20 61 20 76 69  instance of a vi
5150: 72 74 75 61 6c 20 74 61 62 6c 65 20 0a 69 6e 20  rtual table .in 
5160: 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 3c 61  response to a <a
5170: 20 68 72 65 66 3d 22 6c 61 6e 67 5f 63 72 65 61   href="lang_crea
5180: 74 65 76 74 61 62 2e 68 74 6d 6c 22 3e 43 52 45  tevtab.html">CRE
5190: 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c  ATE VIRTUAL TABL
51a0: 45 3c 2f 61 3e 20 73 74 61 74 65 6d 65 6e 74 2e  E</a> statement.
51b0: 20 0a 54 68 65 20 64 62 20 70 61 72 61 6d 65 74   .The db paramet
51c0: 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
51d0: 74 6f 20 74 68 65 20 53 51 4c 69 74 65 20 3c 61  to the SQLite <a
51e0: 20 68 72 65 66 3d 22 63 33 72 65 66 2f 73 71 6c   href="c3ref/sql
51f0: 69 74 65 33 2e 68 74 6d 6c 22 3e 64 61 74 61 62  ite3.html">datab
5200: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 3c 2f  ase connection</
5210: 61 3e 20 74 68 61 74 20 0a 69 73 20 65 78 65 63  a> that .is exec
5220: 75 74 69 6e 67 20 74 68 65 20 3c 61 20 68 72 65  uting the <a hre
5230: 66 3d 22 6c 61 6e 67 5f 63 72 65 61 74 65 76 74  f="lang_createvt
5240: 61 62 2e 68 74 6d 6c 22 3e 43 52 45 41 54 45 20  ab.html">CREATE 
5250: 56 49 52 54 55 41 4c 20 54 41 42 4c 45 3c 2f 61  VIRTUAL TABLE</a
5260: 3e 20 73 74 61 74 65 6d 65 6e 74 2e 20 0a 54 68  > statement. .Th
5270: 65 20 70 41 75 78 20 61 72 67 75 6d 65 6e 74 20  e pAux argument 
5280: 69 73 20 74 68 65 20 63 6f 70 79 20 6f 66 20 74  is the copy of t
5290: 68 65 20 63 6c 69 65 6e 74 20 64 61 74 61 20 70  he client data p
52a0: 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20  ointer that was 
52b0: 74 68 65 20 0a 66 6f 75 72 74 68 20 61 72 67 75  the .fourth argu
52c0: 6d 65 6e 74 20 74 6f 20 74 68 65 20 3c 61 20 68  ment to the <a h
52d0: 72 65 66 3d 22 63 33 72 65 66 2f 63 72 65 61 74  ref="c3ref/creat
52e0: 65 5f 6d 6f 64 75 6c 65 2e 68 74 6d 6c 22 3e 73  e_module.html">s
52f0: 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
5300: 64 75 6c 65 28 29 3c 2f 61 3e 20 6f 72 0a 3c 61  dule()</a> or.<a
5310: 20 68 72 65 66 3d 22 63 33 72 65 66 2f 63 72 65   href="c3ref/cre
5320: 61 74 65 5f 6d 6f 64 75 6c 65 2e 68 74 6d 6c 22  ate_module.html"
5330: 3e 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  >sqlite3_create_
5340: 6d 6f 64 75 6c 65 5f 76 32 28 29 3c 2f 61 3e 20  module_v2()</a> 
5350: 63 61 6c 6c 20 74 68 61 74 20 72 65 67 69 73 74  call that regist
5360: 65 72 65 64 20 74 68 65 20 0a 3c 61 20 68 72 65  ered the .<a hre
5370: 66 3d 22 63 33 72 65 66 2f 6d 6f 64 75 6c 65 2e  f="c3ref/module.
5380: 68 74 6d 6c 22 3e 76 69 72 74 75 61 6c 20 74 61  html">virtual ta
5390: 62 6c 65 20 6d 6f 64 75 6c 65 3c 2f 61 3e 2e 20  ble module</a>. 
53a0: 0a 54 68 65 20 61 72 67 76 20 70 61 72 61 6d 65  .The argv parame
53b0: 74 65 72 20 69 73 20 61 6e 20 61 72 72 61 79 20  ter is an array 
53c0: 6f 66 20 61 72 67 63 20 70 6f 69 6e 74 65 72 73  of argc pointers
53d0: 20 74 6f 20 6e 75 6c 6c 20 74 65 72 6d 69 6e 61   to null termina
53e0: 74 65 64 20 73 74 72 69 6e 67 73 2e 20 0a 54 68  ted strings. .Th
53f0: 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 2c 20  e first string, 
5400: 61 72 67 76 5b 30 5d 2c 20 69 73 20 74 68 65 20  argv[0], is the 
5410: 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75  name of the modu
5420: 6c 65 20 62 65 69 6e 67 20 69 6e 76 6f 6b 65 64  le being invoked
5430: 2e 20 20 20 54 68 65 0a 6d 6f 64 75 6c 65 20 6e  .   The.module n
5440: 61 6d 65 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ame is the name 
5450: 70 72 6f 76 69 64 65 64 20 61 73 20 74 68 65 20  provided as the 
5460: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
5470: 74 6f 20 0a 3c 61 20 68 72 65 66 3d 22 63 33 72  to .<a href="c3r
5480: 65 66 2f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  ef/create_module
5490: 2e 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 63  .html">sqlite3_c
54a0: 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 3c 2f  reate_module()</
54b0: 61 3e 20 61 6e 64 20 61 73 20 74 68 65 20 61 72  a> and as the ar
54c0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 55 53  gument to the US
54d0: 49 4e 47 20 63 6c 61 75 73 65 20 6f 66 20 74 68  ING clause of th
54e0: 65 0a 3c 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f  e.<a href="lang_
54f0: 63 72 65 61 74 65 76 74 61 62 2e 68 74 6d 6c 22  createvtab.html"
5500: 3e 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20  >CREATE VIRTUAL 
5510: 54 41 42 4c 45 3c 2f 61 3e 20 73 74 61 74 65 6d  TABLE</a> statem
5520: 65 6e 74 20 74 68 61 74 20 69 73 20 72 75 6e 6e  ent that is runn
5530: 69 6e 67 2e 0a 54 68 65 20 73 65 63 6f 6e 64 2c  ing..The second,
5540: 20 61 72 67 76 5b 31 5d 2c 20 69 73 20 74 68 65   argv[1], is the
5550: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
5560: 61 62 61 73 65 20 69 6e 20 77 68 69 63 68 20 74  abase in which t
5570: 68 65 20 6e 65 77 20 76 69 72 74 75 61 6c 20 74  he new virtual t
5580: 61 62 6c 65 20 69 73 20 62 65 69 6e 67 20 63 72  able is being cr
5590: 65 61 74 65 64 2e 20 54 68 65 20 64 61 74 61 62  eated. The datab
55a0: 61 73 65 20 6e 61 6d 65 20 69 73 20 22 6d 61 69  ase name is "mai
55b0: 6e 22 20 66 6f 72 20 74 68 65 20 70 72 69 6d 61  n" for the prima
55c0: 72 79 20 64 61 74 61 62 61 73 65 2c 20 6f 72 0a  ry database, or.
55d0: 22 74 65 6d 70 22 20 66 6f 72 20 54 45 4d 50 20  "temp" for TEMP 
55e0: 64 61 74 61 62 61 73 65 2c 20 6f 72 20 74 68 65  database, or the
55f0: 20 6e 61 6d 65 20 67 69 76 65 6e 20 61 74 20 74   name given at t
5600: 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 3c 61  he end of the <a
5610: 20 68 72 65 66 3d 22 6c 61 6e 67 5f 61 74 74 61   href="lang_atta
5620: 63 68 2e 68 74 6d 6c 22 3e 41 54 54 41 43 48 3c  ch.html">ATTACH<
5630: 2f 61 3e 0a 73 74 61 74 65 6d 65 6e 74 20 66 6f  /a>.statement fo
5640: 72 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  r attached datab
5650: 61 73 65 73 2e 20 20 54 68 65 20 74 68 69 72 64  ases.  The third
5660: 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20   element of the 
5670: 61 72 72 61 79 2c 20 61 72 67 76 5b 32 5d 2c 20  array, argv[2], 
5680: 0a 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .is the name of 
5690: 74 68 65 20 6e 65 77 20 76 69 72 74 75 61 6c 20  the new virtual 
56a0: 74 61 62 6c 65 2c 20 61 73 20 73 70 65 63 69 66  table, as specif
56b0: 69 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  ied following th
56c0: 65 20 54 41 42 4c 45 0a 6b 65 79 77 6f 72 64 20  e TABLE.keyword 
56d0: 69 6e 20 74 68 65 20 3c 61 20 68 72 65 66 3d 22  in the <a href="
56e0: 6c 61 6e 67 5f 63 72 65 61 74 65 76 74 61 62 2e  lang_createvtab.
56f0: 68 74 6d 6c 22 3e 43 52 45 41 54 45 20 56 49 52  html">CREATE VIR
5700: 54 55 41 4c 20 54 41 42 4c 45 3c 2f 61 3e 20 73  TUAL TABLE</a> s
5710: 74 61 74 65 6d 65 6e 74 2e 0a 49 66 20 70 72 65  tatement..If pre
5720: 73 65 6e 74 2c 20 74 68 65 20 66 6f 75 72 74 68  sent, the fourth
5730: 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
5740: 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 61  strings in the a
5750: 72 67 76 5b 5d 20 61 72 72 61 79 20 72 65 70 6f  rgv[] array repo
5760: 72 74 20 0a 74 68 65 20 61 72 67 75 6d 65 6e 74  rt .the argument
5770: 73 20 74 6f 20 74 68 65 20 6d 6f 64 75 6c 65 20  s to the module 
5780: 6e 61 6d 65 20 69 6e 20 74 68 65 20 3c 61 20 68  name in the <a h
5790: 72 65 66 3d 22 6c 61 6e 67 5f 63 72 65 61 74 65  ref="lang_create
57a0: 76 74 61 62 2e 68 74 6d 6c 22 3e 43 52 45 41 54  vtab.html">CREAT
57b0: 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 3c  E VIRTUAL TABLE<
57c0: 2f 61 3e 20 73 74 61 74 65 6d 65 6e 74 2e 0a 0a  /a> statement...
57d0: 3c 70 3e 54 68 65 20 6a 6f 62 20 6f 66 20 74 68  <p>The job of th
57e0: 69 73 20 6d 65 74 68 6f 64 20 69 73 20 74 6f 20  is method is to 
57f0: 63 6f 6e 73 74 72 75 63 74 20 74 68 65 20 6e 65  construct the ne
5800: 77 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  w virtual table 
5810: 6f 62 6a 65 63 74 0a 28 61 6e 20 3c 61 20 68 72  object.(an <a hr
5820: 65 66 3d 22 63 33 72 65 66 2f 76 74 61 62 2e 68  ef="c3ref/vtab.h
5830: 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 76 74 61  tml">sqlite3_vta
5840: 62 3c 2f 61 3e 20 6f 62 6a 65 63 74 29 20 61 6e  b</a> object) an
5850: 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74  d return a point
5860: 65 72 20 74 6f 20 69 74 20 69 6e 20 2a 70 70 56  er to it in *ppV
5870: 54 61 62 2e 0a 0a 3c 70 3e 41 73 20 70 61 72 74  Tab...<p>As part
5880: 20 6f 66 20 74 68 65 20 74 61 73 6b 20 6f 66 20   of the task of 
5890: 63 72 65 61 74 69 6e 67 20 61 20 6e 65 77 20 3c  creating a new <
58a0: 61 20 68 72 65 66 3d 22 63 33 72 65 66 2f 76 74  a href="c3ref/vt
58b0: 61 62 2e 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33  ab.html">sqlite3
58c0: 5f 76 74 61 62 3c 2f 61 3e 20 73 74 72 75 63 74  _vtab</a> struct
58d0: 75 72 65 2c 20 74 68 69 73 20 0a 6d 65 74 68 6f  ure, this .metho
58e0: 64 20 3c 75 3e 6d 75 73 74 3c 2f 75 3e 20 69 6e  d <u>must</u> in
58f0: 76 6f 6b 65 20 3c 61 20 68 72 65 66 3d 22 63 33  voke <a href="c3
5900: 72 65 66 2f 64 65 63 6c 61 72 65 5f 76 74 61 62  ref/declare_vtab
5910: 2e 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 64  .html">sqlite3_d
5920: 65 63 6c 61 72 65 5f 76 74 61 62 28 29 3c 2f 61  eclare_vtab()</a
5930: 3e 20 74 6f 20 74 65 6c 6c 20 74 68 65 20 53 51  > to tell the SQ
5940: 4c 69 74 65 20 0a 63 6f 72 65 20 61 62 6f 75 74  Lite .core about
5950: 20 74 68 65 20 63 6f 6c 75 6d 6e 73 20 61 6e 64   the columns and
5960: 20 64 61 74 61 74 79 70 65 73 20 69 6e 20 74 68   datatypes in th
5970: 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e  e virtual table.
5980: 20 0a 54 68 65 20 3c 61 20 68 72 65 66 3d 22 63   .The <a href="c
5990: 33 72 65 66 2f 64 65 63 6c 61 72 65 5f 76 74 61  3ref/declare_vta
59a0: 62 2e 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f  b.html">sqlite3_
59b0: 64 65 63 6c 61 72 65 5f 76 74 61 62 28 29 3c 2f  declare_vtab()</
59c0: 61 3e 20 41 50 49 20 68 61 73 20 74 68 65 20 66  a> API has the f
59d0: 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 74 6f 74 79  ollowing prototy
59e0: 70 65 3a 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65  pe:..<blockquote
59f0: 3e 3c 70 72 65 3e 0a 20 20 20 20 69 6e 74 20 73  ><pre>.    int s
5a00: 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76  qlite3_declare_v
5a10: 74 61 62 28 73 71 6c 69 74 65 33 20 2a 64 62 2c  tab(sqlite3 *db,
5a20: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 72   const char *zCr
5a30: 65 61 74 65 54 61 62 6c 65 29 0a 3c 2f 70 72 65  eateTable).</pre
5a40: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a  ></blockquote>..
5a50: 3c 70 3e 54 68 65 20 66 69 72 73 74 20 61 72 67  <p>The first arg
5a60: 75 6d 65 6e 74 20 74 6f 20 3c 61 20 68 72 65 66  ument to <a href
5a70: 3d 22 63 33 72 65 66 2f 64 65 63 6c 61 72 65 5f  ="c3ref/declare_
5a80: 76 74 61 62 2e 68 74 6d 6c 22 3e 73 71 6c 69 74  vtab.html">sqlit
5a90: 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28  e3_declare_vtab(
5aa0: 29 3c 2f 61 3e 20 6d 75 73 74 20 62 65 20 74 68  )</a> must be th
5ab0: 65 20 73 61 6d 65 20 0a 3c 61 20 68 72 65 66 3d  e same .<a href=
5ac0: 22 63 33 72 65 66 2f 73 71 6c 69 74 65 33 2e 68  "c3ref/sqlite3.h
5ad0: 74 6d 6c 22 3e 64 61 74 61 62 61 73 65 20 63 6f  tml">database co
5ae0: 6e 6e 65 63 74 69 6f 6e 3c 2f 61 3e 20 70 6f 69  nnection</a> poi
5af0: 6e 74 65 72 20 61 73 20 74 68 65 20 66 69 72 73  nter as the firs
5b00: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
5b10: 68 69 73 20 6d 65 74 68 6f 64 2e 0a 54 68 65 20  his method..The 
5b20: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
5b30: 74 6f 20 3c 61 20 68 72 65 66 3d 22 63 33 72 65  to <a href="c3re
5b40: 66 2f 64 65 63 6c 61 72 65 5f 76 74 61 62 2e 68  f/declare_vtab.h
5b50: 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 64 65 63  tml">sqlite3_dec
5b60: 6c 61 72 65 5f 76 74 61 62 28 29 3c 2f 61 3e 20  lare_vtab()</a> 
5b70: 6d 75 73 74 20 61 20 7a 65 72 6f 2d 74 65 72 6d  must a zero-term
5b80: 69 6e 61 74 65 64 20 0a 55 54 46 2d 38 20 73 74  inated .UTF-8 st
5b90: 72 69 6e 67 20 74 68 61 74 20 63 6f 6e 74 61 69  ring that contai
5ba0: 6e 73 20 61 20 77 65 6c 6c 2d 66 6f 72 6d 65 64  ns a well-formed
5bb0: 20 3c 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f 63   <a href="lang_c
5bc0: 72 65 61 74 65 74 61 62 6c 65 2e 68 74 6d 6c 22  reatetable.html"
5bd0: 3e 43 52 45 41 54 45 20 54 41 42 4c 45 3c 2f 61  >CREATE TABLE</a
5be0: 3e 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  > statement that
5bf0: 20 0a 64 65 66 69 6e 65 73 20 74 68 65 20 63 6f   .defines the co
5c00: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 76 69 72  lumns in the vir
5c10: 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 74  tual table and t
5c20: 68 65 69 72 20 64 61 74 61 20 74 79 70 65 73 2e  heir data types.
5c30: 20 0a 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   .The name of th
5c40: 65 20 74 61 62 6c 65 20 69 6e 20 74 68 69 73 20  e table in this 
5c50: 43 52 45 41 54 45 20 54 41 42 4c 45 20 73 74 61  CREATE TABLE sta
5c60: 74 65 6d 65 6e 74 20 69 73 20 69 67 6e 6f 72 65  tement is ignore
5c70: 64 2c 20 0a 61 73 20 61 72 65 20 61 6c 6c 20 63  d, .as are all c
5c80: 6f 6e 73 74 72 61 69 6e 74 73 2e 20 4f 6e 6c 79  onstraints. Only
5c90: 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65   the column name
5ca0: 73 20 61 6e 64 20 64 61 74 61 74 79 70 65 73 20  s and datatypes 
5cb0: 6d 61 74 74 65 72 2e 0a 54 68 65 20 43 52 45 41  matter..The CREA
5cc0: 54 45 20 54 41 42 4c 45 20 73 74 61 74 65 6d 65  TE TABLE stateme
5cd0: 6e 74 20 73 74 72 69 6e 67 20 6e 65 65 64 20 6e  nt string need n
5ce0: 6f 74 20 74 6f 20 62 65 20 0a 68 65 6c 64 20 69  ot to be .held i
5cf0: 6e 20 70 65 72 73 69 73 74 65 6e 74 20 6d 65 6d  n persistent mem
5d00: 6f 72 79 2e 20 20 54 68 65 20 73 74 72 69 6e 67  ory.  The string
5d10: 20 63 61 6e 20 62 65 0a 64 65 61 6c 6c 6f 63 61   can be.dealloca
5d20: 74 65 64 20 61 6e 64 2f 6f 72 20 72 65 75 73 65  ted and/or reuse
5d30: 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65  d as soon as the
5d40: 20 3c 61 20 68 72 65 66 3d 22 63 33 72 65 66 2f   <a href="c3ref/
5d50: 64 65 63 6c 61 72 65 5f 76 74 61 62 2e 68 74 6d  declare_vtab.htm
5d60: 6c 22 3e 73 71 6c 69 74 65 33 5f 64 65 63 6c 61  l">sqlite3_decla
5d70: 72 65 5f 76 74 61 62 28 29 3c 2f 61 3e 0a 72 6f  re_vtab()</a>.ro
5d80: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 0a  utine returns...
5d90: 3c 70 3e 54 68 65 20 78 43 72 65 61 74 65 20 6d  <p>The xCreate m
5da0: 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 69  ethod need not i
5db0: 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 70 4d  nitialize the pM
5dc0: 6f 64 75 6c 65 2c 20 6e 52 65 66 2c 20 61 6e 64  odule, nRef, and
5dd0: 20 7a 45 72 72 4d 73 67 0a 66 69 65 6c 64 73 20   zErrMsg.fields 
5de0: 6f 66 20 74 68 65 20 3c 61 20 68 72 65 66 3d 22  of the <a href="
5df0: 63 33 72 65 66 2f 76 74 61 62 2e 68 74 6d 6c 22  c3ref/vtab.html"
5e00: 3e 73 71 6c 69 74 65 33 5f 76 74 61 62 3c 2f 61  >sqlite3_vtab</a
5e10: 3e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53  > object.  The S
5e20: 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20  QLite core will 
5e30: 74 61 6b 65 20 63 61 72 65 20 6f 66 20 0a 74 68  take care of .th
5e40: 61 74 20 63 68 6f 72 65 2e 0a 0a 3c 70 3e 54 68  at chore...<p>Th
5e50: 65 20 78 43 72 65 61 74 65 20 73 68 6f 75 6c 64  e xCreate should
5e60: 20 72 65 74 75 72 6e 20 3c 61 20 68 72 65 66 3d   return <a href=
5e70: 22 72 65 73 63 6f 64 65 2e 68 74 6d 6c 23 6f 6b  "rescode.html#ok
5e80: 22 3e 53 51 4c 49 54 45 5f 4f 4b 3c 2f 61 3e 20  ">SQLITE_OK</a> 
5e90: 69 66 20 69 74 20 69 73 20 73 75 63 63 65 73 73  if it is success
5ea0: 66 75 6c 20 69 6e 20 0a 63 72 65 61 74 69 6e 67  ful in .creating
5eb0: 20 74 68 65 20 6e 65 77 20 76 69 72 74 75 61 6c   the new virtual
5ec0: 20 74 61 62 6c 65 2c 20 6f 72 20 3c 61 20 68 72   table, or <a hr
5ed0: 65 66 3d 22 72 65 73 63 6f 64 65 2e 68 74 6d 6c  ef="rescode.html
5ee0: 23 65 72 72 6f 72 22 3e 53 51 4c 49 54 45 5f 45  #error">SQLITE_E
5ef0: 52 52 4f 52 3c 2f 61 3e 20 69 66 20 69 74 20 69  RROR</a> if it i
5f00: 73 20 6e 6f 74 20 73 75 63 63 65 73 73 66 75 6c  s not successful
5f10: 2e 0a 49 66 20 6e 6f 74 20 73 75 63 63 65 73 73  ..If not success
5f20: 66 75 6c 2c 20 74 68 65 20 3c 61 20 68 72 65 66  ful, the <a href
5f30: 3d 22 63 33 72 65 66 2f 76 74 61 62 2e 68 74 6d  ="c3ref/vtab.htm
5f40: 6c 22 3e 73 71 6c 69 74 65 33 5f 76 74 61 62 3c  l">sqlite3_vtab<
5f50: 2f 61 3e 20 73 74 72 75 63 74 75 72 65 20 6d 75  /a> structure mu
5f60: 73 74 20 6e 6f 74 20 62 65 20 61 6c 6c 6f 63 61  st not be alloca
5f70: 74 65 64 2e 20 0a 41 6e 20 65 72 72 6f 72 20 6d  ted. .An error m
5f80: 65 73 73 61 67 65 20 6d 61 79 20 6f 70 74 69 6f  essage may optio
5f90: 6e 61 6c 6c 79 20 62 65 20 72 65 74 75 72 6e 65  nally be returne
5fa0: 64 20 69 6e 20 2a 70 7a 45 72 72 20 69 66 20 75  d in *pzErr if u
5fb0: 6e 73 75 63 63 65 73 73 66 75 6c 2e 0a 53 70 61  nsuccessful..Spa
5fc0: 63 65 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ce to hold the e
5fd0: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
5fe0: 69 6e 67 20 6d 75 73 74 20 62 65 20 61 6c 6c 6f  ing must be allo
5ff0: 63 61 74 65 64 20 75 73 69 6e 67 0a 61 6e 20 53  cated using.an S
6000: 51 4c 69 74 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  QLite memory all
6010: 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  ocation function
6020: 20 6c 69 6b 65 20 0a 3c 61 20 68 72 65 66 3d 22   like .<a href="
6030: 63 33 72 65 66 2f 66 72 65 65 2e 68 74 6d 6c 22  c3ref/free.html"
6040: 3e 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  >sqlite3_malloc(
6050: 29 3c 2f 61 3e 20 6f 72 20 3c 61 20 68 72 65 66  )</a> or <a href
6060: 3d 22 63 33 72 65 66 2f 6d 70 72 69 6e 74 66 2e  ="c3ref/mprintf.
6070: 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 6d 70  html">sqlite3_mp
6080: 72 69 6e 74 66 28 29 3c 2f 61 3e 20 61 73 20 74  rintf()</a> as t
6090: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77  he SQLite core w
60a0: 69 6c 6c 0a 61 74 74 65 6d 70 74 20 74 6f 20 66  ill.attempt to f
60b0: 72 65 65 20 74 68 65 20 73 70 61 63 65 20 75 73  ree the space us
60c0: 69 6e 67 20 3c 61 20 68 72 65 66 3d 22 63 33 72  ing <a href="c3r
60d0: 65 66 2f 66 72 65 65 2e 68 74 6d 6c 22 3e 73 71  ef/free.html">sq
60e0: 6c 69 74 65 33 5f 66 72 65 65 28 29 3c 2f 61 3e  lite3_free()</a>
60f0: 20 61 66 74 65 72 20 74 68 65 20 65 72 72 6f 72   after the error
6100: 20 68 61 73 0a 62 65 65 6e 20 72 65 70 6f 72 74   has.been report
6110: 65 64 20 75 70 20 74 6f 20 74 68 65 20 61 70 70  ed up to the app
6120: 6c 69 63 61 74 69 6f 6e 2e 0a 0a 3c 70 3e 0a 49  lication...<p>.I
6130: 66 20 74 68 65 20 78 43 72 65 61 74 65 20 6d 65  f the xCreate me
6140: 74 68 6f 64 20 69 73 20 6f 6d 69 74 74 65 64 20  thod is omitted 
6150: 28 6c 65 66 74 20 61 73 20 61 20 4e 55 4c 4c 20  (left as a NULL 
6160: 70 6f 69 6e 74 65 72 29 20 74 68 65 6e 20 74 68  pointer) then th
6170: 65 0a 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  e.virtual table 
6180: 69 73 20 61 6e 20 3c 61 20 68 72 65 66 3d 22 76  is an <a href="v
6190: 74 61 62 2e 68 74 6d 6c 23 65 70 6f 6f 6e 6c 79  tab.html#epoonly
61a0: 76 74 61 62 22 3e 65 70 6f 6e 79 6d 6f 75 73 2d  vtab">eponymous-
61b0: 6f 6e 6c 79 20 76 69 72 74 75 61 6c 20 74 61 62  only virtual tab
61c0: 6c 65 3c 2f 61 3e 2e 20 20 4e 65 77 20 69 6e 73  le</a>.  New ins
61d0: 74 61 6e 63 65 73 20 6f 66 0a 74 68 65 20 76 69  tances of.the vi
61e0: 72 74 75 61 6c 20 74 61 62 6c 65 20 63 61 6e 6e  rtual table cann
61f0: 6f 74 20 62 65 20 63 72 65 61 74 65 64 20 75 73  ot be created us
6200: 69 6e 67 20 3c 61 20 68 72 65 66 3d 22 6c 61 6e  ing <a href="lan
6210: 67 5f 63 72 65 61 74 65 76 74 61 62 2e 68 74 6d  g_createvtab.htm
6220: 6c 22 3e 43 52 45 41 54 45 20 56 49 52 54 55 41  l">CREATE VIRTUA
6230: 4c 20 54 41 42 4c 45 3c 2f 61 3e 20 61 6e 64 20  L TABLE</a> and 
6240: 74 68 65 0a 76 69 72 74 75 61 6c 20 74 61 62 6c  the.virtual tabl
6250: 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73  e can only be us
6260: 65 64 20 76 69 61 20 69 74 73 20 6d 6f 64 75 6c  ed via its modul
6270: 65 20 6e 61 6d 65 2e 0a 4e 6f 74 65 20 74 68 61  e name..Note tha
6280: 74 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  t SQLite version
6290: 73 20 70 72 69 6f 72 20 74 6f 20 33 2e 39 2e 30  s prior to 3.9.0
62a0: 20 64 6f 20 6e 6f 74 20 75 6e 64 65 72 73 74 61   do not understa
62b0: 6e 64 0a 65 70 6f 6e 79 6d 6f 75 73 2d 6f 6e 6c  nd.eponymous-onl
62c0: 79 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73  y virtual tables
62d0: 20 61 6e 64 20 77 69 6c 6c 20 73 65 67 66 61 75   and will segfau
62e0: 6c 74 20 69 66 20 61 6e 20 61 74 74 65 6d 70 74  lt if an attempt
62f0: 20 69 73 20 6d 61 64 65 0a 74 6f 20 3c 61 20 68   is made.to <a h
6300: 72 65 66 3d 22 6c 61 6e 67 5f 63 72 65 61 74 65  ref="lang_create
6310: 76 74 61 62 2e 68 74 6d 6c 22 3e 43 52 45 41 54  vtab.html">CREAT
6320: 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 3c  E VIRTUAL TABLE<
6330: 2f 61 3e 20 6f 6e 20 61 6e 20 65 70 6f 6e 79 6d  /a> on an eponym
6340: 6f 75 73 2d 6f 6e 6c 79 20 76 69 72 74 75 61 6c  ous-only virtual
6350: 20 74 61 62 6c 65 20 62 65 63 61 75 73 65 0a 74   table because.t
6360: 68 65 20 78 43 72 65 61 74 65 20 6d 65 74 68 6f  he xCreate metho
6370: 64 20 77 61 73 20 6e 6f 74 20 63 68 65 63 6b 65  d was not checke
6380: 64 20 66 6f 72 20 6e 75 6c 6c 2e 0a 0a 3c 70 3e  d for null...<p>
6390: 0a 49 66 20 74 68 65 20 78 43 72 65 61 74 65 20  .If the xCreate 
63a0: 6d 65 74 68 6f 64 20 69 73 20 74 68 65 20 65 78  method is the ex
63b0: 61 63 74 20 73 61 6d 65 20 70 6f 69 6e 74 65 72  act same pointer
63c0: 20 61 73 20 74 68 65 20 3c 61 20 68 72 65 66 3d   as the <a href=
63d0: 22 76 74 61 62 2e 68 74 6d 6c 23 78 63 6f 6e 6e  "vtab.html#xconn
63e0: 65 63 74 22 3e 78 43 6f 6e 6e 65 63 74 3c 2f 61  ect">xConnect</a
63f0: 3e 20 6d 65 74 68 6f 64 2c 0a 74 68 61 74 20 69  > method,.that i
6400: 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68  ndicates that th
6410: 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  e virtual table 
6420: 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
6430: 20 69 6e 69 74 69 61 6c 69 7a 65 20 62 61 63 6b   initialize back
6440: 69 6e 67 0a 73 74 6f 72 65 2e 20 20 53 75 63 68  ing.store.  Such
6450: 20 61 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65   a virtual table
6460: 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20   can be used as 
6470: 61 6e 20 3c 61 20 68 72 65 66 3d 22 76 74 61 62  an <a href="vtab
6480: 2e 68 74 6d 6c 23 65 70 6f 76 74 61 62 22 3e 65  .html#epovtab">e
6490: 70 6f 6e 79 6d 6f 75 73 20 76 69 72 74 75 61 6c  ponymous virtual
64a0: 20 74 61 62 6c 65 3c 2f 61 3e 0a 6f 72 20 61 73   table</a>.or as
64b0: 20 61 20 6e 61 6d 65 64 20 76 69 72 74 75 61 6c   a named virtual
64c0: 20 74 61 62 6c 65 20 75 73 69 6e 67 20 3c 61 20   table using <a 
64d0: 68 72 65 66 3d 22 6c 61 6e 67 5f 63 72 65 61 74  href="lang_creat
64e0: 65 76 74 61 62 2e 68 74 6d 6c 22 3e 43 52 45 41  evtab.html">CREA
64f0: 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45  TE VIRTUAL TABLE
6500: 3c 2f 61 3e 20 6f 72 20 62 6f 74 68 2e 0a 0a 3c  </a> or both...<
6510: 61 20 6e 61 6d 65 3d 22 68 69 64 64 65 6e 63 6f  a name="hiddenco
6520: 6c 22 3e 3c 2f 61 3e 0a 0a 3c 68 34 3e 32 2e 31  l"></a>..<h4>2.1
6530: 2e 31 20 48 69 64 64 65 6e 20 63 6f 6c 75 6d 6e  .1 Hidden column
6540: 73 20 69 6e 20 76 69 72 74 75 61 6c 20 74 61 62  s in virtual tab
6550: 6c 65 73 3c 2f 68 34 3e 0a 3c 70 3e 49 66 20 61  les</h4>.<p>If a
6560: 20 63 6f 6c 75 6d 6e 20 64 61 74 61 74 79 70 65   column datatype
6570: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 73 70   contains the sp
6580: 65 63 69 61 6c 20 6b 65 79 77 6f 72 64 20 22 48  ecial keyword "H
6590: 49 44 44 45 4e 22 0a 28 69 6e 20 61 6e 79 20 63  IDDEN".(in any c
65a0: 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20 75 70  ombination of up
65b0: 70 65 72 20 61 6e 64 20 6c 6f 77 65 72 20 63 61  per and lower ca
65c0: 73 65 20 6c 65 74 74 65 72 73 29 20 74 68 65 6e  se letters) then
65d0: 20 74 68 61 74 20 6b 65 79 77 6f 72 64 0a 69 74   that keyword.it
65e0: 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
65f0: 20 74 68 65 20 63 6f 6c 75 6d 6e 20 64 61 74 61   the column data
6600: 74 79 70 65 20 6e 61 6d 65 20 61 6e 64 20 74 68  type name and th
6610: 65 20 63 6f 6c 75 6d 6e 20 69 73 20 6d 61 72 6b  e column is mark
6620: 65 64 20 0a 61 73 20 61 20 68 69 64 64 65 6e 20  ed .as a hidden 
6630: 63 6f 6c 75 6d 6e 20 69 6e 74 65 72 6e 61 6c 6c  column internall
6640: 79 2e 20 0a 41 20 68 69 64 64 65 6e 20 63 6f 6c  y. .A hidden col
6650: 75 6d 6e 20 64 69 66 66 65 72 73 20 66 72 6f 6d  umn differs from
6660: 20 61 20 6e 6f 72 6d 61 6c 20 63 6f 6c 75 6d 6e   a normal column
6670: 20 69 6e 20 74 68 72 65 65 20 72 65 73 70 65 63   in three respec
6680: 74 73 3a 0a 0a 3c 70 3e 0a 3c 75 6c 3e 0a 3c 6c  ts:..<p>.<ul>.<l
6690: 69 3e 20 48 69 64 64 65 6e 20 63 6f 6c 75 6d 6e  i> Hidden column
66a0: 73 20 61 72 65 20 6e 6f 74 20 6c 69 73 74 65 64  s are not listed
66b0: 20 69 6e 20 74 68 65 20 64 61 74 61 73 65 74 20   in the dataset 
66c0: 72 65 74 75 72 6e 65 64 20 62 79 20 0a 20 20 20  returned by .   
66d0: 20 20 22 3c 61 20 68 72 65 66 3d 22 70 72 61 67    "<a href="prag
66e0: 6d 61 2e 68 74 6d 6c 23 70 72 61 67 6d 61 5f 74  ma.html#pragma_t
66f0: 61 62 6c 65 5f 69 6e 66 6f 22 3e 50 52 41 47 4d  able_info">PRAGM
6700: 41 20 74 61 62 6c 65 5f 69 6e 66 6f 3c 2f 61 3e  A table_info</a>
6710: 22 2c 0a 3c 6c 69 3e 20 48 69 64 64 65 6e 20 63  ",.<li> Hidden c
6720: 6f 6c 75 6d 6e 73 20 61 72 65 20 6e 6f 74 20 69  olumns are not i
6730: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 65  ncluded in the e
6740: 78 70 61 6e 73 69 6f 6e 20 6f 66 20 61 20 22 2a  xpansion of a "*
6750: 22 0a 20 20 20 20 20 65 78 70 72 65 73 73 69 6f  ".     expressio
6760: 6e 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  n in the result 
6770: 73 65 74 20 6f 66 20 61 20 3c 61 20 68 72 65 66  set of a <a href
6780: 3d 22 6c 61 6e 67 5f 73 65 6c 65 63 74 2e 68 74  ="lang_select.ht
6790: 6d 6c 22 3e 53 45 4c 45 43 54 3c 2f 61 3e 2c 20  ml">SELECT</a>, 
67a0: 61 6e 64 0a 3c 6c 69 3e 20 48 69 64 64 65 6e 20  and.<li> Hidden 
67b0: 63 6f 6c 75 6d 6e 73 20 61 72 65 20 6e 6f 74 20  columns are not 
67c0: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20  included in the 
67d0: 69 6d 70 6c 69 63 69 74 20 63 6f 6c 75 6d 6e 2d  implicit column-
67e0: 6c 69 73 74 20 0a 20 20 20 20 20 75 73 65 64 20  list .     used 
67f0: 62 79 20 61 6e 20 3c 61 20 68 72 65 66 3d 22 6c  by an <a href="l
6800: 61 6e 67 5f 69 6e 73 65 72 74 2e 68 74 6d 6c 22  ang_insert.html"
6810: 3e 49 4e 53 45 52 54 3c 2f 61 3e 20 73 74 61 74  >INSERT</a> stat
6820: 65 6d 65 6e 74 20 74 68 61 74 20 6c 61 63 6b 73  ement that lacks
6830: 20 61 6e 20 65 78 70 6c 69 63 69 74 20 63 6f 6c   an explicit col
6840: 75 6d 6e 2d 6c 69 73 74 2e 20 0a 3c 2f 75 6c 3e  umn-list. .</ul>
6850: 0a 0a 3c 70 3e 46 6f 72 20 65 78 61 6d 70 6c 65  ..<p>For example
6860: 2c 20 69 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  , if the followi
6870: 6e 67 20 53 51 4c 20 69 73 20 70 61 73 73 65 64  ng SQL is passed
6880: 20 74 6f 20 3c 61 20 68 72 65 66 3d 22 63 33 72   to <a href="c3r
6890: 65 66 2f 64 65 63 6c 61 72 65 5f 76 74 61 62 2e  ef/declare_vtab.
68a0: 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 64 65  html">sqlite3_de
68b0: 63 6c 61 72 65 5f 76 74 61 62 28 29 3c 2f 61 3e  clare_vtab()</a>
68c0: 3a 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  :..<blockquote><
68d0: 70 72 65 3e 0a 20 20 20 43 52 45 41 54 45 20 54  pre>.   CREATE T
68e0: 41 42 4c 45 20 78 28 61 20 48 49 44 44 45 4e 20  ABLE x(a HIDDEN 
68f0: 56 41 52 43 48 41 52 28 31 32 29 2c 20 62 20 49  VARCHAR(12), b I
6900: 4e 54 45 47 45 52 2c 20 63 20 49 4e 54 45 47 45  NTEGER, c INTEGE
6910: 52 20 48 69 64 64 65 6e 29 3b 0a 3c 2f 70 72 65  R Hidden);.</pre
6920: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a  ></blockquote>..
6930: 3c 70 3e 54 68 65 6e 20 74 68 65 20 76 69 72 74  <p>Then the virt
6940: 75 61 6c 20 74 61 62 6c 65 20 77 6f 75 6c 64 20  ual table would 
6950: 62 65 20 63 72 65 61 74 65 64 20 77 69 74 68 20  be created with 
6960: 74 77 6f 20 68 69 64 64 65 6e 20 63 6f 6c 75 6d  two hidden colum
6970: 6e 73 2c 0a 61 6e 64 20 77 69 74 68 20 64 61 74  ns,.and with dat
6980: 61 74 79 70 65 73 20 6f 66 20 22 56 41 52 43 48  atypes of "VARCH
6990: 41 52 28 31 32 29 22 20 61 6e 64 20 22 49 4e 54  AR(12)" and "INT
69a0: 45 47 45 52 22 2e 0a 0a 3c 70 3e 41 6e 20 65 78  EGER"...<p>An ex
69b0: 61 6d 70 6c 65 20 75 73 65 20 6f 66 20 68 69 64  ample use of hid
69c0: 64 65 6e 20 63 6f 6c 75 6d 6e 73 20 63 61 6e 20  den columns can 
69d0: 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20 3c  be seen in the <
69e0: 61 20 68 72 65 66 3d 22 66 74 73 33 2e 68 74 6d  a href="fts3.htm
69f0: 6c 22 3e 46 54 53 33 3c 2f 61 3e 20 76 69 72 74  l">FTS3</a> virt
6a00: 75 61 6c 20 0a 74 61 62 6c 65 20 69 6d 70 6c 65  ual .table imple
6a10: 6d 65 6e 74 61 74 69 6f 6e 2c 20 77 68 65 72 65  mentation, where
6a20: 20 65 76 65 72 79 20 46 54 53 20 76 69 72 74 75   every FTS virtu
6a30: 61 6c 20 74 61 62 6c 65 0a 63 6f 6e 74 61 69 6e  al table.contain
6a40: 73 20 61 6e 20 3c 61 20 68 72 65 66 3d 22 66 74  s an <a href="ft
6a50: 73 33 2e 68 74 6d 6c 23 68 69 64 64 65 6e 63 6f  s3.html#hiddenco
6a60: 6c 22 3e 46 54 53 20 68 69 64 64 65 6e 20 63 6f  l">FTS hidden co
6a70: 6c 75 6d 6e 3c 2f 61 3e 20 74 68 61 74 20 69 73  lumn</a> that is
6a80: 20 75 73 65 64 20 74 6f 20 70 61 73 73 20 69 6e   used to pass in
6a90: 66 6f 72 6d 61 74 69 6f 6e 20 66 72 6f 6d 20 74  formation from t
6aa0: 68 65 0a 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he.virtual table
6ab0: 20 69 6e 74 6f 20 3c 61 20 68 72 65 66 3d 22 66   into <a href="f
6ac0: 74 73 33 2e 68 74 6d 6c 23 73 6e 69 70 70 65 74  ts3.html#snippet
6ad0: 22 3e 46 54 53 20 61 75 78 69 6c 69 61 72 79 20  ">FTS auxiliary 
6ae0: 66 75 6e 63 74 69 6f 6e 73 3c 2f 61 3e 20 61 6e  functions</a> an
6af0: 64 20 74 6f 20 74 68 65 20 3c 61 20 68 72 65 66  d to the <a href
6b00: 3d 22 66 74 73 33 2e 68 74 6d 6c 23 73 65 63 74  ="fts3.html#sect
6b10: 69 6f 6e 5f 33 22 3e 46 54 53 20 4d 41 54 43 48  ion_3">FTS MATCH
6b20: 3c 2f 61 3e 20 6f 70 65 72 61 74 6f 72 2e 0a 0a  </a> operator...
6b30: 3c 61 20 6e 61 6d 65 3d 22 74 61 62 66 75 6e 63  <a name="tabfunc
6b40: 32 22 3e 3c 2f 61 3e 0a 0a 3c 68 34 3e 32 2e 31  2"></a>..<h4>2.1
6b50: 2e 32 20 54 61 62 6c 65 2d 76 61 6c 75 65 64 20  .2 Table-valued 
6b60: 66 75 6e 63 74 69 6f 6e 73 3c 2f 68 34 3e 0a 0a  functions</h4>..
6b70: 3c 70 3e 41 20 3c 61 20 68 72 65 66 3d 22 76 74  <p>A <a href="vt
6b80: 61 62 2e 68 74 6d 6c 22 3e 76 69 72 74 75 61 6c  ab.html">virtual
6b90: 20 74 61 62 6c 65 3c 2f 61 3e 20 74 68 61 74 20   table</a> that 
6ba0: 63 6f 6e 74 61 69 6e 73 20 3c 61 20 68 72 65 66  contains <a href
6bb0: 3d 22 76 74 61 62 2e 68 74 6d 6c 23 68 69 64 64  ="vtab.html#hidd
6bc0: 65 6e 63 6f 6c 22 3e 68 69 64 64 65 6e 20 63 6f  encol">hidden co
6bd0: 6c 75 6d 6e 73 3c 2f 61 3e 20 63 61 6e 20 62 65  lumns</a> can be
6be0: 20 75 73 65 64 20 6c 69 6b 65 0a 61 20 74 61 62   used like.a tab
6bf0: 6c 65 2d 76 61 6c 75 65 64 20 66 75 6e 63 74 69  le-valued functi
6c00: 6f 6e 20 69 6e 20 74 68 65 20 46 52 4f 4d 20 63  on in the FROM c
6c10: 6c 61 75 73 65 20 6f 66 20 61 20 3c 61 20 68 72  lause of a <a hr
6c20: 65 66 3d 22 6c 61 6e 67 5f 73 65 6c 65 63 74 2e  ef="lang_select.
6c30: 68 74 6d 6c 22 3e 53 45 4c 45 43 54 3c 2f 61 3e  html">SELECT</a>
6c40: 20 73 74 61 74 65 6d 65 6e 74 2e 0a 54 68 65 20   statement..The 
6c50: 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65  arguments to the
6c60: 20 74 61 62 6c 65 2d 76 61 6c 75 65 64 20 66 75   table-valued fu
6c70: 6e 63 74 69 6f 6e 20 62 65 63 6f 6d 65 20 63 6f  nction become co
6c80: 6e 73 74 72 61 69 6e 74 73 20 6f 6e 20 0a 74 68  nstraints on .th
6c90: 65 20 48 49 44 44 45 4e 20 63 6f 6c 75 6d 6e 73  e HIDDEN columns
6ca0: 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 20   of the virtual 
6cb0: 74 61 62 6c 65 2e 0a 0a 3c 70 3e 46 6f 72 20 65  table...<p>For e
6cc0: 78 61 6d 70 6c 65 2c 20 74 68 65 20 22 67 65 6e  xample, the "gen
6cd0: 65 72 61 74 65 5f 73 65 72 69 65 73 22 20 65 78  erate_series" ex
6ce0: 74 65 6e 73 69 6f 6e 20 28 6c 6f 63 61 74 65 64  tension (located
6cf0: 20 69 6e 20 74 68 65 0a 3c 61 20 68 72 65 66 3d   in the.<a href=
6d00: 22 68 74 74 70 3a 2f 2f 77 77 77 2e 73 71 6c 69  "http://www.sqli
6d10: 74 65 2e 6f 72 67 2f 73 72 63 2f 61 72 74 69 66  te.org/src/artif
6d20: 61 63 74 3f 63 69 3d 74 72 75 6e 6b 26 66 69 6c  act?ci=trunk&fil
6d30: 65 6e 61 6d 65 3d 65 78 74 2f 6d 69 73 63 2f 73  ename=ext/misc/s
6d40: 65 72 69 65 73 2e 63 22 3e 65 78 74 2f 6d 69 73  eries.c">ext/mis
6d50: 63 2f 73 65 72 69 65 73 2e 63 3c 2f 61 3e 0a 66  c/series.c</a>.f
6d60: 69 6c 65 20 69 6e 20 74 68 65 20 3c 61 20 68 72  ile in the <a hr
6d70: 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 73  ef="http://www.s
6d80: 71 6c 69 74 65 2e 6f 72 67 2f 73 72 63 2f 74 72  qlite.org/src/tr
6d90: 65 65 3f 63 69 3d 74 72 75 6e 6b 22 3e 73 6f 75  ee?ci=trunk">sou
6da0: 72 63 65 20 74 72 65 65 3c 2f 61 3e 29 0a 69 6d  rce tree</a>).im
6db0: 70 6c 65 6d 65 6e 74 73 20 61 6e 20 3c 61 20 68  plements an <a h
6dc0: 72 65 66 3d 22 76 74 61 62 2e 68 74 6d 6c 23 65  ref="vtab.html#e
6dd0: 70 6f 76 74 61 62 22 3e 65 70 6f 6e 79 6d 6f 75  povtab">eponymou
6de0: 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 3c  s virtual table<
6df0: 2f 61 3e 20 77 69 74 68 20 74 68 65 20 66 6f 6c  /a> with the fol
6e00: 6c 6f 77 69 6e 67 20 73 63 68 65 6d 61 3a 0a 0a  lowing schema:..
6e10: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
6e20: 3e 0a 43 52 45 41 54 45 20 54 41 42 4c 45 20 67  >.CREATE TABLE g
6e30: 65 6e 65 72 61 74 65 5f 73 65 72 69 65 73 28 0a  enerate_series(.
6e40: 20 20 76 61 6c 75 65 2c 0a 20 20 73 74 61 72 74    value,.  start
6e50: 20 48 49 44 44 45 4e 2c 0a 20 20 73 74 6f 70 20   HIDDEN,.  stop 
6e60: 48 49 44 44 45 4e 2c 0a 20 20 73 74 65 70 20 48  HIDDEN,.  step H
6e70: 49 44 44 45 4e 0a 29 3b 0a 3c 2f 70 72 65 3e 3c  IDDEN.);.</pre><
6e80: 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70  /blockquote>..<p
6e90: 3e 54 68 65 20 3c 61 20 68 72 65 66 3d 22 76 74  >The <a href="vt
6ea0: 61 62 2e 68 74 6d 6c 23 78 62 65 73 74 69 6e 64  ab.html#xbestind
6eb0: 65 78 22 3e 73 71 6c 69 74 65 33 5f 6d 6f 64 75  ex">sqlite3_modu
6ec0: 6c 65 2e 78 42 65 73 74 49 6e 64 65 78 3c 2f 61  le.xBestIndex</a
6ed0: 3e 20 6d 65 74 68 6f 64 20 69 6e 20 74 68 65 20  > method in the 
6ee0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
6ef0: 66 20 74 68 69 73 0a 74 61 62 6c 65 20 63 68 65  f this.table che
6f00: 63 6b 73 20 66 6f 72 20 65 71 75 61 6c 69 74 79  cks for equality
6f10: 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 67 61   constraints aga
6f20: 69 6e 73 74 20 74 68 65 20 48 49 44 44 45 4e 20  inst the HIDDEN 
6f30: 63 6f 6c 75 6d 6e 73 2c 20 61 6e 64 20 75 73 65  columns, and use
6f40: 73 0a 74 68 6f 73 65 20 61 73 20 69 6e 70 75 74  s.those as input
6f50: 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 64   parameters to d
6f60: 65 74 65 72 6d 69 6e 65 20 74 68 65 20 72 61 6e  etermine the ran
6f70: 67 65 20 6f 66 20 69 6e 74 65 67 65 72 20 22 76  ge of integer "v
6f80: 61 6c 75 65 22 20 6f 75 74 70 75 74 73 0a 74 6f  alue" outputs.to
6f90: 20 67 65 6e 65 72 61 74 65 2e 20 20 52 65 61 73   generate.  Reas
6fa0: 6f 6e 61 62 6c 65 20 64 65 66 61 75 6c 74 73 20  onable defaults 
6fb0: 61 72 65 20 75 73 65 64 20 66 6f 72 20 61 6e 79  are used for any
6fc0: 20 75 6e 63 6f 6e 73 74 72 61 69 6e 65 64 20 63   unconstrained c
6fd0: 6f 6c 75 6d 6e 73 2e 0a 46 6f 72 20 65 78 61 6d  olumns..For exam
6fe0: 70 6c 65 2c 20 74 6f 20 6c 69 73 74 20 61 6c 6c  ple, to list all
6ff0: 20 69 6e 74 65 67 65 72 73 20 62 65 74 77 65 65   integers betwee
7000: 6e 20 35 20 61 6e 64 20 35 30 3a 0a 0a 3c 62 6c  n 5 and 50:..<bl
7010: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 53  ockquote><pre>.S
7020: 45 4c 45 43 54 20 76 61 6c 75 65 20 46 52 4f 4d  ELECT value FROM
7030: 20 67 65 6e 65 72 61 74 65 5f 73 65 72 69 65 73   generate_series
7040: 28 35 2c 35 30 29 3b 0a 3c 2f 70 72 65 3e 3c 2f  (5,50);.</pre></
7050: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e  blockquote>..<p>
7060: 54 68 65 20 70 72 65 76 69 6f 75 73 20 71 75 65  The previous que
7070: 72 79 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  ry is equivalent
7080: 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   to the followin
7090: 67 3a 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  g:..<blockquote>
70a0: 3c 70 72 65 3e 0a 53 45 4c 45 43 54 20 76 61 6c  <pre>.SELECT val
70b0: 75 65 20 46 52 4f 4d 20 67 65 6e 65 72 61 74 65  ue FROM generate
70c0: 5f 73 65 72 69 65 73 20 57 48 45 52 45 20 73 74  _series WHERE st
70d0: 61 72 74 3d 35 20 41 4e 44 20 73 74 6f 70 3d 35  art=5 AND stop=5
70e0: 30 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  0;.</pre></block
70f0: 71 75 6f 74 65 3e 0a 0a 3c 70 3e 41 72 67 75 6d  quote>..<p>Argum
7100: 65 6e 74 73 20 6f 6e 20 74 68 65 20 76 69 72 74  ents on the virt
7110: 75 61 6c 20 74 61 62 6c 65 20 6e 61 6d 65 20 61  ual table name a
7120: 72 65 20 6d 61 74 63 68 65 64 20 74 6f 20 3c 61  re matched to <a
7130: 20 68 72 65 66 3d 22 76 74 61 62 2e 68 74 6d 6c   href="vtab.html
7140: 23 68 69 64 64 65 6e 63 6f 6c 22 3e 68 69 64 64  #hiddencol">hidd
7150: 65 6e 20 63 6f 6c 75 6d 6e 73 3c 2f 61 3e 0a 69  en columns</a>.i
7160: 6e 20 6f 72 64 65 72 2e 20 20 54 68 65 20 6e 75  n order.  The nu
7170: 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
7180: 73 20 63 61 6e 20 62 65 20 6c 65 73 73 20 74 68  s can be less th
7190: 61 6e 20 74 68 65 0a 6e 75 6d 62 65 72 20 6f 66  an the.number of
71a0: 20 68 69 64 64 65 6e 20 63 6f 6c 75 6d 6e 73 2c   hidden columns,
71b0: 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74   in which case t
71c0: 68 65 20 6c 61 74 74 65 72 20 68 69 64 64 65 6e  he latter hidden
71d0: 20 63 6f 6c 75 6d 6e 73 20 61 72 65 0a 75 6e 63   columns are.unc
71e0: 6f 6e 73 74 72 61 69 6e 65 64 2e 20 20 48 6f 77  onstrained.  How
71f0: 65 76 65 72 2c 20 61 6e 20 65 72 72 6f 72 20 72  ever, an error r
7200: 65 73 75 6c 74 73 20 69 66 20 74 68 65 72 65 20  esults if there 
7210: 61 72 65 20 6d 6f 72 65 20 61 72 67 75 6d 65 6e  are more argumen
7220: 74 73 0a 74 68 61 6e 20 74 68 65 72 65 20 61 72  ts.than there ar
7230: 65 20 68 69 64 64 65 6e 20 63 6f 6c 75 6d 6e 73  e hidden columns
7240: 20 69 6e 20 74 68 65 20 76 69 72 74 75 61 6c 20   in the virtual 
7250: 74 61 62 6c 65 2e 0a 0a 0a 3c 61 20 6e 61 6d 65  table....<a name
7260: 3d 22 78 63 6f 6e 6e 65 63 74 22 3e 3c 2f 61 3e  ="xconnect"></a>
7270: 0a 0a 3c 68 33 3e 32 2e 32 20 54 68 65 20 78 43  ..<h3>2.2 The xC
7280: 6f 6e 6e 65 63 74 20 4d 65 74 68 6f 64 3c 2f 68  onnect Method</h
7290: 33 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  3>..<blockquote>
72a0: 3c 70 72 65 3e 0a 20 20 69 6e 74 20 28 2a 78 43  <pre>.  int (*xC
72b0: 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 2a  onnect)(sqlite3*
72c0: 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20  , void *pAux,.  
72d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
72e0: 20 61 72 67 63 2c 20 63 68 61 72 20 2a 2a 61 72   argc, char **ar
72f0: 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  gv,.            
7300: 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20     sqlite3_vtab 
7310: 2a 2a 70 70 56 54 61 62 2c 0a 20 20 20 20 20 20  **ppVTab,.      
7320: 20 20 20 20 20 20 20 20 20 63 68 61 72 20 2a 2a           char **
7330: 70 7a 45 72 72 29 3b 0a 3c 2f 70 72 65 3e 3c 2f  pzErr);.</pre></
7340: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e  blockquote>..<p>
7350: 54 68 65 20 78 43 6f 6e 6e 65 63 74 20 6d 65 74  The xConnect met
7360: 68 6f 64 20 69 73 20 76 65 72 79 20 73 69 6d 69  hod is very simi
7370: 6c 61 72 20 74 6f 20 3c 61 20 68 72 65 66 3d 22  lar to <a href="
7380: 76 74 61 62 2e 68 74 6d 6c 23 78 63 72 65 61 74  vtab.html#xcreat
7390: 65 22 3e 78 43 72 65 61 74 65 3c 2f 61 3e 2e 20  e">xCreate</a>. 
73a0: 0a 49 74 20 68 61 73 20 74 68 65 20 73 61 6d 65  .It has the same
73b0: 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20   parameters and 
73c0: 63 6f 6e 73 74 72 75 63 74 73 20 61 20 6e 65 77  constructs a new
73d0: 20 3c 61 20 68 72 65 66 3d 22 63 33 72 65 66 2f   <a href="c3ref/
73e0: 76 74 61 62 2e 68 74 6d 6c 22 3e 73 71 6c 69 74  vtab.html">sqlit
73f0: 65 33 5f 76 74 61 62 3c 2f 61 3e 20 73 74 72 75  e3_vtab</a> stru
7400: 63 74 75 72 65 20 0a 6a 75 73 74 20 6c 69 6b 65  cture .just like
7410: 20 78 43 72 65 61 74 65 2e 20 0a 41 6e 64 20 69   xCreate. .And i
7420: 74 20 6d 75 73 74 20 61 6c 73 6f 20 63 61 6c 6c  t must also call
7430: 20 3c 61 20 68 72 65 66 3d 22 63 33 72 65 66 2f   <a href="c3ref/
7440: 64 65 63 6c 61 72 65 5f 76 74 61 62 2e 68 74 6d  declare_vtab.htm
7450: 6c 22 3e 73 71 6c 69 74 65 33 5f 64 65 63 6c 61  l">sqlite3_decla
7460: 72 65 5f 76 74 61 62 28 29 3c 2f 61 3e 20 6c 69  re_vtab()</a> li
7470: 6b 65 20 78 43 72 65 61 74 65 2e 0a 0a 3c 70 3e  ke xCreate...<p>
7480: 54 68 65 20 64 69 66 66 65 72 65 6e 63 65 20 69  The difference i
7490: 73 20 74 68 61 74 20 78 43 6f 6e 6e 65 63 74 20  s that xConnect 
74a0: 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 65 73 74  is called to est
74b0: 61 62 6c 69 73 68 20 61 20 6e 65 77 20 0a 63 6f  ablish a new .co
74c0: 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 61 6e 20 65  nnection to an e
74d0: 78 69 73 74 69 6e 67 20 76 69 72 74 75 61 6c 20  xisting virtual 
74e0: 74 61 62 6c 65 20 77 68 65 72 65 61 73 20 78 43  table whereas xC
74f0: 72 65 61 74 65 20 69 73 20 63 61 6c 6c 65 64 20  reate is called 
7500: 0a 74 6f 20 63 72 65 61 74 65 20 61 20 6e 65 77  .to create a new
7510: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 66   virtual table f
7520: 72 6f 6d 20 73 63 72 61 74 63 68 2e 0a 0a 3c 70  rom scratch...<p
7530: 3e 54 68 65 20 78 43 72 65 61 74 65 20 61 6e 64  >The xCreate and
7540: 20 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64   xConnect method
7550: 73 20 61 72 65 20 6f 6e 6c 79 20 64 69 66 66 65  s are only diffe
7560: 72 65 6e 74 20 77 68 65 6e 20 74 68 65 0a 76 69  rent when the.vi
7570: 72 74 75 61 6c 20 74 61 62 6c 65 20 68 61 73 20  rtual table has 
7580: 73 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 62 61 63  some kind of bac
7590: 6b 69 6e 67 20 73 74 6f 72 65 20 74 68 61 74 20  king store that 
75a0: 6d 75 73 74 20 62 65 20 69 6e 69 74 69 61 6c 69  must be initiali
75b0: 7a 65 64 20 0a 74 68 65 20 66 69 72 73 74 20 74  zed .the first t
75c0: 69 6d 65 20 74 68 65 20 76 69 72 74 75 61 6c 20  ime the virtual 
75d0: 74 61 62 6c 65 20 69 73 20 63 72 65 61 74 65 64  table is created
75e0: 2e 20 54 68 65 20 78 43 72 65 61 74 65 20 6d 65  . The xCreate me
75f0: 74 68 6f 64 20 63 72 65 61 74 65 73 20 0a 61 6e  thod creates .an
7600: 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68  d initializes th
7610: 65 20 62 61 63 6b 69 6e 67 20 73 74 6f 72 65 2e  e backing store.
7620: 20 54 68 65 20 78 43 6f 6e 6e 65 63 74 20 6d 65   The xConnect me
7630: 74 68 6f 64 20 6a 75 73 74 20 63 6f 6e 6e 65 63  thod just connec
7640: 74 73 20 0a 74 6f 20 61 6e 20 65 78 69 73 74 69  ts .to an existi
7650: 6e 67 20 62 61 63 6b 69 6e 67 20 73 74 6f 72 65  ng backing store
7660: 2e 20 20 57 68 65 6e 20 78 43 72 65 61 74 65 20  .  When xCreate 
7670: 61 6e 64 20 78 43 6f 6e 6e 65 63 74 20 61 72 65  and xConnect are
7680: 20 74 68 65 20 73 61 6d 65 2c 0a 74 68 65 20 74   the same,.the t
7690: 61 62 6c 65 20 69 73 20 61 6e 20 3c 61 20 68 72  able is an <a hr
76a0: 65 66 3d 22 76 74 61 62 2e 68 74 6d 6c 23 65 70  ef="vtab.html#ep
76b0: 6f 76 74 61 62 22 3e 65 70 6f 6e 79 6d 6f 75 73  ovtab">eponymous
76c0: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 3c 2f   virtual table</
76d0: 61 3e 2e 0a 0a 3c 70 3e 41 73 20 61 6e 20 65 78  a>...<p>As an ex
76e0: 61 6d 70 6c 65 2c 20 63 6f 6e 73 69 64 65 72 20  ample, consider 
76f0: 61 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  a virtual table 
7700: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74  implementation t
7710: 68 61 74 20 0a 70 72 6f 76 69 64 65 73 20 72 65  hat .provides re
7720: 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 20 74  ad-only access t
7730: 6f 20 65 78 69 73 74 69 6e 67 20 63 6f 6d 6d 61  o existing comma
7740: 2d 73 65 70 61 72 61 74 65 64 2d 76 61 6c 75 65  -separated-value
7750: 20 28 43 53 56 29 0a 66 69 6c 65 73 20 6f 6e 20   (CSV).files on 
7760: 64 69 73 6b 2e 20 54 68 65 72 65 20 69 73 20 6e  disk. There is n
7770: 6f 20 62 61 63 6b 69 6e 67 20 73 74 6f 72 65 20  o backing store 
7780: 74 68 61 74 20 6e 65 65 64 73 20 74 6f 20 62 65  that needs to be
7790: 20 63 72 65 61 74 65 64 20 0a 6f 72 20 69 6e 69   created .or ini
77a0: 74 69 61 6c 69 7a 65 64 20 66 6f 72 20 73 75 63  tialized for suc
77b0: 68 20 61 20 76 69 72 74 75 61 6c 20 74 61 62 6c  h a virtual tabl
77c0: 65 20 28 73 69 6e 63 65 20 74 68 65 20 43 53 56  e (since the CSV
77d0: 20 66 69 6c 65 73 20 61 6c 72 65 61 64 79 20 0a   files already .
77e0: 65 78 69 73 74 20 6f 6e 20 64 69 73 6b 29 20 73  exist on disk) s
77f0: 6f 20 74 68 65 20 78 43 72 65 61 74 65 20 61 6e  o the xCreate an
7800: 64 20 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68 6f  d xConnect metho
7810: 64 73 20 77 69 6c 6c 20 62 65 20 69 64 65 6e 74  ds will be ident
7820: 69 63 61 6c 20 0a 66 6f 72 20 74 68 61 74 20 6d  ical .for that m
7830: 6f 64 75 6c 65 2e 0a 0a 3c 70 3e 41 6e 6f 74 68  odule...<p>Anoth
7840: 65 72 20 65 78 61 6d 70 6c 65 20 69 73 20 61 20  er example is a 
7850: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 74 68  virtual table th
7860: 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 61 20  at implements a 
7870: 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64 65 78 2e  full-text index.
7880: 20 0a 54 68 65 20 78 43 72 65 61 74 65 20 6d 65   .The xCreate me
7890: 74 68 6f 64 20 6d 75 73 74 20 63 72 65 61 74 65  thod must create
78a0: 20 61 6e 64 20 69 6e 69 74 69 61 6c 69 7a 65 20   and initialize 
78b0: 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
78c0: 74 6f 20 68 6f 6c 64 20 0a 74 68 65 20 64 69 63  to hold .the dic
78d0: 74 69 6f 6e 61 72 79 20 61 6e 64 20 70 6f 73 74  tionary and post
78e0: 69 6e 67 20 6c 69 73 74 73 20 66 6f 72 20 74 68  ing lists for th
78f0: 61 74 20 69 6e 64 65 78 2e 20 54 68 65 20 78 43  at index. The xC
7900: 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64 2c 0a 6f  onnect method,.o
7910: 6e 20 74 68 65 20 6f 74 68 65 72 20 68 61 6e 64  n the other hand
7920: 2c 20 6f 6e 6c 79 20 68 61 73 20 74 6f 20 6c 6f  , only has to lo
7930: 63 61 74 65 20 61 6e 64 20 75 73 65 20 61 6e 20  cate and use an 
7940: 65 78 69 73 74 69 6e 67 20 64 69 63 74 69 6f 6e  existing diction
7950: 61 72 79 20 0a 61 6e 64 20 70 6f 73 74 69 6e 67  ary .and posting
7960: 20 6c 69 73 74 73 20 74 68 61 74 20 77 65 72 65   lists that were
7970: 20 63 72 65 61 74 65 64 20 62 79 20 61 20 70 72   created by a pr
7980: 69 6f 72 20 78 43 72 65 61 74 65 20 63 61 6c 6c  ior xCreate call
7990: 2e 0a 0a 3c 70 3e 54 68 65 20 78 43 6f 6e 6e 65  ...<p>The xConne
79a0: 63 74 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 72  ct method must r
79b0: 65 74 75 72 6e 20 3c 61 20 68 72 65 66 3d 22 72  eturn <a href="r
79c0: 65 73 63 6f 64 65 2e 68 74 6d 6c 23 6f 6b 22 3e  escode.html#ok">
79d0: 53 51 4c 49 54 45 5f 4f 4b 3c 2f 61 3e 20 69 66  SQLITE_OK</a> if
79e0: 20 69 74 20 69 73 20 73 75 63 63 65 73 73 66 75   it is successfu
79f0: 6c 20 0a 69 6e 20 63 72 65 61 74 69 6e 67 20 74  l .in creating t
7a00: 68 65 20 6e 65 77 20 76 69 72 74 75 61 6c 20 74  he new virtual t
7a10: 61 62 6c 65 2c 20 6f 72 20 3c 61 20 68 72 65 66  able, or <a href
7a20: 3d 22 72 65 73 63 6f 64 65 2e 68 74 6d 6c 23 65  ="rescode.html#e
7a30: 72 72 6f 72 22 3e 53 51 4c 49 54 45 5f 45 52 52  rror">SQLITE_ERR
7a40: 4f 52 3c 2f 61 3e 20 69 66 20 69 74 20 69 73 20  OR</a> if it is 
7a50: 6e 6f 74 20 0a 73 75 63 63 65 73 73 66 75 6c 2e  not .successful.
7a60: 20 49 66 20 6e 6f 74 20 73 75 63 63 65 73 73 66   If not successf
7a70: 75 6c 2c 20 74 68 65 20 3c 61 20 68 72 65 66 3d  ul, the <a href=
7a80: 22 63 33 72 65 66 2f 76 74 61 62 2e 68 74 6d 6c  "c3ref/vtab.html
7a90: 22 3e 73 71 6c 69 74 65 33 5f 76 74 61 62 3c 2f  ">sqlite3_vtab</
7aa0: 61 3e 20 73 74 72 75 63 74 75 72 65 20 6d 75 73  a> structure mus
7ab0: 74 20 6e 6f 74 20 62 65 20 0a 61 6c 6c 6f 63 61  t not be .alloca
7ac0: 74 65 64 2e 20 41 6e 20 65 72 72 6f 72 20 6d 65  ted. An error me
7ad0: 73 73 61 67 65 20 6d 61 79 20 6f 70 74 69 6f 6e  ssage may option
7ae0: 61 6c 6c 79 20 62 65 20 72 65 74 75 72 6e 65 64  ally be returned
7af0: 20 69 6e 20 2a 70 7a 45 72 72 20 69 66 20 0a 75   in *pzErr if .u
7b00: 6e 73 75 63 63 65 73 73 66 75 6c 2e 20 0a 53 70  nsuccessful. .Sp
7b10: 61 63 65 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ace to hold the 
7b20: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
7b30: 72 69 6e 67 20 6d 75 73 74 20 62 65 20 61 6c 6c  ring must be all
7b40: 6f 63 61 74 65 64 20 75 73 69 6e 67 0a 61 6e 20  ocated using.an 
7b50: 53 51 4c 69 74 65 20 6d 65 6d 6f 72 79 20 61 6c  SQLite memory al
7b60: 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  location functio
7b70: 6e 20 6c 69 6b 65 20 0a 3c 61 20 68 72 65 66 3d  n like .<a href=
7b80: 22 63 33 72 65 66 2f 66 72 65 65 2e 68 74 6d 6c  "c3ref/free.html
7b90: 22 3e 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  ">sqlite3_malloc
7ba0: 28 29 3c 2f 61 3e 20 6f 72 20 3c 61 20 68 72 65  ()</a> or <a hre
7bb0: 66 3d 22 63 33 72 65 66 2f 6d 70 72 69 6e 74 66  f="c3ref/mprintf
7bc0: 2e 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 6d  .html">sqlite3_m
7bd0: 70 72 69 6e 74 66 28 29 3c 2f 61 3e 20 61 73 20  printf()</a> as 
7be0: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  the SQLite core 
7bf0: 77 69 6c 6c 0a 61 74 74 65 6d 70 74 20 74 6f 20  will.attempt to 
7c00: 66 72 65 65 20 74 68 65 20 73 70 61 63 65 20 75  free the space u
7c10: 73 69 6e 67 20 3c 61 20 68 72 65 66 3d 22 63 33  sing <a href="c3
7c20: 72 65 66 2f 66 72 65 65 2e 68 74 6d 6c 22 3e 73  ref/free.html">s
7c30: 71 6c 69 74 65 33 5f 66 72 65 65 28 29 3c 2f 61  qlite3_free()</a
7c40: 3e 20 61 66 74 65 72 20 74 68 65 20 65 72 72 6f  > after the erro
7c50: 72 20 68 61 73 0a 62 65 65 6e 20 72 65 70 6f 72  r has.been repor
7c60: 74 65 64 20 75 70 20 74 6f 20 74 68 65 20 61 70  ted up to the ap
7c70: 70 6c 69 63 61 74 69 6f 6e 2e 0a 0a 3c 70 3e 54  plication...<p>T
7c80: 68 65 20 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68  he xConnect meth
7c90: 6f 64 20 69 73 20 72 65 71 75 69 72 65 64 20 66  od is required f
7ca0: 6f 72 20 65 76 65 72 79 20 76 69 72 74 75 61 6c  or every virtual
7cb0: 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74   table implement
7cc0: 61 74 69 6f 6e 2c 20 0a 74 68 6f 75 67 68 20 74  ation, .though t
7cd0: 68 65 20 3c 61 20 68 72 65 66 3d 22 76 74 61 62  he <a href="vtab
7ce0: 2e 68 74 6d 6c 23 78 63 72 65 61 74 65 22 3e 78  .html#xcreate">x
7cf0: 43 72 65 61 74 65 3c 2f 61 3e 20 61 6e 64 20 78  Create</a> and x
7d00: 43 6f 6e 6e 65 63 74 20 70 6f 69 6e 74 65 72 73  Connect pointers
7d10: 20 6f 66 20 74 68 65 20 3c 61 20 68 72 65 66 3d   of the <a href=
7d20: 22 63 33 72 65 66 2f 6d 6f 64 75 6c 65 2e 68 74  "c3ref/module.ht
7d30: 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 6d 6f 64 75  ml">sqlite3_modu
7d40: 6c 65 3c 2f 61 3e 20 6f 62 6a 65 63 74 0a 6d 61  le</a> object.ma
7d50: 79 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 73  y point to the s
7d60: 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 69 66 20  ame function if 
7d70: 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
7d80: 65 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  e does not need 
7d90: 74 6f 0a 69 6e 69 74 69 61 6c 69 7a 65 20 62 61  to.initialize ba
7da0: 63 6b 69 6e 67 20 73 74 6f 72 65 2e 0a 0a 3c 61  cking store...<a
7db0: 20 6e 61 6d 65 3d 22 78 62 65 73 74 69 6e 64 65   name="xbestinde
7dc0: 78 22 3e 3c 2f 61 3e 0a 0a 3c 68 33 3e 32 2e 33  x"></a>..<h3>2.3
7dd0: 20 54 68 65 20 78 42 65 73 74 49 6e 64 65 78 20   The xBestIndex 
7de0: 4d 65 74 68 6f 64 3c 2f 68 33 3e 0a 0a 3c 70 3e  Method</h3>..<p>
7df0: 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
7e00: 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f  xBestIndex metho
7e10: 64 20 6f 66 20 61 20 76 69 72 74 75 61 6c 20 74  d of a virtual t
7e20: 61 62 6c 65 20 6d 6f 64 75 6c 65 20 74 6f 20 64  able module to d
7e30: 65 74 65 72 6d 69 6e 65 0a 74 68 65 20 62 65 73  etermine.the bes
7e40: 74 20 77 61 79 20 74 6f 20 61 63 63 65 73 73 20  t way to access 
7e50: 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
7e60: 65 2e 20 0a 54 68 65 20 78 42 65 73 74 49 6e 64  e. .The xBestInd
7e70: 65 78 20 6d 65 74 68 6f 64 20 68 61 73 20 61 20  ex method has a 
7e80: 70 72 6f 74 6f 74 79 70 65 20 6c 69 6b 65 20 74  prototype like t
7e90: 68 69 73 3a 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74  his:..<blockquot
7ea0: 65 3e 3c 70 72 65 3e 0a 20 20 69 6e 74 20 28 2a  e><pre>.  int (*
7eb0: 78 42 65 73 74 49 6e 64 65 78 29 28 73 71 6c 69  xBestIndex)(sqli
7ec0: 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c  te3_vtab *pVTab,
7ed0: 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
7ee0: 6e 66 6f 2a 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 62  nfo*);.</pre></b
7ef0: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54  lockquote>..<p>T
7f00: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 63  he SQLite core c
7f10: 6f 6d 6d 75 6e 69 63 61 74 65 73 20 77 69 74 68  ommunicates with
7f20: 20 74 68 65 20 78 42 65 73 74 49 6e 64 65 78 20   the xBestIndex 
7f30: 6d 65 74 68 6f 64 20 62 79 20 66 69 6c 6c 69 6e  method by fillin
7f40: 67 20 0a 69 6e 20 63 65 72 74 61 69 6e 20 66 69  g .in certain fi
7f50: 65 6c 64 73 20 6f 66 20 74 68 65 20 3c 61 20 68  elds of the <a h
7f60: 72 65 66 3d 22 63 33 72 65 66 2f 69 6e 64 65 78  ref="c3ref/index
7f70: 5f 69 6e 66 6f 2e 68 74 6d 6c 22 3e 73 71 6c 69  _info.html">sqli
7f80: 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3c 2f  te3_index_info</
7f90: 61 3e 20 73 74 72 75 63 74 75 72 65 20 61 6e 64  a> structure and
7fa0: 20 70 61 73 73 69 6e 67 20 61 20 0a 70 6f 69 6e   passing a .poin
7fb0: 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 75  ter to that stru
7fc0: 63 74 75 72 65 20 69 6e 74 6f 20 78 42 65 73 74  cture into xBest
7fd0: 49 6e 64 65 78 20 61 73 20 74 68 65 20 73 65 63  Index as the sec
7fe0: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 0a  ond parameter. .
7ff0: 54 68 65 20 78 42 65 73 74 49 6e 64 65 78 20 6d  The xBestIndex m
8000: 65 74 68 6f 64 20 66 69 6c 6c 73 20 6f 75 74 20  ethod fills out 
8010: 6f 74 68 65 72 20 66 69 65 6c 64 73 20 6f 66 20  other fields of 
8020: 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 77  this structure w
8030: 68 69 63 68 0a 66 6f 72 6d 73 20 74 68 65 20 72  hich.forms the r
8040: 65 70 6c 79 2e 20 54 68 65 20 3c 61 20 68 72 65  eply. The <a hre
8050: 66 3d 22 63 33 72 65 66 2f 69 6e 64 65 78 5f 69  f="c3ref/index_i
8060: 6e 66 6f 2e 68 74 6d 6c 22 3e 73 71 6c 69 74 65  nfo.html">sqlite
8070: 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3c 2f 61 3e  3_index_info</a>
8080: 20 73 74 72 75 63 74 75 72 65 20 6c 6f 6f 6b 73   structure looks
8090: 20 6c 69 6b 65 20 74 68 69 73 3a 0a 0a 3c 62 6c   like this:..<bl
80a0: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 20  ockquote><pre>. 
80b0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
80c0: 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a 20 20 20  index_info {.   
80d0: 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a 20 20   /* Inputs */.  
80e0: 20 20 63 6f 6e 73 74 20 69 6e 74 20 6e 43 6f 6e    const int nCon
80f0: 73 74 72 61 69 6e 74 3b 20 20 20 20 20 2f 2a 20  straint;     /* 
8100: 4e 75 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65  Number of entrie
8110: 73 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74  s in aConstraint
8120: 20 2a 2f 0a 20 20 20 20 63 6f 6e 73 74 20 73 74   */.    const st
8130: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
8140: 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a  ex_constraint {.
8150: 20 20 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75         int iColu
8160: 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  mn;             
8170: 20 2f 2a 20 43 6f 6c 75 6d 6e 20 63 6f 6e 73 74   /* Column const
8180: 72 61 69 6e 65 64 2e 20 20 2d 31 20 66 6f 72 20  rained.  -1 for 
8190: 52 4f 57 49 44 20 2a 2f 0a 20 20 20 20 20 20 20  ROWID */.       
81a0: 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70  unsigned char op
81b0: 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e  ;         /* Con
81c0: 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72  straint operator
81d0: 20 2a 2f 0a 20 20 20 20 20 20 20 75 6e 73 69 67   */.       unsig
81e0: 6e 65 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b  ned char usable;
81f0: 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20       /* True if 
8200: 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20  this constraint 
8210: 69 73 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20  is usable */.   
8220: 20 20 20 20 69 6e 74 20 69 54 65 72 6d 4f 66 66      int iTermOff
8230: 73 65 74 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  set;          /*
8240: 20 55 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   Used internally
8250: 20 2d 20 78 42 65 73 74 49 6e 64 65 78 20 73 68   - xBestIndex sh
8260: 6f 75 6c 64 20 69 67 6e 6f 72 65 20 2a 2f 0a 20  ould ignore */. 
8270: 20 20 20 7d 20 2a 63 6f 6e 73 74 20 61 43 6f 6e     } *const aCon
8280: 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 2f 2a  straint;      /*
8290: 20 54 61 62 6c 65 20 6f 66 20 57 48 45 52 45 20   Table of WHERE 
82a0: 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e  clause constrain
82b0: 74 73 20 2a 2f 0a 20 20 20 20 63 6f 6e 73 74 20  ts */.    const 
82c0: 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20  int nOrderBy;   
82d0: 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
82e0: 66 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20 4f  f terms in the O
82f0: 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a  RDER BY clause *
8300: 2f 0a 20 20 20 20 63 6f 6e 73 74 20 73 74 72 75  /.    const stru
8310: 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
8320: 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20  _orderby {.     
8330: 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20    int iColumn;  
8340: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
8350: 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a  olumn number */.
8360: 20 20 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20         unsigned 
8370: 63 68 61 72 20 64 65 73 63 3b 20 20 20 20 20 20  char desc;      
8380: 20 2f 2a 20 54 72 75 65 20 66 6f 72 20 44 45 53   /* True for DES
8390: 43 2e 20 20 46 61 6c 73 65 20 66 6f 72 20 41 53  C.  False for AS
83a0: 43 2e 20 2a 2f 0a 20 20 20 20 7d 20 2a 63 6f 6e  C. */.    } *con
83b0: 73 74 20 61 4f 72 64 65 72 42 79 3b 20 20 20 20  st aOrderBy;    
83c0: 20 20 20 20 20 2f 2a 20 54 68 65 20 4f 52 44 45       /* The ORDE
83d0: 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 0a  R BY clause */..
83e0: 20 20 20 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a      /* Outputs *
83f0: 2f 0a 20 20 20 20 73 74 72 75 63 74 20 73 71 6c  /.    struct sql
8400: 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74  ite3_index_const
8410: 72 61 69 6e 74 5f 75 73 61 67 65 20 7b 0a 20 20  raint_usage {.  
8420: 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e 64 65      int argvInde
8430: 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  x;           /* 
8440: 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69 6e  if >0, constrain
8450: 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 72 67  t is part of arg
8460: 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f 0a  v to xFilter */.
8470: 20 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63        unsigned c
8480: 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f  har omit;      /
8490: 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20  * Do not code a 
84a0: 74 65 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f  test for this co
84b0: 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20  nstraint */.    
84c0: 7d 20 2a 63 6f 6e 73 74 20 61 43 6f 6e 73 74 72  } *const aConstr
84d0: 61 69 6e 74 55 73 61 67 65 3b 0a 20 20 20 20 69  aintUsage;.    i
84e0: 6e 74 20 69 64 78 4e 75 6d 3b 20 20 20 20 20 20  nt idxNum;      
84f0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
8500: 62 65 72 20 75 73 65 64 20 74 6f 20 69 64 65 6e  ber used to iden
8510: 74 69 66 79 20 74 68 65 20 69 6e 64 65 78 20 2a  tify the index *
8520: 2f 0a 20 20 20 20 63 68 61 72 20 2a 69 64 78 53  /.    char *idxS
8530: 74 72 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  tr;             
8540: 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f 73 73   /* String, poss
8550: 69 62 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  ibly obtained fr
8560: 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
8570: 63 20 2a 2f 0a 20 20 20 20 69 6e 74 20 6e 65 65  c */.    int nee
8580: 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b 20 20  dToFreeIdxStr;  
8590: 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64 78 53      /* Free idxS
85a0: 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33  tr using sqlite3
85b0: 5f 66 72 65 65 28 29 20 69 66 20 74 72 75 65 20  _free() if true 
85c0: 2a 2f 0a 20 20 20 20 69 6e 74 20 6f 72 64 65 72  */.    int order
85d0: 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20  ByConsumed;     
85e0: 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74    /* True if out
85f0: 70 75 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f  put is already o
8600: 72 64 65 72 65 64 20 2a 2f 0a 20 20 20 20 64 6f  rdered */.    do
8610: 75 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f  uble estimatedCo
8620: 73 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69  st;      /* Esti
8630: 6d 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73  mated cost of us
8640: 69 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a  ing this index *
8650: 2f 0a 20 20 20 20 3c 62 3e 2f 2a 20 46 69 65 6c  /.    <b>/* Fiel
8660: 64 73 20 62 65 6c 6f 77 20 61 72 65 20 6f 6e 6c  ds below are onl
8670: 79 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 53  y available in S
8680: 51 4c 69 74 65 20 33 2e 38 2e 32 20 61 6e 64 20  QLite 3.8.2 and 
8690: 6c 61 74 65 72 20 2a 2f 3c 2f 62 3e 0a 20 20 20  later */</b>.   
86a0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 65   sqlite3_int64 e
86b0: 73 74 69 6d 61 74 65 64 52 6f 77 73 3b 20 20 20  stimatedRows;   
86c0: 20 2f 2a 20 45 73 74 69 6d 61 74 65 64 20 6e 75   /* Estimated nu
86d0: 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 72 65 74  mber of rows ret
86e0: 75 72 6e 65 64 20 2a 2f 0a 20 20 20 20 3c 62 3e  urned */.    <b>
86f0: 2f 2a 20 46 69 65 6c 64 73 20 62 65 6c 6f 77 20  /* Fields below 
8700: 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62  are only availab
8710: 6c 65 20 69 6e 20 53 51 4c 69 74 65 20 33 2e 39  le in SQLite 3.9
8720: 2e 30 20 61 6e 64 20 6c 61 74 65 72 20 2a 2f 3c  .0 and later */<
8730: 2f 62 3e 0a 20 20 20 20 69 6e 74 20 69 64 78 46  /b>.    int idxF
8740: 6c 61 67 73 3b 20 20 20 20 20 20 20 20 20 20 20  lags;           
8750: 20 20 20 2f 2a 20 4d 61 73 6b 20 6f 66 20 53 51     /* Mask of SQ
8760: 4c 49 54 45 5f 49 4e 44 45 58 5f 53 43 41 4e 5f  LITE_INDEX_SCAN_
8770: 2a 20 66 6c 61 67 73 20 2a 2f 0a 20 20 20 20 3c  * flags */.    <
8780: 62 3e 2f 2a 20 46 69 65 6c 64 73 20 62 65 6c 6f  b>/* Fields belo
8790: 77 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c  w are only avail
87a0: 61 62 6c 65 20 69 6e 20 53 51 4c 69 74 65 20 33  able in SQLite 3
87b0: 2e 31 30 2e 30 20 61 6e 64 20 6c 61 74 65 72 20  .10.0 and later 
87c0: 2a 2f 3c 2f 62 3e 0a 20 20 20 20 73 71 6c 69 74  */</b>.    sqlit
87d0: 65 33 5f 75 69 6e 74 36 34 20 63 6f 6c 55 73 65  e3_uint64 colUse
87e0: 64 3b 20 20 20 20 2f 2a 20 49 6e 70 75 74 3a 20  d;    /* Input: 
87f0: 4d 61 73 6b 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  Mask of columns 
8800: 75 73 65 64 20 62 79 20 73 74 61 74 65 6d 65 6e  used by statemen
8810: 74 20 2a 2f 0a 20 20 7d 3b 0a 3c 2f 70 72 65 3e  t */.  };.</pre>
8820: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c  </blockquote>..<
8830: 70 3e 4e 6f 74 65 20 74 68 65 20 77 61 72 6e 69  p>Note the warni
8840: 6e 67 73 20 6f 6e 20 74 68 65 20 22 65 73 74 69  ngs on the "esti
8850: 6d 61 74 65 64 52 6f 77 73 22 2c 20 22 69 64 78  matedRows", "idx
8860: 46 6c 61 67 73 22 2c 20 61 6e 64 20 63 6f 6c 55  Flags", and colU
8870: 73 65 64 20 66 69 65 6c 64 73 2e 0a 54 68 65 73  sed fields..Thes
8880: 65 20 66 69 65 6c 64 73 20 77 65 72 65 20 61 64  e fields were ad
8890: 64 65 64 20 77 69 74 68 20 53 51 4c 69 74 65 20  ded with SQLite 
88a0: 76 65 72 73 69 6f 6e 73 20 33 2e 38 2e 32 2c 20  versions 3.8.2, 
88b0: 33 2e 39 2e 30 2c 20 61 6e 64 20 33 2e 31 30 2e  3.9.0, and 3.10.
88c0: 30 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  0, respectively.
88d0: 20 0a 41 6e 79 20 65 78 74 65 6e 73 69 6f 6e 20   .Any extension 
88e0: 74 68 61 74 20 72 65 61 64 73 20 6f 72 20 77 72  that reads or wr
88f0: 69 74 65 73 20 74 68 65 73 65 20 66 69 65 6c 64  ites these field
8900: 73 20 6d 75 73 74 20 66 69 72 73 74 20 63 68 65  s must first che
8910: 63 6b 20 74 68 61 74 20 74 68 65 20 0a 76 65 72  ck that the .ver
8920: 73 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69  sion of the SQLi
8930: 74 65 20 6c 69 62 72 61 72 79 20 69 6e 20 75 73  te library in us
8940: 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  e is greater tha
8950: 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 61 70  n or equal to ap
8960: 70 72 6f 70 72 69 61 74 65 0a 76 65 72 73 69 6f  propriate.versio
8970: 6e 20 2d 20 70 65 72 68 61 70 73 20 63 6f 6d 70  n - perhaps comp
8980: 61 72 69 6e 67 20 74 68 65 20 76 61 6c 75 65 20  aring the value 
8990: 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 3c 61  returned from <a
89a0: 20 68 72 65 66 3d 22 63 33 72 65 66 2f 6c 69 62   href="c3ref/lib
89b0: 76 65 72 73 69 6f 6e 2e 68 74 6d 6c 22 3e 73 71  version.html">sq
89c0: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
89d0: 5f 6e 75 6d 62 65 72 28 29 3c 2f 61 3e 0a 61 67  _number()</a>.ag
89e0: 61 69 6e 73 74 20 63 6f 6e 73 74 61 6e 74 73 20  ainst constants 
89f0: 33 30 30 38 30 30 32 2c 20 33 30 30 39 30 30 30  3008002, 3009000
8a00: 2c 20 61 6e 64 2f 6f 72 20 33 30 31 30 30 30 30  , and/or 3010000
8a10: 2e 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20  . The result of 
8a20: 61 74 74 65 6d 70 74 69 6e 67 20 0a 74 6f 20 61  attempting .to a
8a30: 63 63 65 73 73 20 74 68 65 73 65 20 66 69 65 6c  ccess these fiel
8a40: 64 73 20 69 6e 20 61 6e 20 73 71 6c 69 74 65 33  ds in an sqlite3
8a50: 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75  _index_info stru
8a60: 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79  cture created by
8a70: 20 61 6e 20 0a 6f 6c 64 65 72 20 76 65 72 73 69   an .older versi
8a80: 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 61 72 65  on of SQLite are
8a90: 20 75 6e 64 65 66 69 6e 65 64 2e 0a 0a 3c 70 3e   undefined...<p>
8aa0: 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65  In addition, the
8ab0: 72 65 20 61 72 65 20 73 6f 6d 65 20 64 65 66 69  re are some defi
8ac0: 6e 65 64 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 0a  ned constants:..
8ad0: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
8ae0: 3e 0a 20 20 23 64 65 66 69 6e 65 20 53 51 4c 49  >.  #define SQLI
8af0: 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
8b00: 49 4e 54 5f 45 51 20 20 20 20 20 20 32 0a 20 20  INT_EQ      2.  
8b10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
8b20: 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
8b30: 47 54 20 20 20 20 20 20 34 0a 20 20 23 64 65 66  GT      4.  #def
8b40: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
8b50: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20 20  _CONSTRAINT_LE  
8b60: 20 20 20 20 38 0a 20 20 23 64 65 66 69 6e 65 20      8.  #define 
8b70: 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
8b80: 53 54 52 41 49 4e 54 5f 4c 54 20 20 20 20 20 31  STRAINT_LT     1
8b90: 36 0a 20 20 23 64 65 66 69 6e 65 20 53 51 4c 49  6.  #define SQLI
8ba0: 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
8bb0: 49 4e 54 5f 47 45 20 20 20 20 20 33 32 0a 20 20  INT_GE     32.  
8bc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
8bd0: 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
8be0: 4d 41 54 43 48 20 20 36 34 0a 20 20 23 64 65 66  MATCH  64.  #def
8bf0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
8c00: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 49 4b 45  _CONSTRAINT_LIKE
8c10: 20 20 20 36 35 20 20 20 20 20 2f 2a 20 33 2e 31     65     /* 3.1
8c20: 30 2e 30 20 61 6e 64 20 6c 61 74 65 72 20 6f 6e  0.0 and later on
8c30: 6c 79 20 2a 2f 0a 20 20 23 64 65 66 69 6e 65 20  ly */.  #define 
8c40: 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
8c50: 53 54 52 41 49 4e 54 5f 47 4c 4f 42 20 20 20 36  STRAINT_GLOB   6
8c60: 36 20 20 20 20 20 2f 2a 20 33 2e 31 30 2e 30 20  6     /* 3.10.0 
8c70: 61 6e 64 20 6c 61 74 65 72 20 6f 6e 6c 79 20 2a  and later only *
8c80: 2f 0a 20 20 23 64 65 66 69 6e 65 20 53 51 4c 49  /.  #define SQLI
8c90: 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
8ca0: 49 4e 54 5f 52 45 47 45 58 50 20 36 37 20 20 20  INT_REGEXP 67   
8cb0: 20 20 2f 2a 20 33 2e 31 30 2e 30 20 61 6e 64 20    /* 3.10.0 and 
8cc0: 6c 61 74 65 72 20 6f 6e 6c 79 20 2a 2f 0a 20 20  later only */.  
8cd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
8ce0: 4e 44 45 58 5f 53 43 41 4e 5f 55 4e 49 51 55 45  NDEX_SCAN_UNIQUE
8cf0: 20 20 20 20 20 20 20 20 31 20 20 20 20 20 2f 2a          1     /*
8d00: 20 53 63 61 6e 20 76 69 73 69 74 73 20 61 74 20   Scan visits at 
8d10: 6d 6f 73 74 20 31 20 72 6f 77 20 2a 2f 0a 3c 2f  most 1 row */.</
8d20: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
8d30: 3e 0a 0a 3c 70 3e 54 68 65 20 53 51 4c 69 74 65  >..<p>The SQLite
8d40: 20 63 6f 72 65 20 63 61 6c 6c 73 20 74 68 65 20   core calls the 
8d50: 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f  xBestIndex metho
8d60: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d  d when it is com
8d70: 70 69 6c 69 6e 67 20 61 20 71 75 65 72 79 0a 74  piling a query.t
8d80: 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 61 20 76  hat involves a v
8d90: 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 49 6e  irtual table. In
8da0: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 53 51   other words, SQ
8db0: 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 69 73 20  Lite calls this 
8dc0: 6d 65 74 68 6f 64 20 0a 77 68 65 6e 20 69 74 20  method .when it 
8dd0: 69 73 20 72 75 6e 6e 69 6e 67 20 3c 61 20 68 72  is running <a hr
8de0: 65 66 3d 22 63 33 72 65 66 2f 70 72 65 70 61 72  ef="c3ref/prepar
8df0: 65 2e 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f  e.html">sqlite3_
8e00: 70 72 65 70 61 72 65 28 29 3c 2f 61 3e 20 6f 72  prepare()</a> or
8e10: 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 2e   the equivalent.
8e20: 20 0a 42 79 20 63 61 6c 6c 69 6e 67 20 74 68 69   .By calling thi
8e30: 73 20 6d 65 74 68 6f 64 2c 20 74 68 65 20 0a 53  s method, the .S
8e40: 51 4c 69 74 65 20 63 6f 72 65 20 69 73 20 73 61  QLite core is sa
8e50: 79 69 6e 67 20 74 6f 20 74 68 65 20 76 69 72 74  ying to the virt
8e60: 75 61 6c 20 74 61 62 6c 65 20 74 68 61 74 20 69  ual table that i
8e70: 74 20 6e 65 65 64 73 20 74 6f 20 61 63 63 65 73  t needs to acces
8e80: 73 20 0a 73 6f 6d 65 20 73 75 62 73 65 74 20 6f  s .some subset o
8e90: 66 20 74 68 65 20 72 6f 77 73 20 69 6e 20 74 68  f the rows in th
8ea0: 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  e virtual table 
8eb0: 61 6e 64 20 69 74 20 77 61 6e 74 73 20 74 6f 20  and it wants to 
8ec0: 6b 6e 6f 77 20 74 68 65 0a 6d 6f 73 74 20 65 66  know the.most ef
8ed0: 66 69 63 69 65 6e 74 20 77 61 79 20 74 6f 20 64  ficient way to d
8ee0: 6f 20 74 68 61 74 20 61 63 63 65 73 73 2e 20 54  o that access. T
8ef0: 68 65 20 78 42 65 73 74 49 6e 64 65 78 20 6d 65  he xBestIndex me
8f00: 74 68 6f 64 20 72 65 70 6c 69 65 73 20 0a 77 69  thod replies .wi
8f10: 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 74  th information t
8f20: 68 61 74 20 74 68 65 20 53 51 4c 69 74 65 20 63  hat the SQLite c
8f30: 6f 72 65 20 63 61 6e 20 74 68 65 6e 20 75 73 65  ore can then use
8f40: 20 74 6f 20 63 6f 6e 64 75 63 74 20 61 6e 20 0a   to conduct an .
8f50: 65 66 66 69 63 69 65 6e 74 20 73 65 61 72 63 68  efficient search
8f60: 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 20   of the virtual 
8f70: 74 61 62 6c 65 2e 0a 0a 3c 70 3e 57 68 69 6c 65  table...<p>While
8f80: 20 63 6f 6d 70 69 6c 69 6e 67 20 61 20 73 69 6e   compiling a sin
8f90: 67 6c 65 20 53 51 4c 20 71 75 65 72 79 2c 20 74  gle SQL query, t
8fa0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6d  he SQLite core m
8fb0: 69 67 68 74 20 63 61 6c 6c 20 0a 78 42 65 73 74  ight call .xBest
8fc0: 49 6e 64 65 78 20 6d 75 6c 74 69 70 6c 65 20 74  Index multiple t
8fd0: 69 6d 65 73 20 77 69 74 68 20 64 69 66 66 65 72  imes with differ
8fe0: 65 6e 74 20 73 65 74 74 69 6e 67 73 20 69 6e 20  ent settings in 
8ff0: 3c 61 20 68 72 65 66 3d 22 63 33 72 65 66 2f 69  <a href="c3ref/i
9000: 6e 64 65 78 5f 69 6e 66 6f 2e 68 74 6d 6c 22 3e  ndex_info.html">
9010: 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
9020: 66 6f 3c 2f 61 3e 2e 0a 54 68 65 20 53 51 4c 69  fo</a>..The SQLi
9030: 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 74 68 65  te core will the
9040: 6e 20 73 65 6c 65 63 74 20 74 68 65 20 63 6f 6d  n select the com
9050: 62 69 6e 61 74 69 6f 6e 20 74 68 61 74 20 61 70  bination that ap
9060: 70 65 61 72 73 20 74 6f 20 0a 67 69 76 65 20 74  pears to .give t
9070: 68 65 20 62 65 73 74 20 70 65 72 66 6f 72 6d 61  he best performa
9080: 6e 63 65 2e 0a 0a 3c 70 3e 42 65 66 6f 72 65 20  nce...<p>Before 
9090: 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 6d 65 74  calling this met
90a0: 68 6f 64 2c 20 74 68 65 20 53 51 4c 69 74 65 20  hod, the SQLite 
90b0: 63 6f 72 65 20 69 6e 69 74 69 61 6c 69 7a 65 73  core initializes
90c0: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 0a 6f 66   an instance .of
90d0: 20 74 68 65 20 3c 61 20 68 72 65 66 3d 22 63 33   the <a href="c3
90e0: 72 65 66 2f 69 6e 64 65 78 5f 69 6e 66 6f 2e 68  ref/index_info.h
90f0: 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 69 6e 64  tml">sqlite3_ind
9100: 65 78 5f 69 6e 66 6f 3c 2f 61 3e 20 73 74 72 75  ex_info</a> stru
9110: 63 74 75 72 65 20 77 69 74 68 20 69 6e 66 6f 72  cture with infor
9120: 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
9130: 0a 71 75 65 72 79 20 74 68 61 74 20 69 74 20 69  .query that it i
9140: 73 20 63 75 72 72 65 6e 74 6c 79 20 74 72 79 69  s currently tryi
9150: 6e 67 20 74 6f 20 70 72 6f 63 65 73 73 2e 20 54  ng to process. T
9160: 68 69 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  his information 
9170: 0a 64 65 72 69 76 65 73 20 6d 61 69 6e 6c 79 20  .derives mainly 
9180: 66 72 6f 6d 20 74 68 65 20 57 48 45 52 45 20 63  from the WHERE c
9190: 6c 61 75 73 65 20 61 6e 64 20 4f 52 44 45 52 20  lause and ORDER 
91a0: 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63  BY or GROUP BY c
91b0: 6c 61 75 73 65 73 20 0a 6f 66 20 74 68 65 20 71  lauses .of the q
91c0: 75 65 72 79 2c 20 62 75 74 20 61 6c 73 6f 20 66  uery, but also f
91d0: 72 6f 6d 20 61 6e 79 20 4f 4e 20 6f 72 20 55 53  rom any ON or US
91e0: 49 4e 47 20 63 6c 61 75 73 65 73 20 69 66 20 74  ING clauses if t
91f0: 68 65 20 71 75 65 72 79 20 69 73 20 61 20 0a 6a  he query is a .j
9200: 6f 69 6e 2e 20 54 68 65 20 69 6e 66 6f 72 6d 61  oin. The informa
9210: 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20 53 51  tion that the SQ
9220: 4c 69 74 65 20 63 6f 72 65 20 70 72 6f 76 69 64  Lite core provid
9230: 65 73 20 74 6f 20 74 68 65 20 78 42 65 73 74 49  es to the xBestI
9240: 6e 64 65 78 20 0a 6d 65 74 68 6f 64 20 69 73 20  ndex .method is 
9250: 68 65 6c 64 20 69 6e 20 74 68 65 20 70 61 72 74  held in the part
9260: 20 6f 66 20 74 68 65 20 73 74 72 75 63 74 75 72   of the structur
9270: 65 20 74 68 61 74 20 69 73 20 6d 61 72 6b 65 64  e that is marked
9280: 20 61 73 20 22 49 6e 70 75 74 73 22 2e 20 0a 54   as "Inputs". .T
9290: 68 65 20 22 4f 75 74 70 75 74 73 22 20 73 65 63  he "Outputs" sec
92a0: 74 69 6f 6e 20 69 73 20 69 6e 69 74 69 61 6c 69  tion is initiali
92b0: 7a 65 64 20 74 6f 20 7a 65 72 6f 2e 0a 0a 3c 70  zed to zero...<p
92c0: 3e 54 68 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  >The information
92d0: 20 69 6e 20 74 68 65 20 3c 61 20 68 72 65 66 3d   in the <a href=
92e0: 22 63 33 72 65 66 2f 69 6e 64 65 78 5f 69 6e 66  "c3ref/index_inf
92f0: 6f 2e 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f  o.html">sqlite3_
9300: 69 6e 64 65 78 5f 69 6e 66 6f 3c 2f 61 3e 20 73  index_info</a> s
9310: 74 72 75 63 74 75 72 65 20 69 73 20 65 70 68 65  tructure is ephe
9320: 6d 65 72 61 6c 0a 61 6e 64 20 6d 61 79 20 62 65  meral.and may be
9330: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20   overwritten or 
9340: 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 73 20 73  deallocated as s
9350: 6f 6f 6e 20 61 73 20 74 68 65 20 78 42 65 73 74  oon as the xBest
9360: 49 6e 64 65 78 20 6d 65 74 68 6f 64 0a 72 65 74  Index method.ret
9370: 75 72 6e 73 2e 20 20 49 66 20 74 68 65 20 78 42  urns.  If the xB
9380: 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f 64 20  estIndex method 
9390: 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65  needs to remembe
93a0: 72 20 61 6e 79 20 70 61 72 74 20 6f 66 20 74 68  r any part of th
93b0: 65 0a 3c 61 20 68 72 65 66 3d 22 63 33 72 65 66  e.<a href="c3ref
93c0: 2f 69 6e 64 65 78 5f 69 6e 66 6f 2e 68 74 6d 6c  /index_info.html
93d0: 22 3e 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  ">sqlite3_index_
93e0: 69 6e 66 6f 3c 2f 61 3e 20 73 74 72 75 63 74 75  info</a> structu
93f0: 72 65 2c 20 69 74 20 73 68 6f 75 6c 64 20 6d 61  re, it should ma
9400: 6b 65 20 61 20 63 6f 70 79 2e 20 20 43 61 72 65  ke a copy.  Care
9410: 20 6d 75 73 74 20 62 65 0a 74 61 6b 65 20 74 6f   must be.take to
9420: 20 73 74 6f 72 65 20 74 68 65 20 63 6f 70 79 20   store the copy 
9430: 69 6e 20 61 20 70 6c 61 63 65 20 77 68 65 72 65  in a place where
9440: 20 69 74 20 77 69 6c 6c 20 62 65 20 64 65 61 6c   it will be deal
9450: 6c 6f 63 61 74 65 64 2c 20 73 75 63 68 0a 61 73  located, such.as
9460: 20 69 6e 20 74 68 65 20 69 64 78 53 74 72 20 66   in the idxStr f
9470: 69 65 6c 64 20 77 69 74 68 20 6e 65 65 64 54 6f  ield with needTo
9480: 46 72 65 65 49 64 78 53 74 72 20 73 65 74 20 74  FreeIdxStr set t
9490: 6f 20 31 2e 0a 0a 3c 70 3e 4e 6f 74 65 20 74 68  o 1...<p>Note th
94a0: 61 74 20 78 42 65 73 74 49 6e 64 65 78 20 77 69  at xBestIndex wi
94b0: 6c 6c 20 61 6c 77 61 79 73 20 62 65 20 63 61 6c  ll always be cal
94c0: 6c 65 64 20 62 65 66 6f 72 65 20 3c 61 20 68 72  led before <a hr
94d0: 65 66 3d 22 76 74 61 62 2e 68 74 6d 6c 23 78 66  ef="vtab.html#xf
94e0: 69 6c 74 65 72 22 3e 78 46 69 6c 74 65 72 3c 2f  ilter">xFilter</
94f0: 61 3e 2c 20 73 69 6e 63 65 0a 74 68 65 20 69 64  a>, since.the id
9500: 78 4e 75 6d 20 61 6e 64 20 69 64 78 53 74 72 20  xNum and idxStr 
9510: 6f 75 74 70 75 74 73 20 66 72 6f 6d 20 78 42 65  outputs from xBe
9520: 73 74 49 6e 64 65 78 20 61 72 65 20 72 65 71 75  stIndex are requ
9530: 69 72 65 64 20 69 6e 70 75 74 73 20 74 6f 0a 78  ired inputs to.x
9540: 46 69 6c 74 65 72 2e 20 20 48 6f 77 65 76 65 72  Filter.  However
9550: 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75  , there is no gu
9560: 61 72 61 6e 74 65 65 20 74 68 61 74 20 78 46 69  arantee that xFi
9570: 6c 74 65 72 20 77 69 6c 6c 20 62 65 20 63 61 6c  lter will be cal
9580: 6c 65 64 0a 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  led.following a 
9590: 73 75 63 63 65 73 73 66 75 6c 20 78 42 65 73 74  successful xBest
95a0: 49 6e 64 65 78 2e 20 20 0a 0a 3c 70 3e 54 68 65  Index.  ..<p>The
95b0: 20 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68   xBestIndex meth
95c0: 6f 64 20 69 73 20 72 65 71 75 69 72 65 64 20 66  od is required f
95d0: 6f 72 20 65 76 65 72 79 20 76 69 72 74 75 61 6c  or every virtual
95e0: 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74   table implement
95f0: 61 74 69 6f 6e 2e 0a 0a 3c 68 34 3e 32 2e 33 2e  ation...<h4>2.3.
9600: 31 20 49 6e 70 75 74 73 3c 2f 68 34 3e 0a 0a 3c  1 Inputs</h4>..<
9610: 70 3e 54 68 65 20 6d 61 69 6e 20 74 68 69 6e 67  p>The main thing
9620: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
9630: 20 63 6f 72 65 20 69 73 20 74 72 79 69 6e 67 20   core is trying 
9640: 74 6f 20 63 6f 6d 6d 75 6e 69 63 61 74 65 20 74  to communicate t
9650: 6f 20 0a 74 68 65 20 76 69 72 74 75 61 6c 20 74  o .the virtual t
9660: 61 62 6c 65 20 69 73 20 74 68 65 20 63 6f 6e 73  able is the cons
9670: 74 72 61 69 6e 74 73 20 74 68 61 74 20 61 72 65  traints that are
9680: 20 61 76 61 69 6c 61 62 6c 65 20 74 6f 20 6c 69   available to li
9690: 6d 69 74 20 0a 74 68 65 20 6e 75 6d 62 65 72 20  mit .the number 
96a0: 6f 66 20 72 6f 77 73 20 74 68 61 74 20 6e 65 65  of rows that nee
96b0: 64 20 74 6f 20 62 65 20 73 65 61 72 63 68 65 64  d to be searched
96c0: 2e 20 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e  . The aConstrain
96d0: 74 5b 5d 20 61 72 72 61 79 20 0a 63 6f 6e 74 61  t[] array .conta
96e0: 69 6e 73 20 6f 6e 65 20 65 6e 74 72 79 20 66 6f  ins one entry fo
96f0: 72 20 65 61 63 68 20 63 6f 6e 73 74 72 61 69 6e  r each constrain
9700: 74 2e 20 54 68 65 72 65 20 77 69 6c 6c 20 62 65  t. There will be
9710: 20 65 78 61 63 74 6c 79 20 0a 6e 43 6f 6e 73 74   exactly .nConst
9720: 72 61 69 6e 74 20 65 6e 74 72 69 65 73 20 69 6e  raint entries in
9730: 20 74 68 61 74 20 61 72 72 61 79 2e 0a 0a 3c 70   that array...<p
9740: 3e 45 61 63 68 20 63 6f 6e 73 74 72 61 69 6e 74  >Each constraint
9750: 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64   will correspond
9760: 20 74 6f 20 61 20 74 65 72 6d 20 69 6e 20 74 68   to a term in th
9770: 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a 6f  e WHERE clause.o
9780: 72 20 69 6e 20 61 20 55 53 49 4e 47 20 6f 72 20  r in a USING or 
9790: 4f 4e 20 63 6c 61 75 73 65 20 74 68 61 74 20 69  ON clause that i
97a0: 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 0a 0a 3c  s of the form..<
97b0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 20 20 20 20  blockquote>.    
97c0: 20 63 6f 6c 75 6d 6e 20 20 4f 50 20 20 45 58 50   column  OP  EXP
97d0: 52 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  R.</blockquote>.
97e0: 0a 3c 70 3e 57 68 65 72 65 20 22 63 6f 6c 75 6d  .<p>Where "colum
97f0: 6e 22 20 69 73 20 61 20 63 6f 6c 75 6d 6e 20 69  n" is a column i
9800: 6e 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  n the virtual ta
9810: 62 6c 65 2c 20 4f 50 20 69 73 20 61 6e 20 6f 70  ble, OP is an op
9820: 65 72 61 74 6f 72 20 0a 6c 69 6b 65 20 22 3d 22  erator .like "="
9830: 20 6f 72 20 22 3c 22 2c 20 61 6e 64 20 45 58 50   or "<", and EXP
9840: 52 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  R is an arbitrar
9850: 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 20 53 6f  y expression. So
9860: 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 69  , for example,.i
9870: 66 20 74 68 65 20 57 48 45 52 45 20 63 6c 61 75  f the WHERE clau
9880: 73 65 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 74  se contained a t
9890: 65 72 6d 20 6c 69 6b 65 20 74 68 69 73 3a 0a 0a  erm like this:..
98a0: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
98b0: 3e 0a 20 20 20 20 20 61 20 3d 20 35 0a 3c 2f 70  >.     a = 5.</p
98c0: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
98d0: 0a 0a 3c 70 3e 54 68 65 6e 20 6f 6e 65 20 6f 66  ..<p>Then one of
98e0: 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 73   the constraints
98f0: 20 77 6f 75 6c 64 20 62 65 20 6f 6e 20 74 68 65   would be on the
9900: 20 22 61 22 20 63 6f 6c 75 6d 6e 20 77 69 74 68   "a" column with
9910: 20 0a 6f 70 65 72 61 74 6f 72 20 22 3d 22 20 61   .operator "=" a
9920: 6e 64 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e  nd an expression
9930: 20 6f 66 20 22 35 22 2e 20 43 6f 6e 73 74 72 61   of "5". Constra
9940: 69 6e 74 73 20 6e 65 65 64 20 6e 6f 74 20 68 61  ints need not ha
9950: 76 65 20 61 0a 6c 69 74 65 72 61 6c 20 72 65 70  ve a.literal rep
9960: 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  resentation of t
9970: 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 2e  he WHERE clause.
9980: 20 54 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d   The query optim
9990: 69 7a 65 72 20 6d 69 67 68 74 0a 6d 61 6b 65 20  izer might.make 
99a0: 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 73 20  transformations 
99b0: 74 6f 20 74 68 65 20 0a 57 48 45 52 45 20 63 6c  to the .WHERE cl
99c0: 61 75 73 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  ause in order to
99d0: 20 65 78 74 72 61 63 74 20 61 73 20 6d 61 6e 79   extract as many
99e0: 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 0a 61 73   constraints .as
99f0: 20 69 74 20 63 61 6e 2e 20 53 6f 2c 20 66 6f 72   it can. So, for
9a00: 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65   example, if the
9a10: 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f   WHERE clause co
9a20: 6e 74 61 69 6e 65 64 20 73 6f 6d 65 74 68 69 6e  ntained somethin
9a30: 67 20 0a 6c 69 6b 65 20 74 68 69 73 3a 0a 0a 3c  g .like this:..<
9a40: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
9a50: 0a 20 20 20 20 20 78 20 42 45 54 57 45 45 4e 20  .     x BETWEEN 
9a60: 31 30 20 41 4e 44 20 31 30 30 20 41 4e 44 20 39  10 AND 100 AND 9
9a70: 39 39 3e 79 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  99>y.</pre></blo
9a80: 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68 65  ckquote>..<p>The
9a90: 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72   query optimizer
9aa0: 20 6d 69 67 68 74 20 74 72 61 6e 73 6c 61 74 65   might translate
9ab0: 20 74 68 69 73 20 69 6e 74 6f 20 74 68 72 65 65   this into three
9ac0: 20 73 65 70 61 72 61 74 65 20 63 6f 6e 73 74 72   separate constr
9ad0: 61 69 6e 74 73 3a 0a 0a 3c 62 6c 6f 63 6b 71 75  aints:..<blockqu
9ae0: 6f 74 65 3e 3c 70 72 65 3e 0a 20 20 20 20 20 78  ote><pre>.     x
9af0: 20 3e 3d 20 31 30 0a 20 20 20 20 20 78 20 3c 3d   >= 10.     x <=
9b00: 20 31 30 30 0a 20 20 20 20 20 79 20 3c 20 39 39   100.     y < 99
9b10: 39 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  9.</pre></blockq
9b20: 75 6f 74 65 3e 0a 0a 3c 70 3e 46 6f 72 20 65 61  uote>..<p>For ea
9b30: 63 68 20 63 6f 6e 73 74 72 61 69 6e 74 2c 20 74  ch constraint, t
9b40: 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  he aConstraint[]
9b50: 2e 69 43 6f 6c 75 6d 6e 20 66 69 65 6c 64 20 69  .iColumn field i
9b60: 6e 64 69 63 61 74 65 73 20 77 68 69 63 68 20 0a  ndicates which .
9b70: 63 6f 6c 75 6d 6e 20 61 70 70 65 61 72 73 20 6f  column appears o
9b80: 6e 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20  n the left-hand 
9b90: 73 69 64 65 20 6f 66 20 74 68 65 20 63 6f 6e 73  side of the cons
9ba0: 74 72 61 69 6e 74 2e 0a 54 68 65 20 66 69 72 73  traint..The firs
9bb0: 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
9bc0: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 73  virtual table is
9bd0: 20 63 6f 6c 75 6d 6e 20 30 2e 20 0a 54 68 65 20   column 0. .The 
9be0: 72 6f 77 69 64 20 6f 66 20 74 68 65 20 76 69 72  rowid of the vir
9bf0: 74 75 61 6c 20 74 61 62 6c 65 20 69 73 20 63 6f  tual table is co
9c00: 6c 75 6d 6e 20 2d 31 2e 20 0a 54 68 65 20 61 43  lumn -1. .The aC
9c10: 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 20 66  onstraint[].op f
9c20: 69 65 6c 64 20 69 6e 64 69 63 61 74 65 73 20 77  ield indicates w
9c30: 68 69 63 68 20 6f 70 65 72 61 74 6f 72 20 69 73  hich operator is
9c40: 20 75 73 65 64 2e 20 0a 54 68 65 20 53 51 4c 49   used. .The SQLI
9c50: 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
9c60: 49 4e 54 5f 2a 20 63 6f 6e 73 74 61 6e 74 73 20  INT_* constants 
9c70: 6d 61 70 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  map integer cons
9c80: 74 61 6e 74 73 20 0a 69 6e 74 6f 20 6f 70 65 72  tants .into oper
9c90: 61 74 6f 72 20 76 61 6c 75 65 73 2e 0a 43 6f 6c  ator values..Col
9ca0: 75 6d 6e 73 20 6f 63 63 75 72 20 69 6e 20 74 68  umns occur in th
9cb0: 65 20 6f 72 64 65 72 20 74 68 65 79 20 77 65 72  e order they wer
9cc0: 65 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 65  e defined by the
9cd0: 20 63 61 6c 6c 20 74 6f 0a 3c 61 20 68 72 65 66   call to.<a href
9ce0: 3d 22 63 33 72 65 66 2f 64 65 63 6c 61 72 65 5f  ="c3ref/declare_
9cf0: 76 74 61 62 2e 68 74 6d 6c 22 3e 73 71 6c 69 74  vtab.html">sqlit
9d00: 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28  e3_declare_vtab(
9d10: 29 3c 2f 61 3e 20 69 6e 20 74 68 65 20 3c 61 20  )</a> in the <a 
9d20: 68 72 65 66 3d 22 76 74 61 62 2e 68 74 6d 6c 23  href="vtab.html#
9d30: 78 63 72 65 61 74 65 22 3e 78 43 72 65 61 74 65  xcreate">xCreate
9d40: 3c 2f 61 3e 20 6f 72 20 3c 61 20 68 72 65 66 3d  </a> or <a href=
9d50: 22 76 74 61 62 2e 68 74 6d 6c 23 78 63 6f 6e 6e  "vtab.html#xconn
9d60: 65 63 74 22 3e 78 43 6f 6e 6e 65 63 74 3c 2f 61  ect">xConnect</a
9d70: 3e 20 6d 65 74 68 6f 64 2e 0a 48 69 64 64 65 6e  > method..Hidden
9d80: 20 63 6f 6c 75 6d 6e 73 20 61 72 65 20 63 6f 75   columns are cou
9d90: 6e 74 65 64 20 77 68 65 6e 20 64 65 74 65 72 6d  nted when determ
9da0: 69 6e 69 6e 67 20 74 68 65 20 63 6f 6c 75 6d 6e  ining the column
9db0: 20 69 6e 64 65 78 2e 0a 0a 3c 70 3e 54 68 65 20   index...<p>The 
9dc0: 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72  aConstraint[] ar
9dd0: 72 61 79 20 63 6f 6e 74 61 69 6e 73 20 69 6e 66  ray contains inf
9de0: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61  ormation about a
9df0: 6c 6c 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 0a  ll constraints .
9e00: 74 68 61 74 20 61 70 70 6c 79 20 74 6f 20 74 68  that apply to th
9e10: 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e  e virtual table.
9e20: 20 42 75 74 20 73 6f 6d 65 20 6f 66 20 74 68 65   But some of the
9e30: 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 6d 69 67   constraints mig
9e40: 68 74 0a 6e 6f 74 20 62 65 20 75 73 61 62 6c 65  ht.not be usable
9e50: 20 62 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   because of the 
9e60: 77 61 79 20 74 61 62 6c 65 73 20 61 72 65 20 6f  way tables are o
9e70: 72 64 65 72 65 64 20 69 6e 20 61 20 6a 6f 69 6e  rdered in a join
9e80: 2e 20 0a 54 68 65 20 78 42 65 73 74 49 6e 64 65  . .The xBestInde
9e90: 78 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 74 68  x method must th
9ea0: 65 72 65 66 6f 72 65 20 6f 6e 6c 79 20 63 6f 6e  erefore only con
9eb0: 73 69 64 65 72 20 63 6f 6e 73 74 72 61 69 6e 74  sider constraint
9ec0: 73 20 0a 74 68 61 74 20 68 61 76 65 20 61 6e 20  s .that have an 
9ed0: 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 73  aConstraint[].us
9ee0: 61 62 6c 65 20 66 6c 61 67 20 77 68 69 63 68 20  able flag which 
9ef0: 69 73 20 74 72 75 65 2e 0a 0a 3c 70 3e 49 6e 20  is true...<p>In 
9f00: 61 64 64 69 74 69 6f 6e 20 74 6f 20 57 48 45 52  addition to WHER
9f10: 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61  E clause constra
9f20: 69 6e 74 73 2c 20 74 68 65 20 53 51 4c 69 74 65  ints, the SQLite
9f30: 20 63 6f 72 65 20 61 6c 73 6f 20 0a 74 65 6c 6c   core also .tell
9f40: 73 20 74 68 65 20 78 42 65 73 74 49 6e 64 65 78  s the xBestIndex
9f50: 20 6d 65 74 68 6f 64 20 61 62 6f 75 74 20 74 68   method about th
9f60: 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
9f70: 65 2e 20 0a 28 49 6e 20 61 6e 20 61 67 67 72 65  e. .(In an aggre
9f80: 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20  gate query, the 
9f90: 53 51 4c 69 74 65 20 63 6f 72 65 20 6d 69 67 68  SQLite core migh
9fa0: 74 20 70 75 74 20 69 6e 20 47 52 4f 55 50 20 42  t put in GROUP B
9fb0: 59 20 63 6c 61 75 73 65 20 0a 69 6e 66 6f 72 6d  Y clause .inform
9fc0: 61 74 69 6f 6e 20 69 6e 20 70 6c 61 63 65 20 6f  ation in place o
9fd0: 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63  f the ORDER BY c
9fe0: 6c 61 75 73 65 20 69 6e 66 6f 72 6d 61 74 69 6f  lause informatio
9ff0: 6e 2c 20 62 75 74 20 74 68 69 73 20 66 61 63 74  n, but this fact
a000: 0a 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b 65  .should not make
a010: 20 61 6e 79 20 64 69 66 66 65 72 65 6e 63 65 20   any difference 
a020: 74 6f 20 74 68 65 20 78 42 65 73 74 49 6e 64 65  to the xBestInde
a030: 78 20 6d 65 74 68 6f 64 2e 29 20 0a 49 66 20 61  x method.) .If a
a040: 6c 6c 20 74 65 72 6d 73 20 6f 66 20 74 68 65 20  ll terms of the 
a050: 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20  ORDER BY clause 
a060: 61 72 65 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74  are columns in t
a070: 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
a080: 2c 20 0a 74 68 65 6e 20 6e 4f 72 64 65 72 42 79  , .then nOrderBy
a090: 20 77 69 6c 6c 20 62 65 20 74 68 65 20 6e 75 6d   will be the num
a0a0: 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20  ber of terms in 
a0b0: 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  the ORDER BY cla
a0c0: 75 73 65 20 0a 61 6e 64 20 74 68 65 20 61 4f 72  use .and the aOr
a0d0: 64 65 72 42 79 5b 5d 20 61 72 72 61 79 20 77 69  derBy[] array wi
a0e0: 6c 6c 20 69 64 65 6e 74 69 66 79 20 74 68 65 20  ll identify the 
a0f0: 63 6f 6c 75 6d 6e 20 66 6f 72 20 65 61 63 68 20  column for each 
a100: 74 65 72 6d 20 0a 69 6e 20 74 68 65 20 6f 72 64  term .in the ord
a110: 65 72 20 62 79 20 63 6c 61 75 73 65 20 61 6e 64  er by clause and
a120: 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
a130: 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 41  that column is A
a140: 53 43 20 6f 72 20 44 45 53 43 2e 0a 0a 3c 61 20  SC or DESC...<a 
a150: 6e 61 6d 65 3d 22 63 6f 6c 55 73 65 64 22 3e 3c  name="colUsed"><
a160: 2f 61 3e 0a 0a 3c 70 3e 49 6e 20 53 51 4c 69 74  /a>..<p>In SQLit
a170: 65 20 76 65 72 73 69 6f 6e 20 33 2e 31 30 2e 30  e version 3.10.0
a180: 20 61 6e 64 20 6c 61 74 65 72 2c 20 74 68 65 20   and later, the 
a190: 63 6f 6c 55 73 65 64 20 66 69 65 6c 64 20 69 73  colUsed field is
a1a0: 20 61 76 61 69 6c 61 62 6c 65 0a 74 6f 20 69 6e   available.to in
a1b0: 64 69 63 61 74 65 20 77 68 69 63 68 20 66 69 65  dicate which fie
a1c0: 6c 64 73 20 6f 66 20 74 68 65 20 76 69 72 74 75  lds of the virtu
a1d0: 61 6c 20 74 61 62 6c 65 20 61 72 65 20 61 63 74  al table are act
a1e0: 75 61 6c 6c 79 20 75 73 65 64 20 62 79 20 74 68  ually used by th
a1f0: 65 0a 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e  e.statement bein
a200: 67 20 70 72 65 70 61 72 65 64 2e 20 20 49 66 20  g prepared.  If 
a210: 74 68 65 20 6c 6f 77 65 73 74 20 62 69 74 20 6f  the lowest bit o
a220: 66 20 63 6f 6c 55 73 65 64 20 69 73 20 73 65 74  f colUsed is set
a230: 2c 20 74 68 61 74 0a 6d 65 61 6e 73 20 74 68 61  , that.means tha
a240: 74 20 74 68 65 20 66 69 72 73 74 20 63 6f 6c 75  t the first colu
a250: 6d 6e 20 69 73 20 75 73 65 64 2e 20 20 54 68 65  mn is used.  The
a260: 20 73 65 63 6f 6e 64 20 6c 6f 77 65 73 74 20 62   second lowest b
a270: 69 74 20 63 6f 72 72 65 73 70 6f 6e 64 73 0a 74  it corresponds.t
a280: 6f 20 74 68 65 20 73 65 63 6f 6e 64 20 63 6f 6c  o the second col
a290: 75 6d 6e 2e 20 20 41 6e 64 20 73 6f 20 66 6f 72  umn.  And so for
a2a0: 74 68 2e 20 20 49 66 20 74 68 65 20 6d 6f 73 74  th.  If the most
a2b0: 20 73 69 67 6e 69 66 69 63 61 6e 74 20 62 69 74   significant bit
a2c0: 20 6f 66 0a 63 6f 6c 55 73 65 64 20 69 73 20 73   of.colUsed is s
a2d0: 65 74 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  et, that means t
a2e0: 68 61 74 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  hat one or more 
a2f0: 63 6f 6c 75 6d 6e 73 20 6f 74 68 65 72 20 74 68  columns other th
a300: 61 6e 20 74 68 65 20 0a 66 69 72 73 74 20 36 33  an the .first 63
a310: 20 63 6f 6c 75 6d 6e 73 20 61 72 65 20 75 73 65   columns are use
a320: 64 2e 20 20 49 66 20 63 6f 6c 75 6d 6e 20 75 73  d.  If column us
a330: 61 67 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  age information 
a340: 69 73 20 6e 65 65 64 65 64 20 62 79 20 74 68 65  is needed by the
a350: 0a 3c 61 20 68 72 65 66 3d 22 76 74 61 62 2e 68  .<a href="vtab.h
a360: 74 6d 6c 23 78 66 69 6c 74 65 72 22 3e 78 46 69  tml#xfilter">xFi
a370: 6c 74 65 72 3c 2f 61 3e 20 6d 65 74 68 6f 64 2c  lter</a> method,
a380: 20 74 68 65 6e 20 74 68 65 20 72 65 71 75 69 72   then the requir
a390: 65 64 20 62 69 74 73 20 6d 75 73 74 20 62 65 20  ed bits must be 
a3a0: 65 6e 63 6f 64 65 64 20 69 6e 74 6f 20 65 69 74  encoded into eit
a3b0: 68 65 72 0a 74 68 65 20 69 64 78 4e 75 6d 20 6f  her.the idxNum o
a3c0: 72 20 69 64 78 53 74 72 20 6f 75 74 70 75 74 20  r idxStr output 
a3d0: 66 69 65 6c 64 73 2e 0a 0a 3c 68 34 3e 32 2e 33  fields...<h4>2.3
a3e0: 2e 32 20 4f 75 74 70 75 74 73 3c 2f 68 34 3e 0a  .2 Outputs</h4>.
a3f0: 0a 3c 70 3e 47 69 76 65 6e 20 61 6c 6c 20 6f 66  .<p>Given all of
a400: 20 74 68 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e   the information
a410: 20 61 62 6f 76 65 2c 20 74 68 65 20 6a 6f 62 20   above, the job 
a420: 6f 66 20 74 68 65 20 78 42 65 73 74 49 6e 64 65  of the xBestInde
a430: 78 20 0a 6d 65 74 68 6f 64 20 69 74 20 74 6f 20  x .method it to 
a440: 66 69 67 75 72 65 20 6f 75 74 20 74 68 65 20 62  figure out the b
a450: 65 73 74 20 77 61 79 20 74 6f 20 73 65 61 72 63  est way to searc
a460: 68 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  h the virtual ta
a470: 62 6c 65 2e 0a 0a 3c 70 3e 54 68 65 20 78 42 65  ble...<p>The xBe
a480: 73 74 49 6e 64 65 78 20 6d 65 74 68 6f 64 20 66  stIndex method f
a490: 69 6c 6c 73 20 74 68 65 20 69 64 78 4e 75 6d 20  ills the idxNum 
a4a0: 61 6e 64 20 69 64 78 53 74 72 20 66 69 65 6c 64  and idxStr field
a4b0: 73 20 77 69 74 68 20 0a 69 6e 66 6f 72 6d 61 74  s with .informat
a4c0: 69 6f 6e 20 74 68 61 74 20 63 6f 6d 6d 75 6e 69  ion that communi
a4d0: 63 61 74 65 73 20 61 6e 20 69 6e 64 65 78 69 6e  cates an indexin
a4e0: 67 20 73 74 72 61 74 65 67 79 20 74 6f 20 74 68  g strategy to th
a4f0: 65 20 3c 61 20 68 72 65 66 3d 22 76 74 61 62 2e  e <a href="vtab.
a500: 68 74 6d 6c 23 78 66 69 6c 74 65 72 22 3e 78 46  html#xfilter">xF
a510: 69 6c 74 65 72 3c 2f 61 3e 20 0a 6d 65 74 68 6f  ilter</a> .metho
a520: 64 2e 20 54 68 65 20 69 6e 66 6f 72 6d 61 74 69  d. The informati
a530: 6f 6e 20 69 6e 20 69 64 78 4e 75 6d 20 61 6e 64  on in idxNum and
a540: 20 69 64 78 53 74 72 20 69 73 20 61 72 62 69 74   idxStr is arbit
a550: 72 61 72 79 20 61 73 20 66 61 72 20 0a 61 73 20  rary as far .as 
a560: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  the SQLite core 
a570: 69 73 20 63 6f 6e 63 65 72 6e 65 64 2e 20 54 68  is concerned. Th
a580: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6a 75  e SQLite core ju
a590: 73 74 20 63 6f 70 69 65 73 20 74 68 65 20 0a 69  st copies the .i
a5a0: 6e 66 6f 72 6d 61 74 69 6f 6e 20 74 68 72 6f 75  nformation throu
a5b0: 67 68 20 74 6f 20 74 68 65 20 3c 61 20 68 72 65  gh to the <a hre
a5c0: 66 3d 22 76 74 61 62 2e 68 74 6d 6c 23 78 66 69  f="vtab.html#xfi
a5d0: 6c 74 65 72 22 3e 78 46 69 6c 74 65 72 3c 2f 61  lter">xFilter</a
a5e0: 3e 20 6d 65 74 68 6f 64 2e 20 41 6e 79 20 64 65  > method. Any de
a5f0: 73 69 72 65 64 20 6d 65 61 6e 69 6e 67 20 63 61  sired meaning ca
a600: 6e 20 0a 62 65 20 61 73 73 69 67 6e 65 64 20 74  n .be assigned t
a610: 6f 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78  o idxNum and idx
a620: 53 74 72 20 61 73 20 6c 6f 6e 67 20 61 73 20 78  Str as long as x
a630: 42 65 73 74 49 6e 64 65 78 20 61 6e 64 20 78 46  BestIndex and xF
a640: 69 6c 74 65 72 20 0a 61 67 72 65 65 20 6f 6e 20  ilter .agree on 
a650: 77 68 61 74 20 74 68 61 74 20 6d 65 61 6e 69 6e  what that meanin
a660: 67 20 69 73 2e 0a 0a 3c 70 3e 54 68 65 20 69 64  g is...<p>The id
a670: 78 53 74 72 20 76 61 6c 75 65 20 6d 61 79 20 62  xStr value may b
a680: 65 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69  e a string obtai
a690: 6e 65 64 20 66 72 6f 6d 20 61 6e 20 53 51 4c 69  ned from an SQLi
a6a0: 74 65 0a 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  te.memory alloca
a6b0: 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 73 75  tion function su
a6c0: 63 68 20 61 73 20 3c 61 20 68 72 65 66 3d 22 63  ch as <a href="c
a6d0: 33 72 65 66 2f 6d 70 72 69 6e 74 66 2e 68 74 6d  3ref/mprintf.htm
a6e0: 6c 22 3e 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  l">sqlite3_mprin
a6f0: 74 66 28 29 3c 2f 61 3e 2e 20 0a 49 66 20 74 68  tf()</a>. .If th
a700: 69 73 20 69 73 20 74 68 65 20 63 61 73 65 2c 20  is is the case, 
a710: 74 68 65 6e 20 74 68 65 20 6e 65 65 64 54 6f 46  then the needToF
a720: 72 65 65 49 64 78 53 74 72 20 66 6c 61 67 20 6d  reeIdxStr flag m
a730: 75 73 74 20 62 65 20 73 65 74 20 74 6f 20 0a 74  ust be set to .t
a740: 72 75 65 20 73 6f 20 74 68 61 74 20 74 68 65 20  rue so that the 
a750: 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c  SQLite core will
a760: 20 6b 6e 6f 77 20 74 6f 20 63 61 6c 6c 20 3c 61   know to call <a
a770: 20 68 72 65 66 3d 22 63 33 72 65 66 2f 66 72 65   href="c3ref/fre
a780: 65 2e 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f  e.html">sqlite3_
a790: 66 72 65 65 28 29 3c 2f 61 3e 20 6f 6e 20 0a 74  free()</a> on .t
a7a0: 68 61 74 20 73 74 72 69 6e 67 20 77 68 65 6e 20  hat string when 
a7b0: 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
a7c0: 77 69 74 68 20 69 74 2c 20 61 6e 64 20 74 68 75  with it, and thu
a7d0: 73 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79  s avoid a memory
a7e0: 20 6c 65 61 6b 2e 0a 0a 3c 70 3e 49 66 20 74 68   leak...<p>If th
a7f0: 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  e virtual table 
a800: 77 69 6c 6c 20 6f 75 74 70 75 74 20 72 6f 77 73  will output rows
a810: 20 69 6e 20 74 68 65 20 6f 72 64 65 72 20 73 70   in the order sp
a820: 65 63 69 66 69 65 64 20 62 79 20 0a 74 68 65 20  ecified by .the 
a830: 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 2c  ORDER BY clause,
a840: 20 74 68 65 6e 20 74 68 65 20 6f 72 64 65 72 42   then the orderB
a850: 79 43 6f 6e 73 75 6d 65 64 20 66 6c 61 67 20 6d  yConsumed flag m
a860: 61 79 20 62 65 20 73 65 74 20 74 6f 20 0a 74 72  ay be set to .tr
a870: 75 65 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75  ue. If the outpu
a880: 74 20 69 73 20 6e 6f 74 20 61 75 74 6f 6d 61 74  t is not automat
a890: 69 63 61 6c 6c 79 20 69 6e 20 74 68 65 20 63 6f  ically in the co
a8a0: 72 72 65 63 74 20 6f 72 64 65 72 20 0a 74 68 65  rrect order .the
a8b0: 6e 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65  n orderByConsume
a8c0: 64 20 6d 75 73 74 20 62 65 20 6c 65 66 74 20 69  d must be left i
a8d0: 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 66 61  n its default fa
a8e0: 6c 73 65 20 73 65 74 74 69 6e 67 2e 20 0a 54 68  lse setting. .Th
a8f0: 69 73 20 77 69 6c 6c 20 69 6e 64 69 63 61 74 65  is will indicate
a900: 20 74 6f 20 74 68 65 20 53 51 4c 69 74 65 20 63   to the SQLite c
a910: 6f 72 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c  ore that it will
a920: 20 6e 65 65 64 20 74 6f 20 64 6f 20 61 20 0a 73   need to do a .s
a930: 65 70 61 72 61 74 65 20 73 6f 72 74 69 6e 67 20  eparate sorting 
a940: 70 61 73 73 20 6f 76 65 72 20 74 68 65 20 64 61  pass over the da
a950: 74 61 20 61 66 74 65 72 20 69 74 20 63 6f 6d 65  ta after it come
a960: 73 20 6f 75 74 20 6f 66 20 74 68 65 20 76 69 72  s out of the vir
a970: 74 75 61 6c 20 74 61 62 6c 65 2e 0a 0a 3c 70 3e  tual table...<p>
a980: 54 68 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73  The estimatedCos
a990: 74 20 66 69 65 6c 64 20 73 68 6f 75 6c 64 20 62  t field should b
a9a0: 65 20 73 65 74 20 74 6f 20 74 68 65 20 65 73 74  e set to the est
a9b0: 69 6d 61 74 65 64 20 6e 75 6d 62 65 72 0a 6f 66  imated number.of
a9c0: 20 64 69 73 6b 20 61 63 63 65 73 73 20 6f 70 65   disk access ope
a9d0: 72 61 74 69 6f 6e 73 20 72 65 71 75 69 72 65 64  rations required
a9e0: 20 74 6f 20 65 78 65 63 75 74 65 20 74 68 69 73   to execute this
a9f0: 20 71 75 65 72 79 20 61 67 61 69 6e 73 74 20 0a   query against .
aa00: 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
aa10: 65 2e 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  e. The SQLite co
aa20: 72 65 20 77 69 6c 6c 20 6f 66 74 65 6e 20 63 61  re will often ca
aa30: 6c 6c 20 78 42 65 73 74 49 6e 64 65 78 20 0a 6d  ll xBestIndex .m
aa40: 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69  ultiple times wi
aa50: 74 68 20 64 69 66 66 65 72 65 6e 74 20 63 6f 6e  th different con
aa60: 73 74 72 61 69 6e 74 73 2c 20 6f 62 74 61 69 6e  straints, obtain
aa70: 20 6d 75 6c 74 69 70 6c 65 20 63 6f 73 74 0a 65   multiple cost.e
aa80: 73 74 69 6d 61 74 65 73 2c 20 74 68 65 6e 20 63  stimates, then c
aa90: 68 6f 6f 73 65 20 74 68 65 20 71 75 65 72 79 20  hoose the query 
aaa0: 70 6c 61 6e 20 74 68 61 74 20 67 69 76 65 73 20  plan that gives 
aab0: 74 68 65 20 6c 6f 77 65 73 74 20 65 73 74 69 6d  the lowest estim
aac0: 61 74 65 2e 0a 0a 3c 70 3e 49 66 20 74 68 65 20  ate...<p>If the 
aad0: 63 75 72 72 65 6e 74 20 76 65 72 73 69 6f 6e 20  current version 
aae0: 6f 66 20 53 51 4c 69 74 65 20 69 73 20 33 2e 38  of SQLite is 3.8
aaf0: 2e 32 20 6f 72 20 67 72 65 61 74 65 72 2c 20 74  .2 or greater, t
ab00: 68 65 20 65 73 74 69 6d 61 74 65 64 52 6f 77 73  he estimatedRows
ab10: 0a 66 69 65 6c 64 20 6d 61 79 20 62 65 20 73 65  .field may be se
ab20: 74 20 74 6f 20 61 6e 20 65 73 74 69 6d 61 74 65  t to an estimate
ab30: 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
ab40: 66 20 72 6f 77 73 20 72 65 74 75 72 6e 65 64 20  f rows returned 
ab50: 62 79 20 74 68 65 0a 70 72 6f 70 6f 73 65 64 20  by the.proposed 
ab60: 71 75 65 72 79 20 70 6c 61 6e 2e 20 49 66 20 74  query plan. If t
ab70: 68 69 73 20 76 61 6c 75 65 20 69 73 20 6e 6f 74  his value is not
ab80: 20 65 78 70 6c 69 63 69 74 6c 79 20 73 65 74 2c   explicitly set,
ab90: 20 74 68 65 20 64 65 66 61 75 6c 74 20 0a 65 73   the default .es
aba0: 74 69 6d 61 74 65 20 6f 66 20 32 35 20 72 6f 77  timate of 25 row
abb0: 73 20 69 73 20 75 73 65 64 2e 0a 0a 3c 70 3e 49  s is used...<p>I
abc0: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 65  f the current ve
abd0: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20  rsion of SQLite 
abe0: 69 73 20 33 2e 39 2e 30 20 6f 72 20 67 72 65 61  is 3.9.0 or grea
abf0: 74 65 72 2c 20 74 68 65 20 69 64 78 46 6c 61 67  ter, the idxFlag
ac00: 73 20 66 69 65 6c 64 0a 6d 61 79 20 62 65 20 73  s field.may be s
ac10: 65 74 20 74 6f 20 53 51 4c 49 54 45 5f 49 4e 44  et to SQLITE_IND
ac20: 45 58 5f 53 43 41 4e 5f 55 4e 49 51 55 45 20 74  EX_SCAN_UNIQUE t
ac30: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
ac40: 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
ac50: 65 0a 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e  e.will return on
ac60: 6c 79 20 7a 65 72 6f 20 6f 72 20 6f 6e 65 20 72  ly zero or one r
ac70: 6f 77 73 20 67 69 76 65 6e 20 74 68 65 20 69 6e  ows given the in
ac80: 70 75 74 20 63 6f 6e 73 74 72 61 69 6e 74 73 2e  put constraints.
ac90: 20 20 41 64 64 69 74 69 6f 6e 61 6c 0a 62 69 74    Additional.bit
aca0: 73 20 6f 66 20 74 68 65 20 69 64 78 46 6c 61 67  s of the idxFlag
acb0: 73 20 66 69 65 6c 64 20 6d 69 67 68 74 20 62 65  s field might be
acc0: 20 75 6e 64 65 72 73 74 6f 6f 64 20 69 6e 20 6c   understood in l
acd0: 61 74 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  ater versions of
ace0: 20 53 51 4c 69 74 65 2e 0a 0a 3c 70 3e 54 68 65   SQLite...<p>The
acf0: 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67   aConstraintUsag
ad00: 65 5b 5d 20 61 72 72 61 79 20 63 6f 6e 74 61 69  e[] array contai
ad10: 6e 73 20 6f 6e 65 20 65 6c 65 6d 65 6e 74 20 66  ns one element f
ad20: 6f 72 20 65 61 63 68 20 6f 66 20 0a 74 68 65 20  or each of .the 
ad30: 6e 43 6f 6e 73 74 72 61 69 6e 74 20 63 6f 6e 73  nConstraint cons
ad40: 74 72 61 69 6e 74 73 20 69 6e 20 74 68 65 20 69  traints in the i
ad50: 6e 70 75 74 73 20 73 65 63 74 69 6f 6e 20 6f 66  nputs section of
ad60: 20 74 68 65 20 0a 3c 61 20 68 72 65 66 3d 22 63   the .<a href="c
ad70: 33 72 65 66 2f 69 6e 64 65 78 5f 69 6e 66 6f 2e  3ref/index_info.
ad80: 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 69 6e  html">sqlite3_in
ad90: 64 65 78 5f 69 6e 66 6f 3c 2f 61 3e 20 73 74 72  dex_info</a> str
ada0: 75 63 74 75 72 65 2e 20 0a 54 68 65 20 61 43 6f  ucture. .The aCo
adb0: 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20  nstraintUsage[] 
adc0: 61 72 72 61 79 20 69 73 20 75 73 65 64 20 62 79  array is used by
add0: 20 78 42 65 73 74 49 6e 64 65 78 20 74 6f 20 74   xBestIndex to t
ade0: 65 6c 6c 20 74 68 65 20 0a 63 6f 72 65 20 68 6f  ell the .core ho
adf0: 77 20 69 74 20 69 73 20 75 73 69 6e 67 20 74 68  w it is using th
ae00: 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 2e 0a 0a  e constraints...
ae10: 3c 70 3e 54 68 65 20 78 42 65 73 74 49 6e 64 65  <p>The xBestInde
ae20: 78 20 6d 65 74 68 6f 64 20 6d 61 79 20 73 65 74  x method may set
ae30: 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67   aConstraintUsag
ae40: 65 5b 5d 2e 61 72 67 76 49 6e 64 65 78 20 0a 65  e[].argvIndex .e
ae50: 6e 74 72 69 65 73 20 74 6f 20 76 61 6c 75 65 73  ntries to values
ae60: 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65   greater than ze
ae70: 72 6f 2e 20 0a 45 78 61 63 74 6c 79 20 6f 6e 65  ro. .Exactly one
ae80: 20 65 6e 74 72 79 20 73 68 6f 75 6c 64 20 62 65   entry should be
ae90: 20 73 65 74 20 74 6f 20 31 2c 20 61 6e 6f 74 68   set to 1, anoth
aea0: 65 72 20 74 6f 20 32 2c 20 61 6e 6f 74 68 65 72  er to 2, another
aeb0: 20 74 6f 20 33 2c 20 0a 61 6e 64 20 73 6f 20 66   to 3, .and so f
aec0: 6f 72 74 68 20 75 70 20 74 6f 20 61 73 20 6d 61  orth up to as ma
aed0: 6e 79 20 6f 72 20 61 73 20 66 65 77 20 61 73 20  ny or as few as 
aee0: 74 68 65 20 78 42 65 73 74 49 6e 64 65 78 20 6d  the xBestIndex m
aef0: 65 74 68 6f 64 20 77 61 6e 74 73 2e 20 0a 54 68  ethod wants. .Th
af00: 65 20 45 58 50 52 20 6f 66 20 74 68 65 20 63 6f  e EXPR of the co
af10: 72 72 65 73 70 6f 6e 64 69 6e 67 20 63 6f 6e 73  rresponding cons
af20: 74 72 61 69 6e 74 73 20 77 69 6c 6c 20 74 68 65  traints will the
af30: 6e 20 62 65 20 70 61 73 73 65 64 20 0a 69 6e 20  n be passed .in 
af40: 61 73 20 74 68 65 20 61 72 67 76 5b 5d 20 70 61  as the argv[] pa
af50: 72 61 6d 65 74 65 72 73 20 74 6f 20 78 46 69 6c  rameters to xFil
af60: 74 65 72 2e 0a 0a 3c 70 3e 46 6f 72 20 65 78 61  ter...<p>For exa
af70: 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 61 43 6f  mple, if the aCo
af80: 6e 73 74 72 61 69 6e 74 5b 33 5d 2e 61 72 67 76  nstraint[3].argv
af90: 49 6e 64 65 78 20 69 73 20 73 65 74 20 74 6f 20  Index is set to 
afa0: 31 2c 20 74 68 65 6e 20 0a 77 68 65 6e 20 78 46  1, then .when xF
afb0: 69 6c 74 65 72 20 69 73 20 63 61 6c 6c 65 64 2c  ilter is called,
afc0: 20 74 68 65 20 61 72 67 76 5b 30 5d 20 70 61 73   the argv[0] pas
afd0: 73 65 64 20 74 6f 20 78 46 69 6c 74 65 72 20 77  sed to xFilter w
afe0: 69 6c 6c 20 68 61 76 65 20 0a 74 68 65 20 45 58  ill have .the EX
aff0: 50 52 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  PR value of the 
b000: 61 43 6f 6e 73 74 72 61 69 6e 74 5b 33 5d 20 63  aConstraint[3] c
b010: 6f 6e 73 74 72 61 69 6e 74 2e 0a 0a 3c 70 3e 42  onstraint...<p>B
b020: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 53  y default, the S
b030: 51 4c 69 74 65 20 63 6f 72 65 20 64 6f 75 62 6c  QLite core doubl
b040: 65 20 63 68 65 63 6b 73 20 61 6c 6c 20 63 6f 6e  e checks all con
b050: 73 74 72 61 69 6e 74 73 20 6f 6e 20 0a 65 61 63  straints on .eac
b060: 68 20 72 6f 77 20 6f 66 20 74 68 65 20 76 69 72  h row of the vir
b070: 74 75 61 6c 20 74 61 62 6c 65 20 74 68 61 74 20  tual table that 
b080: 69 74 20 72 65 63 65 69 76 65 73 2e 20 49 66 20  it receives. If 
b090: 73 75 63 68 20 61 20 63 68 65 63 6b 20 0a 69 73  such a check .is
b0a0: 20 72 65 64 75 6e 64 61 6e 74 2c 20 74 68 65 20   redundant, the 
b0b0: 78 42 65 73 74 46 69 6c 74 65 72 20 6d 65 74 68  xBestFilter meth
b0c0: 6f 64 20 63 61 6e 20 73 75 70 70 72 65 73 73 20  od can suppress 
b0d0: 74 68 61 74 20 64 6f 75 62 6c 65 2d 63 68 65 63  that double-chec
b0e0: 6b 20 62 79 20 0a 73 65 74 74 69 6e 67 20 61 43  k by .setting aC
b0f0: 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d  onstraintUsage[]
b100: 2e 6f 6d 69 74 2e 0a 0a 3c 61 20 6e 61 6d 65 3d  .omit...<a name=
b110: 22 78 64 69 73 63 6f 6e 6e 65 63 74 22 3e 3c 2f  "xdisconnect"></
b120: 61 3e 0a 0a 3c 68 33 3e 32 2e 34 20 54 68 65 20  a>..<h3>2.4 The 
b130: 78 44 69 73 63 6f 6e 6e 65 63 74 20 4d 65 74 68  xDisconnect Meth
b140: 6f 64 3c 2f 68 33 3e 0a 0a 3c 62 6c 6f 63 6b 71  od</h3>..<blockq
b150: 75 6f 74 65 3e 3c 70 72 65 3e 0a 20 20 69 6e 74  uote><pre>.  int
b160: 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28   (*xDisconnect)(
b170: 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
b180: 54 61 62 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c  Tab);.</pre></bl
b190: 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68  ockquote>..<p>Th
b1a0: 69 73 20 6d 65 74 68 6f 64 20 72 65 6c 65 61 73  is method releas
b1b0: 65 73 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  es a connection 
b1c0: 74 6f 20 61 20 76 69 72 74 75 61 6c 20 74 61 62  to a virtual tab
b1d0: 6c 65 2e 20 0a 4f 6e 6c 79 20 74 68 65 20 3c 61  le. .Only the <a
b1e0: 20 68 72 65 66 3d 22 63 33 72 65 66 2f 76 74 61   href="c3ref/vta
b1f0: 62 2e 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f  b.html">sqlite3_
b200: 76 74 61 62 3c 2f 61 3e 20 6f 62 6a 65 63 74 20  vtab</a> object 
b210: 69 73 20 64 65 73 74 72 6f 79 65 64 2e 0a 54 68  is destroyed..Th
b220: 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  e virtual table 
b230: 69 73 20 6e 6f 74 20 64 65 73 74 72 6f 79 65 64  is not destroyed
b240: 20 61 6e 64 20 61 6e 79 20 62 61 63 6b 69 6e 67   and any backing
b250: 20 73 74 6f 72 65 20 0a 61 73 73 6f 63 69 61 74   store .associat
b260: 65 64 20 77 69 74 68 20 74 68 65 20 76 69 72 74  ed with the virt
b270: 75 61 6c 20 74 61 62 6c 65 20 70 65 72 73 69 73  ual table persis
b280: 74 73 2e 20 0a 0a 54 68 69 73 20 6d 65 74 68 6f  ts. ..This metho
b290: 64 20 75 6e 64 6f 65 73 20 74 68 65 20 77 6f 72  d undoes the wor
b2a0: 6b 20 6f 66 20 3c 61 20 68 72 65 66 3d 22 76 74  k of <a href="vt
b2b0: 61 62 2e 68 74 6d 6c 23 78 63 6f 6e 6e 65 63 74  ab.html#xconnect
b2c0: 22 3e 78 43 6f 6e 6e 65 63 74 3c 2f 61 3e 2e 0a  ">xConnect</a>..
b2d0: 0a 3c 70 3e 54 68 69 73 20 6d 65 74 68 6f 64 20  .<p>This method 
b2e0: 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  is a destructor 
b2f0: 66 6f 72 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e  for a connection
b300: 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 20   to the virtual 
b310: 74 61 62 6c 65 2e 0a 43 6f 6e 74 72 61 73 74 20  table..Contrast 
b320: 74 68 69 73 20 6d 65 74 68 6f 64 20 77 69 74 68  this method with
b330: 20 3c 61 20 68 72 65 66 3d 22 76 74 61 62 2e 68   <a href="vtab.h
b340: 74 6d 6c 23 73 71 6c 69 74 65 33 5f 6d 6f 64 75  tml#sqlite3_modu
b350: 6c 65 2e 78 44 65 73 74 72 6f 79 22 3e 78 44 65  le.xDestroy">xDe
b360: 73 74 72 6f 79 3c 2f 61 3e 2e 20 20 54 68 65 20  stroy</a>.  The 
b370: 78 44 65 73 74 72 6f 79 20 69 73 20 61 20 64 65  xDestroy is a de
b380: 73 74 72 75 63 74 6f 72 0a 66 6f 72 20 74 68 65  structor.for the
b390: 20 65 6e 74 69 72 65 20 76 69 72 74 75 61 6c 20   entire virtual 
b3a0: 74 61 62 6c 65 2e 0a 0a 3c 70 3e 54 68 65 20 78  table...<p>The x
b3b0: 44 69 73 63 6f 6e 6e 65 63 74 20 6d 65 74 68 6f  Disconnect metho
b3c0: 64 20 69 73 20 72 65 71 75 69 72 65 64 20 66 6f  d is required fo
b3d0: 72 20 65 76 65 72 79 20 76 69 72 74 75 61 6c 20  r every virtual 
b3e0: 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
b3f0: 74 69 6f 6e 2c 0a 74 68 6f 75 67 68 20 69 74 20  tion,.though it 
b400: 69 73 20 61 63 63 65 70 74 61 62 6c 65 20 66 6f  is acceptable fo
b410: 72 20 74 68 65 20 78 44 69 73 63 6f 6e 6e 65 63  r the xDisconnec
b420: 74 20 61 6e 64 20 3c 61 20 68 72 65 66 3d 22 76  t and <a href="v
b430: 74 61 62 2e 68 74 6d 6c 23 73 71 6c 69 74 65 33  tab.html#sqlite3
b440: 5f 6d 6f 64 75 6c 65 2e 78 44 65 73 74 72 6f 79  _module.xDestroy
b450: 22 3e 78 44 65 73 74 72 6f 79 3c 2f 61 3e 20 6d  ">xDestroy</a> m
b460: 65 74 68 6f 64 73 20 74 6f 20 62 65 0a 74 68 65  ethods to be.the
b470: 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 69   same function i
b480: 66 20 74 68 61 74 20 6d 61 6b 65 73 20 73 65 6e  f that makes sen
b490: 73 65 20 66 6f 72 20 74 68 65 20 70 61 72 74 69  se for the parti
b4a0: 63 75 6c 61 72 20 76 69 72 74 75 61 6c 20 74 61  cular virtual ta
b4b0: 62 6c 65 2e 0a 0a 3c 61 20 6e 61 6d 65 3d 22 73  ble...<a name="s
b4c0: 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 44  qlite3_module.xD
b4d0: 65 73 74 72 6f 79 22 3e 3c 2f 61 3e 0a 0a 3c 68  estroy"></a>..<h
b4e0: 33 3e 32 2e 35 20 54 68 65 20 78 44 65 73 74 72  3>2.5 The xDestr
b4f0: 6f 79 20 4d 65 74 68 6f 64 3c 2f 68 33 3e 0a 0a  oy Method</h3>..
b500: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
b510: 3e 0a 20 20 69 6e 74 20 28 2a 78 44 65 73 74 72  >.  int (*xDestr
b520: 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  oy)(sqlite3_vtab
b530: 20 2a 70 56 54 61 62 29 3b 0a 3c 2f 70 72 65 3e   *pVTab);.</pre>
b540: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c  </blockquote>..<
b550: 70 3e 54 68 69 73 20 6d 65 74 68 6f 64 20 72 65  p>This method re
b560: 6c 65 61 73 65 73 20 61 20 63 6f 6e 6e 65 63 74  leases a connect
b570: 69 6f 6e 20 74 6f 20 61 20 76 69 72 74 75 61 6c  ion to a virtual
b580: 20 74 61 62 6c 65 2c 20 6a 75 73 74 20 6c 69 6b   table, just lik
b590: 65 20 0a 74 68 65 20 3c 61 20 68 72 65 66 3d 22  e .the <a href="
b5a0: 76 74 61 62 2e 68 74 6d 6c 23 78 64 69 73 63 6f  vtab.html#xdisco
b5b0: 6e 6e 65 63 74 22 3e 78 44 69 73 63 6f 6e 6e 65  nnect">xDisconne
b5c0: 63 74 3c 2f 61 3e 20 6d 65 74 68 6f 64 2c 20 61  ct</a> method, a
b5d0: 6e 64 20 69 74 20 61 6c 73 6f 20 64 65 73 74 72  nd it also destr
b5e0: 6f 79 73 20 74 68 65 20 75 6e 64 65 72 6c 79 69  oys the underlyi
b5f0: 6e 67 20 0a 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ng .table implem
b600: 65 6e 74 61 74 69 6f 6e 2e 20 54 68 69 73 20 6d  entation. This m
b610: 65 74 68 6f 64 20 75 6e 64 6f 65 73 20 74 68 65  ethod undoes the
b620: 20 77 6f 72 6b 20 6f 66 20 3c 61 20 68 72 65 66   work of <a href
b630: 3d 22 76 74 61 62 2e 68 74 6d 6c 23 78 63 72 65  ="vtab.html#xcre
b640: 61 74 65 22 3e 78 43 72 65 61 74 65 3c 2f 61 3e  ate">xCreate</a>
b650: 2e 0a 0a 3c 70 3e 54 68 65 20 3c 61 20 68 72 65  ...<p>The <a hre
b660: 66 3d 22 76 74 61 62 2e 68 74 6d 6c 23 78 64 69  f="vtab.html#xdi
b670: 73 63 6f 6e 6e 65 63 74 22 3e 78 44 69 73 63 6f  sconnect">xDisco
b680: 6e 6e 65 63 74 3c 2f 61 3e 20 6d 65 74 68 6f 64  nnect</a> method
b690: 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e 65   is called whene
b6a0: 76 65 72 20 61 20 64 61 74 61 62 61 73 65 20 63  ver a database c
b6b0: 6f 6e 6e 65 63 74 69 6f 6e 0a 74 68 61 74 20 75  onnection.that u
b6c0: 73 65 73 20 61 20 76 69 72 74 75 61 6c 20 74 61  ses a virtual ta
b6d0: 62 6c 65 20 69 73 20 63 6c 6f 73 65 64 2e 20 54  ble is closed. T
b6e0: 68 65 20 78 44 65 73 74 72 6f 79 20 6d 65 74 68  he xDestroy meth
b6f0: 6f 64 20 69 73 20 6f 6e 6c 79 20 0a 63 61 6c 6c  od is only .call
b700: 65 64 20 77 68 65 6e 20 61 20 3c 61 20 68 72 65  ed when a <a hre
b710: 66 3d 22 6c 61 6e 67 5f 64 72 6f 70 74 61 62 6c  f="lang_droptabl
b720: 65 2e 68 74 6d 6c 22 3e 44 52 4f 50 20 54 41 42  e.html">DROP TAB
b730: 4c 45 3c 2f 61 3e 20 73 74 61 74 65 6d 65 6e 74  LE</a> statement
b740: 20 69 73 20 65 78 65 63 75 74 65 64 20 61 67 61   is executed aga
b750: 69 6e 73 74 20 74 68 65 20 76 69 72 74 75 61 6c  inst the virtual
b760: 20 74 61 62 6c 65 2e 0a 0a 3c 70 3e 54 68 65 20   table...<p>The 
b770: 78 44 65 73 74 72 6f 79 20 6d 65 74 68 6f 64 20  xDestroy method 
b780: 69 73 20 72 65 71 75 69 72 65 64 20 66 6f 72 20  is required for 
b790: 65 76 65 72 79 20 76 69 72 74 75 61 6c 20 74 61  every virtual ta
b7a0: 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
b7b0: 6f 6e 2c 0a 74 68 6f 75 67 68 20 69 74 20 69 73  on,.though it is
b7c0: 20 61 63 63 65 70 74 61 62 6c 65 20 66 6f 72 20   acceptable for 
b7d0: 74 68 65 20 3c 61 20 68 72 65 66 3d 22 76 74 61  the <a href="vta
b7e0: 62 2e 68 74 6d 6c 23 78 64 69 73 63 6f 6e 6e 65  b.html#xdisconne
b7f0: 63 74 22 3e 78 44 69 73 63 6f 6e 6e 65 63 74 3c  ct">xDisconnect<
b800: 2f 61 3e 20 61 6e 64 20 78 44 65 73 74 72 6f 79  /a> and xDestroy
b810: 20 6d 65 74 68 6f 64 73 20 74 6f 20 62 65 0a 74   methods to be.t
b820: 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
b830: 20 69 66 20 74 68 61 74 20 6d 61 6b 65 73 20 73   if that makes s
b840: 65 6e 73 65 20 66 6f 72 20 74 68 65 20 70 61 72  ense for the par
b850: 74 69 63 75 6c 61 72 20 76 69 72 74 75 61 6c 20  ticular virtual 
b860: 74 61 62 6c 65 2e 0a 0a 3c 61 20 6e 61 6d 65 3d  table...<a name=
b870: 22 78 6f 70 65 6e 22 3e 3c 2f 61 3e 0a 0a 3c 68  "xopen"></a>..<h
b880: 33 3e 32 2e 36 20 54 68 65 20 78 4f 70 65 6e 20  3>2.6 The xOpen 
b890: 4d 65 74 68 6f 64 3c 2f 68 33 3e 0a 0a 3c 62 6c  Method</h3>..<bl
b8a0: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 20  ockquote><pre>. 
b8b0: 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71   int (*xOpen)(sq
b8c0: 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
b8d0: 62 2c 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  b, sqlite3_vtab_
b8e0: 63 75 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f  cursor **ppCurso
b8f0: 72 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  r);.</pre></bloc
b900: 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68 65 20  kquote>..<p>The 
b910: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 63 72 65  xOpen method cre
b920: 61 74 65 73 20 61 20 6e 65 77 20 63 75 72 73 6f  ates a new curso
b930: 72 20 75 73 65 64 20 66 6f 72 20 61 63 63 65 73  r used for acces
b940: 73 69 6e 67 20 28 72 65 61 64 20 61 6e 64 2f 6f  sing (read and/o
b950: 72 0a 77 72 69 74 69 6e 67 29 20 61 20 76 69 72  r.writing) a vir
b960: 74 75 61 6c 20 74 61 62 6c 65 2e 20 20 41 20 73  tual table.  A s
b970: 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61  uccessful invoca
b980: 74 69 6f 6e 20 6f 66 20 74 68 69 73 20 6d 65 74  tion of this met
b990: 68 6f 64 20 0a 77 69 6c 6c 20 61 6c 6c 6f 63 61  hod .will alloca
b9a0: 74 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 66 6f  te the memory fo
b9b0: 72 20 74 68 65 20 3c 61 20 68 72 65 66 3d 22 63  r the <a href="c
b9c0: 33 72 65 66 2f 76 74 61 62 5f 63 75 72 73 6f 72  3ref/vtab_cursor
b9d0: 2e 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 76  .html">sqlite3_v
b9e0: 74 61 62 5f 63 75 72 73 6f 72 3c 2f 61 3e 20 28  tab_cursor</a> (
b9f0: 6f 72 20 61 20 73 75 62 63 6c 61 73 73 29 2c 0a  or a subclass),.
ba00: 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6e  initialize the n
ba10: 65 77 20 6f 62 6a 65 63 74 2c 20 61 6e 64 20 6d  ew object, and m
ba20: 61 6b 65 20 2a 70 70 43 75 72 73 6f 72 20 70 6f  ake *ppCursor po
ba30: 69 6e 74 20 74 6f 20 74 68 65 20 6e 65 77 20 6f  int to the new o
ba40: 62 6a 65 63 74 2e 0a 54 68 65 20 73 75 63 63 65  bject..The succe
ba50: 73 73 66 75 6c 20 63 61 6c 6c 20 74 68 65 6e 20  ssful call then 
ba60: 72 65 74 75 72 6e 73 20 3c 61 20 68 72 65 66 3d  returns <a href=
ba70: 22 72 65 73 63 6f 64 65 2e 68 74 6d 6c 23 6f 6b  "rescode.html#ok
ba80: 22 3e 53 51 4c 49 54 45 5f 4f 4b 3c 2f 61 3e 2e  ">SQLITE_OK</a>.
ba90: 0a 0a 3c 70 3e 46 6f 72 20 65 76 65 72 79 20 73  ..<p>For every s
baa0: 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
bab0: 6f 20 74 68 69 73 20 6d 65 74 68 6f 64 2c 20 74  o this method, t
bac0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77  he SQLite core w
bad0: 69 6c 6c 0a 6c 61 74 65 72 20 69 6e 76 6f 6b 65  ill.later invoke
bae0: 20 74 68 65 20 3c 61 20 68 72 65 66 3d 22 76 74   the <a href="vt
baf0: 61 62 2e 68 74 6d 6c 23 78 63 6c 6f 73 65 22 3e  ab.html#xclose">
bb00: 78 43 6c 6f 73 65 3c 2f 61 3e 20 6d 65 74 68 6f  xClose</a> metho
bb10: 64 20 74 6f 20 64 65 73 74 72 6f 79 20 0a 74 68  d to destroy .th
bb20: 65 20 61 6c 6c 6f 63 61 74 65 64 20 63 75 72 73  e allocated curs
bb30: 6f 72 2e 0a 0a 3c 70 3e 54 68 65 20 78 4f 70 65  or...<p>The xOpe
bb40: 6e 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f  n method need no
bb50: 74 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  t initialize the
bb60: 20 70 56 74 61 62 20 66 69 65 6c 64 20 6f 66 20   pVtab field of 
bb70: 74 68 65 0a 3c 61 20 68 72 65 66 3d 22 63 33 72  the.<a href="c3r
bb80: 65 66 2f 76 74 61 62 5f 63 75 72 73 6f 72 2e 68  ef/vtab_cursor.h
bb90: 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 76 74 61  tml">sqlite3_vta
bba0: 62 5f 63 75 72 73 6f 72 3c 2f 61 3e 20 73 74 72  b_cursor</a> str
bbb0: 75 63 74 75 72 65 2e 20 20 54 68 65 20 53 51 4c  ucture.  The SQL
bbc0: 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 74 61  ite core will ta
bbd0: 6b 65 20 63 61 72 65 0a 6f 66 20 74 68 61 74 20  ke care.of that 
bbe0: 63 68 6f 72 65 20 61 75 74 6f 6d 61 74 69 63 61  chore automatica
bbf0: 6c 6c 79 2e 0a 0a 3c 70 3e 41 20 76 69 72 74 75  lly...<p>A virtu
bc00: 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  al table impleme
bc10: 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  ntation must be 
bc20: 61 62 6c 65 20 74 6f 20 73 75 70 70 6f 72 74 20  able to support 
bc30: 61 6e 20 61 72 62 69 74 72 61 72 79 0a 6e 75 6d  an arbitrary.num
bc40: 62 65 72 20 6f 66 20 73 69 6d 75 6c 74 61 6e 65  ber of simultane
bc50: 6f 75 73 6c 79 20 6f 70 65 6e 20 63 75 72 73 6f  ously open curso
bc60: 72 73 2e 0a 0a 3c 70 3e 57 68 65 6e 20 69 6e 69  rs...<p>When ini
bc70: 74 69 61 6c 6c 79 20 6f 70 65 6e 65 64 2c 20 74  tially opened, t
bc80: 68 65 20 63 75 72 73 6f 72 20 69 73 20 69 6e 20  he cursor is in 
bc90: 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 73 74 61  an undefined sta
bca0: 74 65 2e 0a 54 68 65 20 53 51 4c 69 74 65 20 63  te..The SQLite c
bcb0: 6f 72 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  ore will invoke 
bcc0: 74 68 65 20 3c 61 20 68 72 65 66 3d 22 76 74 61  the <a href="vta
bcd0: 62 2e 68 74 6d 6c 23 78 66 69 6c 74 65 72 22 3e  b.html#xfilter">
bce0: 78 46 69 6c 74 65 72 3c 2f 61 3e 20 6d 65 74 68  xFilter</a> meth
bcf0: 6f 64 0a 6f 6e 20 74 68 65 20 63 75 72 73 6f 72  od.on the cursor
bd00: 20 70 72 69 6f 72 20 74 6f 20 61 6e 79 20 61 74   prior to any at
bd10: 74 65 6d 70 74 20 74 6f 20 70 6f 73 69 74 69 6f  tempt to positio
bd20: 6e 20 6f 72 20 72 65 61 64 20 66 72 6f 6d 20 74  n or read from t
bd30: 68 65 20 63 75 72 73 6f 72 2e 0a 0a 3c 70 3e 54  he cursor...<p>T
bd40: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
bd50: 69 73 20 72 65 71 75 69 72 65 64 20 66 6f 72 20  is required for 
bd60: 65 76 65 72 79 20 76 69 72 74 75 61 6c 20 74 61  every virtual ta
bd70: 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
bd80: 6f 6e 2e 0a 0a 3c 61 20 6e 61 6d 65 3d 22 78 63  on...<a name="xc
bd90: 6c 6f 73 65 22 3e 3c 2f 61 3e 0a 0a 3c 68 33 3e  lose"></a>..<h3>
bda0: 32 2e 37 20 54 68 65 20 78 43 6c 6f 73 65 20 4d  2.7 The xClose M
bdb0: 65 74 68 6f 64 3c 2f 68 33 3e 0a 0a 3c 62 6c 6f  ethod</h3>..<blo
bdc0: 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 20 20  ckquote><pre>.  
bdd0: 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
bde0: 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
bdf0: 72 2a 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  r*);.</pre></blo
be00: 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68 65  ckquote>..<p>The
be10: 20 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 20 63   xClose method c
be20: 6c 6f 73 65 73 20 61 20 63 75 72 73 6f 72 20 70  loses a cursor p
be30: 72 65 76 69 6f 75 73 6c 79 20 6f 70 65 6e 65 64  reviously opened
be40: 20 62 79 20 0a 3c 61 20 68 72 65 66 3d 22 76 74   by .<a href="vt
be50: 61 62 2e 68 74 6d 6c 23 78 6f 70 65 6e 22 3e 78  ab.html#xopen">x
be60: 4f 70 65 6e 3c 2f 61 3e 2e 20 0a 54 68 65 20 53  Open</a>. .The S
be70: 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20  QLite core will 
be80: 61 6c 77 61 79 73 20 63 61 6c 6c 20 78 43 6c 6f  always call xClo
be90: 73 65 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  se once for each
bea0: 20 63 75 72 73 6f 72 20 6f 70 65 6e 65 64 20 0a   cursor opened .
beb0: 75 73 69 6e 67 20 78 4f 70 65 6e 2e 0a 0a 3c 70  using xOpen...<p
bec0: 3e 54 68 69 73 20 6d 65 74 68 6f 64 20 6d 75 73  >This method mus
bed0: 74 20 72 65 6c 65 61 73 65 20 61 6c 6c 20 72 65  t release all re
bee0: 73 6f 75 72 63 65 73 20 61 6c 6c 6f 63 61 74 65  sources allocate
bef0: 64 20 62 79 20 74 68 65 0a 63 6f 72 72 65 73 70  d by the.corresp
bf00: 6f 6e 64 69 6e 67 20 78 4f 70 65 6e 20 63 61 6c  onding xOpen cal
bf10: 6c 2e 20 54 68 65 20 72 6f 75 74 69 6e 65 20 77  l. The routine w
bf20: 69 6c 6c 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  ill not be calle
bf30: 64 20 61 67 61 69 6e 20 65 76 65 6e 20 69 66 20  d again even if 
bf40: 69 74 0a 72 65 74 75 72 6e 73 20 61 6e 20 65 72  it.returns an er
bf50: 72 6f 72 2e 20 20 54 68 65 20 53 51 4c 69 74 65  ror.  The SQLite
bf60: 20 63 6f 72 65 20 77 69 6c 6c 20 6e 6f 74 20 75   core will not u
bf70: 73 65 20 74 68 65 0a 3c 61 20 68 72 65 66 3d 22  se the.<a href="
bf80: 63 33 72 65 66 2f 76 74 61 62 5f 63 75 72 73 6f  c3ref/vtab_curso
bf90: 72 2e 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f  r.html">sqlite3_
bfa0: 76 74 61 62 5f 63 75 72 73 6f 72 3c 2f 61 3e 20  vtab_cursor</a> 
bfb0: 61 67 61 69 6e 20 61 66 74 65 72 20 69 74 20 68  again after it h
bfc0: 61 73 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a  as been closed..
bfd0: 0a 3c 70 3e 54 68 65 20 78 43 6c 6f 73 65 20 6d  .<p>The xClose m
bfe0: 65 74 68 6f 64 20 69 73 20 72 65 71 75 69 72 65  ethod is require
bff0: 64 20 66 6f 72 20 65 76 65 72 79 20 76 69 72 74  d for every virt
c000: 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
c010: 65 6e 74 61 74 69 6f 6e 2e 0a 0a 3c 61 20 6e 61  entation...<a na
c020: 6d 65 3d 22 78 65 6f 66 22 3e 3c 2f 61 3e 0a 0a  me="xeof"></a>..
c030: 3c 68 33 3e 32 2e 38 20 54 68 65 20 78 45 6f 66  <h3>2.8 The xEof
c040: 20 4d 65 74 68 6f 64 3c 2f 68 33 3e 0a 0a 3c 62   Method</h3>..<b
c050: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
c060: 20 20 69 6e 74 20 28 2a 78 45 6f 66 29 28 73 71    int (*xEof)(sq
c070: 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
c080: 72 2a 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  r*);.</pre></blo
c090: 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68 65  ckquote>..<p>The
c0a0: 20 78 45 6f 66 20 6d 65 74 68 6f 64 20 6d 75 73   xEof method mus
c0b0: 74 20 72 65 74 75 72 6e 20 66 61 6c 73 65 20 28  t return false (
c0c0: 7a 65 72 6f 29 20 69 66 20 74 68 65 20 73 70 65  zero) if the spe
c0d0: 63 69 66 69 65 64 20 63 75 72 73 6f 72 20 0a 63  cified cursor .c
c0e0: 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 73 20  urrently points 
c0f0: 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 20 6f  to a valid row o
c100: 66 20 64 61 74 61 2c 20 6f 72 20 74 72 75 65 20  f data, or true 
c110: 28 6e 6f 6e 2d 7a 65 72 6f 29 20 6f 74 68 65 72  (non-zero) other
c120: 77 69 73 65 2e 20 0a 54 68 69 73 20 6d 65 74 68  wise. .This meth
c130: 6f 64 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20  od is called by 
c140: 74 68 65 20 53 51 4c 20 65 6e 67 69 6e 65 20 69  the SQL engine i
c150: 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72  mmediately after
c160: 20 65 61 63 68 20 0a 3c 61 20 68 72 65 66 3d 22   each .<a href="
c170: 76 74 61 62 2e 68 74 6d 6c 23 78 66 69 6c 74 65  vtab.html#xfilte
c180: 72 22 3e 78 46 69 6c 74 65 72 3c 2f 61 3e 20 61  r">xFilter</a> a
c190: 6e 64 20 3c 61 20 68 72 65 66 3d 22 76 74 61 62  nd <a href="vtab
c1a0: 2e 68 74 6d 6c 23 78 6e 65 78 74 22 3e 78 4e 65  .html#xnext">xNe
c1b0: 78 74 3c 2f 61 3e 20 69 6e 76 6f 63 61 74 69 6f  xt</a> invocatio
c1c0: 6e 2e 0a 0a 3c 70 3e 54 68 65 20 78 45 6f 66 20  n...<p>The xEof 
c1d0: 6d 65 74 68 6f 64 20 69 73 20 72 65 71 75 69 72  method is requir
c1e0: 65 64 20 66 6f 72 20 65 76 65 72 79 20 76 69 72  ed for every vir
c1f0: 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65  tual table imple
c200: 6d 65 6e 74 61 74 69 6f 6e 2e 0a 0a 3c 61 20 6e  mentation...<a n
c210: 61 6d 65 3d 22 78 66 69 6c 74 65 72 22 3e 3c 2f  ame="xfilter"></
c220: 61 3e 0a 0a 3c 68 33 3e 32 2e 39 20 54 68 65 20  a>..<h3>2.9 The 
c230: 78 46 69 6c 74 65 72 20 4d 65 74 68 6f 64 3c 2f  xFilter Method</
c240: 68 33 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65  h3>..<blockquote
c250: 3e 3c 70 72 65 3e 0a 20 20 69 6e 74 20 28 2a 78  ><pre>.  int (*x
c260: 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33 5f  Filter)(sqlite3_
c270: 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e  vtab_cursor*, in
c280: 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20  t idxNum, const 
c290: 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a 20 20  char *idxStr,.  
c2a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
c2b0: 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65 33 5f  t argc, sqlite3_
c2c0: 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a 3c  value **argv);.<
c2d0: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
c2e0: 65 3e 0a 0a 3c 70 3e 54 68 69 73 20 6d 65 74 68  e>..<p>This meth
c2f0: 6f 64 20 62 65 67 69 6e 73 20 61 20 73 65 61 72  od begins a sear
c300: 63 68 20 6f 66 20 61 20 76 69 72 74 75 61 6c 20  ch of a virtual 
c310: 74 61 62 6c 65 2e 20 0a 54 68 65 20 66 69 72 73  table. .The firs
c320: 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  t argument is a 
c330: 63 75 72 73 6f 72 20 6f 70 65 6e 65 64 20 62 79  cursor opened by
c340: 20 3c 61 20 68 72 65 66 3d 22 76 74 61 62 2e 68   <a href="vtab.h
c350: 74 6d 6c 23 78 6f 70 65 6e 22 3e 78 4f 70 65 6e  tml#xopen">xOpen
c360: 3c 2f 61 3e 2e 20 0a 54 68 65 20 6e 65 78 74 20  </a>. .The next 
c370: 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 64 65  two arguments de
c380: 66 69 6e 65 20 61 20 70 61 72 74 69 63 75 6c 61  fine a particula
c390: 72 20 73 65 61 72 63 68 20 69 6e 64 65 78 20 70  r search index p
c3a0: 72 65 76 69 6f 75 73 6c 79 20 0a 63 68 6f 73 65  reviously .chose
c3b0: 6e 20 62 79 20 3c 61 20 68 72 65 66 3d 22 76 74  n by <a href="vt
c3c0: 61 62 2e 68 74 6d 6c 23 78 62 65 73 74 69 6e 64  ab.html#xbestind
c3d0: 65 78 22 3e 78 42 65 73 74 49 6e 64 65 78 3c 2f  ex">xBestIndex</
c3e0: 61 3e 2e 20 54 68 65 20 73 70 65 63 69 66 69 63  a>. The specific
c3f0: 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 69 64 78   meanings of idx
c400: 4e 75 6d 20 61 6e 64 20 69 64 78 53 74 72 20 0a  Num and idxStr .
c410: 61 72 65 20 75 6e 69 6d 70 6f 72 74 61 6e 74 20  are unimportant 
c420: 61 73 20 6c 6f 6e 67 20 61 73 20 78 46 69 6c 74  as long as xFilt
c430: 65 72 20 61 6e 64 20 78 42 65 73 74 49 6e 64 65  er and xBestInde
c440: 78 20 61 67 72 65 65 20 6f 6e 20 77 68 61 74 20  x agree on what 
c450: 0a 74 68 61 74 20 6d 65 61 6e 69 6e 67 20 69 73  .that meaning is
c460: 2e 0a 0a 3c 70 3e 54 68 65 20 78 42 65 73 74 49  ...<p>The xBestI
c470: 6e 64 65 78 20 66 75 6e 63 74 69 6f 6e 20 6d 61  ndex function ma
c480: 79 20 68 61 76 65 20 72 65 71 75 65 73 74 65 64  y have requested
c490: 20 74 68 65 20 76 61 6c 75 65 73 20 6f 66 20 0a   the values of .
c4a0: 63 65 72 74 61 69 6e 20 65 78 70 72 65 73 73 69  certain expressi
c4b0: 6f 6e 73 20 75 73 69 6e 67 20 74 68 65 20 61 43  ons using the aC
c4c0: 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d  onstraintUsage[]
c4d0: 2e 61 72 67 76 49 6e 64 65 78 20 76 61 6c 75 65  .argvIndex value
c4e0: 73 20 0a 6f 66 20 74 68 65 20 3c 61 20 68 72 65  s .of the <a hre
c4f0: 66 3d 22 63 33 72 65 66 2f 69 6e 64 65 78 5f 69  f="c3ref/index_i
c500: 6e 66 6f 2e 68 74 6d 6c 22 3e 73 71 6c 69 74 65  nfo.html">sqlite
c510: 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3c 2f 61 3e  3_index_info</a>
c520: 20 73 74 72 75 63 74 75 72 65 2e 20 0a 54 68 6f   structure. .Tho
c530: 73 65 20 76 61 6c 75 65 73 20 61 72 65 20 70 61  se values are pa
c540: 73 73 65 64 20 74 6f 20 78 46 69 6c 74 65 72 20  ssed to xFilter 
c550: 75 73 69 6e 67 20 74 68 65 20 61 72 67 63 20 61  using the argc a
c560: 6e 64 20 61 72 67 76 20 70 61 72 61 6d 65 74 65  nd argv paramete
c570: 72 73 2e 0a 0a 3c 70 3e 49 66 20 74 68 65 20 76  rs...<p>If the v
c580: 69 72 74 75 61 6c 20 74 61 62 6c 65 20 63 6f 6e  irtual table con
c590: 74 61 69 6e 73 20 6f 6e 65 20 6f 72 20 6d 6f 72  tains one or mor
c5a0: 65 20 72 6f 77 73 20 74 68 61 74 20 6d 61 74 63  e rows that matc
c5b0: 68 20 74 68 65 0a 73 65 61 72 63 68 20 63 72 69  h the.search cri
c5c0: 74 65 72 69 61 2c 20 74 68 65 6e 20 74 68 65 20  teria, then the 
c5d0: 63 75 72 73 6f 72 20 6d 75 73 74 20 62 65 20 6c  cursor must be l
c5e0: 65 66 74 20 70 6f 69 6e 74 20 61 74 20 74 68 65  eft point at the
c5f0: 20 66 69 72 73 74 20 72 6f 77 2e 0a 53 75 62 73   first row..Subs
c600: 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
c610: 3c 61 20 68 72 65 66 3d 22 76 74 61 62 2e 68 74  <a href="vtab.ht
c620: 6d 6c 23 78 65 6f 66 22 3e 78 45 6f 66 3c 2f 61  ml#xeof">xEof</a
c630: 3e 20 6d 75 73 74 20 72 65 74 75 72 6e 20 66 61  > must return fa
c640: 6c 73 65 20 28 7a 65 72 6f 29 2e 0a 49 66 20 74  lse (zero)..If t
c650: 68 65 72 65 20 61 72 65 20 6e 6f 20 72 6f 77 73  here are no rows
c660: 20 6d 61 74 63 68 2c 20 74 68 65 6e 20 74 68 65   match, then the
c670: 20 63 75 72 73 6f 72 20 6d 75 73 74 20 62 65 20   cursor must be 
c680: 6c 65 66 74 20 69 6e 20 61 20 73 74 61 74 65 20  left in a state 
c690: 0a 74 68 61 74 20 77 69 6c 6c 20 63 61 75 73 65  .that will cause
c6a0: 20 74 68 65 20 3c 61 20 68 72 65 66 3d 22 76 74   the <a href="vt
c6b0: 61 62 2e 68 74 6d 6c 23 78 65 6f 66 22 3e 78 45  ab.html#xeof">xE
c6c0: 6f 66 3c 2f 61 3e 20 74 6f 20 72 65 74 75 72 6e  of</a> to return
c6d0: 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29   true (non-zero)
c6e0: 2e 0a 54 68 65 20 53 51 4c 69 74 65 20 65 6e 67  ..The SQLite eng
c6f0: 69 6e 65 20 77 69 6c 6c 20 75 73 65 0a 74 68 65  ine will use.the
c700: 20 3c 61 20 68 72 65 66 3d 22 76 74 61 62 2e 68   <a href="vtab.h
c710: 74 6d 6c 23 78 63 6f 6c 75 6d 6e 22 3e 78 43 6f  tml#xcolumn">xCo
c720: 6c 75 6d 6e 3c 2f 61 3e 20 61 6e 64 20 3c 61 20  lumn</a> and <a 
c730: 68 72 65 66 3d 22 76 74 61 62 2e 68 74 6d 6c 23  href="vtab.html#
c740: 78 72 6f 77 69 64 22 3e 78 52 6f 77 69 64 3c 2f  xrowid">xRowid</
c750: 61 3e 20 6d 65 74 68 6f 64 73 20 74 6f 20 61 63  a> methods to ac
c760: 63 65 73 73 20 74 68 61 74 20 72 6f 77 20 63 6f  cess that row co
c770: 6e 74 65 6e 74 2e 0a 54 68 65 20 3c 61 20 68 72  ntent..The <a hr
c780: 65 66 3d 22 76 74 61 62 2e 68 74 6d 6c 23 78 6e  ef="vtab.html#xn
c790: 65 78 74 22 3e 78 4e 65 78 74 3c 2f 61 3e 20 6d  ext">xNext</a> m
c7a0: 65 74 68 6f 64 20 77 69 6c 6c 20 62 65 20 75 73  ethod will be us
c7b0: 65 64 20 74 6f 20 61 64 76 61 6e 63 65 20 74 6f  ed to advance to
c7c0: 20 74 68 65 20 6e 65 78 74 20 72 6f 77 2e 0a 0a   the next row...
c7d0: 3c 70 3e 54 68 69 73 20 6d 65 74 68 6f 64 20 6d  <p>This method m
c7e0: 75 73 74 20 72 65 74 75 72 6e 20 3c 61 20 68 72  ust return <a hr
c7f0: 65 66 3d 22 72 65 73 63 6f 64 65 2e 68 74 6d 6c  ef="rescode.html
c800: 23 6f 6b 22 3e 53 51 4c 49 54 45 5f 4f 4b 3c 2f  #ok">SQLITE_OK</
c810: 61 3e 20 69 66 20 73 75 63 63 65 73 73 66 75 6c  a> if successful
c820: 2c 20 6f 72 20 61 6e 20 73 71 6c 69 74 65 20 0a  , or an sqlite .
c830: 3c 61 20 68 72 65 66 3d 22 72 65 73 63 6f 64 65  <a href="rescode
c840: 2e 68 74 6d 6c 22 3e 65 72 72 6f 72 20 63 6f 64  .html">error cod
c850: 65 3c 2f 61 3e 20 69 66 20 61 6e 20 65 72 72 6f  e</a> if an erro
c860: 72 20 6f 63 63 75 72 73 2e 0a 0a 3c 70 3e 54 68  r occurs...<p>Th
c870: 65 20 78 46 69 6c 74 65 72 20 6d 65 74 68 6f 64  e xFilter method
c880: 20 69 73 20 72 65 71 75 69 72 65 64 20 66 6f 72   is required for
c890: 20 65 76 65 72 79 20 76 69 72 74 75 61 6c 20 74   every virtual t
c8a0: 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
c8b0: 69 6f 6e 2e 0a 0a 3c 61 20 6e 61 6d 65 3d 22 78  ion...<a name="x
c8c0: 6e 65 78 74 22 3e 3c 2f 61 3e 0a 0a 3c 68 33 3e  next"></a>..<h3>
c8d0: 32 2e 31 30 20 54 68 65 20 78 4e 65 78 74 20 4d  2.10 The xNext M
c8e0: 65 74 68 6f 64 3c 2f 68 33 3e 0a 0a 3c 62 6c 6f  ethod</h3>..<blo
c8f0: 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 20 20  ckquote><pre>.  
c900: 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 73 71 6c  int (*xNext)(sql
c910: 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
c920: 2a 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  *);.</pre></bloc
c930: 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68 65 20  kquote>..<p>The 
c940: 78 4e 65 78 74 20 6d 65 74 68 6f 64 20 61 64 76  xNext method adv
c950: 61 6e 63 65 73 20 61 20 3c 61 20 68 72 65 66 3d  ances a <a href=
c960: 22 63 33 72 65 66 2f 76 74 61 62 5f 63 75 72 73  "c3ref/vtab_curs
c970: 6f 72 2e 68 74 6d 6c 22 3e 76 69 72 74 75 61 6c  or.html">virtual
c980: 20 74 61 62 6c 65 20 63 75 72 73 6f 72 3c 2f 61   table cursor</a
c990: 3e 0a 74 6f 20 74 68 65 20 6e 65 78 74 20 72 6f  >.to the next ro
c9a0: 77 20 6f 66 20 61 20 72 65 73 75 6c 74 20 73 65  w of a result se
c9b0: 74 20 69 6e 69 74 69 61 74 65 64 20 62 79 20 3c  t initiated by <
c9c0: 61 20 68 72 65 66 3d 22 76 74 61 62 2e 68 74 6d  a href="vtab.htm
c9d0: 6c 23 78 66 69 6c 74 65 72 22 3e 78 46 69 6c 74  l#xfilter">xFilt
c9e0: 65 72 3c 2f 61 3e 2e 20 0a 49 66 20 74 68 65 20  er</a>. .If the 
c9f0: 63 75 72 73 6f 72 20 69 73 20 61 6c 72 65 61 64  cursor is alread
ca00: 79 20 70 6f 69 6e 74 69 6e 67 20 61 74 20 74 68  y pointing at th
ca10: 65 20 6c 61 73 74 20 72 6f 77 20 77 68 65 6e 20  e last row when 
ca20: 74 68 69 73 20 0a 72 6f 75 74 69 6e 65 20 69 73  this .routine is
ca30: 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 74 68   called, then th
ca40: 65 20 63 75 72 73 6f 72 20 6e 6f 20 6c 6f 6e 67  e cursor no long
ca50: 65 72 20 70 6f 69 6e 74 73 20 74 6f 20 76 61 6c  er points to val
ca60: 69 64 20 0a 64 61 74 61 20 61 6e 64 20 61 20 73  id .data and a s
ca70: 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
ca80: 6f 20 74 68 65 20 3c 61 20 68 72 65 66 3d 22 76  o the <a href="v
ca90: 74 61 62 2e 68 74 6d 6c 23 78 65 6f 66 22 3e 78  tab.html#xeof">x
caa0: 45 6f 66 3c 2f 61 3e 20 6d 65 74 68 6f 64 20 6d  Eof</a> method m
cab0: 75 73 74 20 72 65 74 75 72 6e 20 74 72 75 65 20  ust return true 
cac0: 28 6e 6f 6e 2d 7a 65 72 6f 29 2e 20 0a 49 66 20  (non-zero). .If 
cad0: 74 68 65 20 63 75 72 73 6f 72 20 69 73 20 73 75  the cursor is su
cae0: 63 63 65 73 73 66 75 6c 6c 79 20 61 64 76 61 6e  ccessfully advan
caf0: 63 65 64 20 74 6f 20 61 6e 6f 74 68 65 72 20 72  ced to another r
cb00: 6f 77 20 6f 66 20 63 6f 6e 74 65 6e 74 2c 20 74  ow of content, t
cb10: 68 65 6e 0a 73 75 62 73 65 71 75 65 6e 74 20 63  hen.subsequent c
cb20: 61 6c 6c 73 20 74 6f 20 3c 61 20 68 72 65 66 3d  alls to <a href=
cb30: 22 76 74 61 62 2e 68 74 6d 6c 23 78 65 6f 66 22  "vtab.html#xeof"
cb40: 3e 78 45 6f 66 3c 2f 61 3e 20 6d 75 73 74 20 72  >xEof</a> must r
cb50: 65 74 75 72 6e 20 66 61 6c 73 65 20 28 7a 65 72  eturn false (zer
cb60: 6f 29 2e 0a 0a 3c 70 3e 54 68 69 73 20 6d 65 74  o)...<p>This met
cb70: 68 6f 64 20 6d 75 73 74 20 72 65 74 75 72 6e 20  hod must return 
cb80: 3c 61 20 68 72 65 66 3d 22 72 65 73 63 6f 64 65  <a href="rescode
cb90: 2e 68 74 6d 6c 23 6f 6b 22 3e 53 51 4c 49 54 45  .html#ok">SQLITE
cba0: 5f 4f 4b 3c 2f 61 3e 20 69 66 20 73 75 63 63 65  _OK</a> if succe
cbb0: 73 73 66 75 6c 2c 20 6f 72 20 61 6e 20 73 71 6c  ssful, or an sql
cbc0: 69 74 65 20 0a 3c 61 20 68 72 65 66 3d 22 72 65  ite .<a href="re
cbd0: 73 63 6f 64 65 2e 68 74 6d 6c 22 3e 65 72 72 6f  scode.html">erro
cbe0: 72 20 63 6f 64 65 3c 2f 61 3e 20 69 66 20 61 6e  r code</a> if an
cbf0: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 0a   error occurs...
cc00: 3c 70 3e 54 68 65 20 78 4e 65 78 74 20 6d 65 74  <p>The xNext met
cc10: 68 6f 64 20 69 73 20 72 65 71 75 69 72 65 64 20  hod is required 
cc20: 66 6f 72 20 65 76 65 72 79 20 76 69 72 74 75 61  for every virtua
cc30: 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  l table implemen
cc40: 74 61 74 69 6f 6e 2e 0a 0a 3c 61 20 6e 61 6d 65  tation...<a name
cc50: 3d 22 78 63 6f 6c 75 6d 6e 22 3e 3c 2f 61 3e 0a  ="xcolumn"></a>.
cc60: 0a 3c 68 33 3e 32 2e 31 31 20 54 68 65 20 78 43  .<h3>2.11 The xC
cc70: 6f 6c 75 6d 6e 20 4d 65 74 68 6f 64 3c 2f 68 33  olumn Method</h3
cc80: 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  >..<blockquote><
cc90: 70 72 65 3e 0a 20 20 69 6e 74 20 28 2a 78 43 6f  pre>.  int (*xCo
cca0: 6c 75 6d 6e 29 28 73 71 6c 69 74 65 33 5f 76 74  lumn)(sqlite3_vt
ccb0: 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69  ab_cursor*, sqli
ccc0: 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
ccd0: 74 20 4e 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c  t N);.</pre></bl
cce0: 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68  ockquote>..<p>Th
ccf0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 69 6e  e SQLite core in
cd00: 76 6f 6b 65 73 20 74 68 69 73 20 6d 65 74 68 6f  vokes this metho
cd10: 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  d in order to fi
cd20: 6e 64 20 74 68 65 20 76 61 6c 75 65 20 66 6f 72  nd the value for
cd30: 20 0a 74 68 65 20 4e 2d 74 68 20 63 6f 6c 75 6d   .the N-th colum
cd40: 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
cd50: 20 72 6f 77 2e 20 4e 20 69 73 20 7a 65 72 6f 2d   row. N is zero-
cd60: 62 61 73 65 64 20 73 6f 20 74 68 65 20 66 69 72  based so the fir
cd70: 73 74 20 63 6f 6c 75 6d 6e 20 0a 69 73 20 6e 75  st column .is nu
cd80: 6d 62 65 72 65 64 20 30 2e 20 0a 54 68 65 20 78  mbered 0. .The x
cd90: 43 6f 6c 75 6d 6e 20 6d 65 74 68 6f 64 20 6d 61  Column method ma
cda0: 79 20 72 65 74 75 72 6e 20 69 74 73 20 72 65 73  y return its res
cdb0: 75 6c 74 20 62 61 63 6b 20 74 6f 20 53 51 4c 69  ult back to SQLi
cdc0: 74 65 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20  te using one of 
cdd0: 74 68 65 0a 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e  the.following in
cde0: 74 65 72 66 61 63 65 3a 0a 0a 3c 70 3e 0a 3c 75  terface:..<p>.<u
cdf0: 6c 3e 0a 3c 6c 69 3e 20 3c 61 20 68 72 65 66 3d  l>.<li> <a href=
ce00: 22 63 33 72 65 66 2f 72 65 73 75 6c 74 5f 62 6c  "c3ref/result_bl
ce10: 6f 62 2e 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33  ob.html">sqlite3
ce20: 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 3c 2f  _result_blob()</
ce30: 61 3e 0a 3c 6c 69 3e 20 3c 61 20 68 72 65 66 3d  a>.<li> <a href=
ce40: 22 63 33 72 65 66 2f 72 65 73 75 6c 74 5f 62 6c  "c3ref/result_bl
ce50: 6f 62 2e 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33  ob.html">sqlite3
ce60: 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29  _result_double()
ce70: 3c 2f 61 3e 0a 3c 6c 69 3e 20 3c 61 20 68 72 65  </a>.<li> <a hre
ce80: 66 3d 22 63 33 72 65 66 2f 72 65 73 75 6c 74 5f  f="c3ref/result_
ce90: 62 6c 6f 62 2e 68 74 6d 6c 22 3e 73 71 6c 69 74  blob.html">sqlit
cea0: 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 3c  e3_result_int()<
ceb0: 2f 61 3e 0a 3c 6c 69 3e 20 3c 61 20 68 72 65 66  /a>.<li> <a href
cec0: 3d 22 63 33 72 65 66 2f 72 65 73 75 6c 74 5f 62  ="c3ref/result_b
ced0: 6c 6f 62 2e 68 74 6d 6c 22 3e 73 71 6c 69 74 65  lob.html">sqlite
cee0: 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29  3_result_int64()
cef0: 3c 2f 61 3e 0a 3c 6c 69 3e 20 3c 61 20 68 72 65  </a>.<li> <a hre
cf00: 66 3d 22 63 33 72 65 66 2f 72 65 73 75 6c 74 5f  f="c3ref/result_
cf10: 62 6c 6f 62 2e 68 74 6d 6c 22 3e 73 71 6c 69 74  blob.html">sqlit
cf20: 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29  e3_result_null()
cf30: 3c 2f 61 3e 0a 3c 6c 69 3e 20 3c 61 20 68 72 65  </a>.<li> <a hre
cf40: 66 3d 22 63 33 72 65 66 2f 72 65 73 75 6c 74 5f  f="c3ref/result_
cf50: 62 6c 6f 62 2e 68 74 6d 6c 22 3e 73 71 6c 69 74  blob.html">sqlit
cf60: 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29  e3_result_text()
cf70: 3c 2f 61 3e 0a 3c 6c 69 3e 20 3c 61 20 68 72 65  </a>.<li> <a hre
cf80: 66 3d 22 63 33 72 65 66 2f 72 65 73 75 6c 74 5f  f="c3ref/result_
cf90: 62 6c 6f 62 2e 68 74 6d 6c 22 3e 73 71 6c 69 74  blob.html">sqlit
cfa0: 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
cfb0: 28 29 3c 2f 61 3e 0a 3c 6c 69 3e 20 3c 61 20 68  ()</a>.<li> <a h
cfc0: 72 65 66 3d 22 63 33 72 65 66 2f 72 65 73 75 6c  ref="c3ref/resul
cfd0: 74 5f 62 6c 6f 62 2e 68 74 6d 6c 22 3e 73 71 6c  t_blob.html">sql
cfe0: 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
cff0: 31 36 6c 65 28 29 3c 2f 61 3e 0a 3c 6c 69 3e 20  16le()</a>.<li> 
d000: 3c 61 20 68 72 65 66 3d 22 63 33 72 65 66 2f 72  <a href="c3ref/r
d010: 65 73 75 6c 74 5f 62 6c 6f 62 2e 68 74 6d 6c 22  esult_blob.html"
d020: 3e 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  >sqlite3_result_
d030: 74 65 78 74 31 36 62 65 28 29 3c 2f 61 3e 0a 3c  text16be()</a>.<
d040: 6c 69 3e 20 3c 61 20 68 72 65 66 3d 22 63 33 72  li> <a href="c3r
d050: 65 66 2f 72 65 73 75 6c 74 5f 62 6c 6f 62 2e 68  ef/result_blob.h
d060: 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 72 65 73  tml">sqlite3_res
d070: 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 3c 2f  ult_zeroblob()</
d080: 61 3e 0a 3c 2f 75 6c 3e 0a 3c 2f 70 3e 0a 0a 3c  a>.</ul>.</p>..<
d090: 70 3e 49 66 20 74 68 65 20 78 43 6f 6c 75 6d 6e  p>If the xColumn
d0a0: 20 6d 65 74 68 6f 64 20 69 6d 70 6c 65 6d 65 6e   method implemen
d0b0: 74 61 74 69 6f 6e 20 63 61 6c 6c 73 20 6e 6f 6e  tation calls non
d0c0: 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  e of the functio
d0d0: 6e 73 20 61 62 6f 76 65 2c 0a 74 68 65 6e 20 74  ns above,.then t
d0e0: 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
d0f0: 63 6f 6c 75 6d 6e 20 64 65 66 61 75 6c 74 73 20  column defaults 
d100: 74 6f 20 61 6e 20 53 51 4c 20 4e 55 4c 4c 2e 0a  to an SQL NULL..
d110: 0a 3c 70 3e 54 6f 20 72 61 69 73 65 20 61 6e 20  .<p>To raise an 
d120: 65 72 72 6f 72 2c 20 74 68 65 20 78 43 6f 6c 75  error, the xColu
d130: 6d 6e 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64  mn method should
d140: 20 75 73 65 20 6f 6e 65 20 6f 66 20 74 68 65 20   use one of the 
d150: 72 65 73 75 6c 74 5f 74 65 78 74 28 29 20 0a 6d  result_text() .m
d160: 65 74 68 6f 64 73 20 74 6f 20 73 65 74 20 74 68  ethods to set th
d170: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
d180: 74 65 78 74 2c 20 74 68 65 6e 20 72 65 74 75 72  text, then retur
d190: 6e 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  n an appropriate
d1a0: 0a 3c 61 20 68 72 65 66 3d 22 72 65 73 63 6f 64  .<a href="rescod
d1b0: 65 2e 68 74 6d 6c 22 3e 65 72 72 6f 72 20 63 6f  e.html">error co
d1c0: 64 65 3c 2f 61 3e 2e 20 20 54 68 65 20 78 43 6f  de</a>.  The xCo
d1d0: 6c 75 6d 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74  lumn method must
d1e0: 20 72 65 74 75 72 6e 20 3c 61 20 68 72 65 66 3d   return <a href=
d1f0: 22 72 65 73 63 6f 64 65 2e 68 74 6d 6c 23 6f 6b  "rescode.html#ok
d200: 22 3e 53 51 4c 49 54 45 5f 4f 4b 3c 2f 61 3e 20  ">SQLITE_OK</a> 
d210: 6f 6e 20 73 75 63 63 65 73 73 2e 0a 0a 3c 70 3e  on success...<p>
d220: 54 68 65 20 78 43 6f 6c 75 6d 6e 20 6d 65 74 68  The xColumn meth
d230: 6f 64 20 69 73 20 72 65 71 75 69 72 65 64 20 66  od is required f
d240: 6f 72 20 65 76 65 72 79 20 76 69 72 74 75 61 6c  or every virtual
d250: 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74   table implement
d260: 61 74 69 6f 6e 2e 0a 0a 3c 61 20 6e 61 6d 65 3d  ation...<a name=
d270: 22 78 72 6f 77 69 64 22 3e 3c 2f 61 3e 0a 0a 3c  "xrowid"></a>..<
d280: 68 33 3e 32 2e 31 32 20 54 68 65 20 78 52 6f 77  h3>2.12 The xRow
d290: 69 64 20 4d 65 74 68 6f 64 3c 2f 68 33 3e 0a 0a  id Method</h3>..
d2a0: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
d2b0: 3e 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77 69 64  >.  int (*xRowid
d2c0: 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
d2d0: 75 72 73 6f 72 20 2a 70 43 75 72 2c 20 73 71 6c  ursor *pCur, sql
d2e0: 69 74 65 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69  ite_int64 *pRowi
d2f0: 64 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  d);.</pre></bloc
d300: 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 41 20 73 75  kquote>..<p>A su
d310: 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
d320: 69 6f 6e 20 6f 66 20 74 68 69 73 20 6d 65 74 68  ion of this meth
d330: 6f 64 20 77 69 6c 6c 20 63 61 75 73 65 20 2a 70  od will cause *p
d340: 52 6f 77 69 64 20 74 6f 20 62 65 0a 66 69 6c 6c  Rowid to be.fill
d350: 65 64 20 77 69 74 68 20 74 68 65 20 3c 61 20 68  ed with the <a h
d360: 72 65 66 3d 22 6c 61 6e 67 5f 63 72 65 61 74 65  ref="lang_create
d370: 74 61 62 6c 65 2e 68 74 6d 6c 23 72 6f 77 69 64  table.html#rowid
d380: 22 3e 72 6f 77 69 64 3c 2f 61 3e 20 6f 66 20 72  ">rowid</a> of r
d390: 6f 77 20 74 68 61 74 20 74 68 65 0a 3c 61 20 68  ow that the.<a h
d3a0: 72 65 66 3d 22 63 33 72 65 66 2f 76 74 61 62 5f  ref="c3ref/vtab_
d3b0: 63 75 72 73 6f 72 2e 68 74 6d 6c 22 3e 76 69 72  cursor.html">vir
d3c0: 74 75 61 6c 20 74 61 62 6c 65 20 63 75 72 73 6f  tual table curso
d3d0: 72 3c 2f 61 3e 20 70 43 75 72 20 69 73 20 63 75  r</a> pCur is cu
d3e0: 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 69 6e 67  rrently pointing
d3f0: 20 61 74 2e 0a 54 68 69 73 20 6d 65 74 68 6f 64   at..This method
d400: 20 72 65 74 75 72 6e 73 20 3c 61 20 68 72 65 66   returns <a href
d410: 3d 22 72 65 73 63 6f 64 65 2e 68 74 6d 6c 23 6f  ="rescode.html#o
d420: 6b 22 3e 53 51 4c 49 54 45 5f 4f 4b 3c 2f 61 3e  k">SQLITE_OK</a>
d430: 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 49 74 20   on success..It 
d440: 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f  returns an appro
d450: 70 72 69 61 74 65 20 3c 61 20 68 72 65 66 3d 22  priate <a href="
d460: 72 65 73 63 6f 64 65 2e 68 74 6d 6c 22 3e 65 72  rescode.html">er
d470: 72 6f 72 20 63 6f 64 65 3c 2f 61 3e 20 6f 6e 20  ror code</a> on 
d480: 66 61 69 6c 75 72 65 2e 3c 2f 70 3e 0a 0a 3c 70  failure.</p>..<p
d490: 3e 54 68 65 20 78 52 6f 77 69 64 20 6d 65 74 68  >The xRowid meth
d4a0: 6f 64 20 69 73 20 72 65 71 75 69 72 65 64 20 66  od is required f
d4b0: 6f 72 20 65 76 65 72 79 20 76 69 72 74 75 61 6c  or every virtual
d4c0: 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74   table implement
d4d0: 61 74 69 6f 6e 2e 0a 0a 3c 61 20 6e 61 6d 65 3d  ation...<a name=
d4e0: 22 78 75 70 64 61 74 65 22 3e 3c 2f 61 3e 0a 0a  "xupdate"></a>..
d4f0: 3c 68 33 3e 32 2e 31 33 20 54 68 65 20 78 55 70  <h3>2.13 The xUp
d500: 64 61 74 65 20 4d 65 74 68 6f 64 3c 2f 68 33 3e  date Method</h3>
d510: 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  ..<blockquote><p
d520: 72 65 3e 0a 20 20 69 6e 74 20 28 2a 78 55 70 64  re>.  int (*xUpd
d530: 61 74 65 29 28 0a 20 20 20 20 73 71 6c 69 74 65  ate)(.    sqlite
d540: 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 0a 20  3_vtab *pVTab,. 
d550: 20 20 20 69 6e 74 20 61 72 67 63 2c 0a 20 20 20     int argc,.   
d560: 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a   sqlite3_value *
d570: 2a 61 72 67 76 2c 0a 20 20 20 20 73 71 6c 69 74  *argv,.    sqlit
d580: 65 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69 64 0a  e_int64 *pRowid.
d590: 20 20 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f    );.</pre></blo
d5a0: 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 41 6c 6c  ckquote>..<p>All
d5b0: 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69   changes to a vi
d5c0: 72 74 75 61 6c 20 74 61 62 6c 65 20 61 72 65 20  rtual table are 
d5d0: 6d 61 64 65 20 75 73 69 6e 67 20 74 68 65 20 78  made using the x
d5e0: 55 70 64 61 74 65 20 6d 65 74 68 6f 64 2e 0a 54  Update method..T
d5f0: 68 69 73 20 6f 6e 65 20 6d 65 74 68 6f 64 20 63  his one method c
d600: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6e  an be used to in
d610: 73 65 72 74 2c 20 64 65 6c 65 74 65 2c 20 6f 72  sert, delete, or
d620: 20 75 70 64 61 74 65 2e 0a 0a 3c 70 3e 54 68 65   update...<p>The
d630: 20 61 72 67 63 20 70 61 72 61 6d 65 74 65 72 20   argc parameter 
d640: 73 70 65 63 69 66 69 65 73 20 74 68 65 20 6e 75  specifies the nu
d650: 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73 20  mber of entries 
d660: 69 6e 20 74 68 65 20 61 72 67 76 20 61 72 72 61  in the argv arra
d670: 79 2e 20 0a 54 68 65 20 76 61 6c 75 65 20 6f 66  y. .The value of
d680: 20 61 72 67 63 20 77 69 6c 6c 20 62 65 20 31 20   argc will be 1 
d690: 66 6f 72 20 61 20 70 75 72 65 20 64 65 6c 65 74  for a pure delet
d6a0: 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 72 20 4e  e operation or N
d6b0: 2b 32 20 66 6f 72 20 61 6e 20 69 6e 73 65 72 74  +2 for an insert
d6c0: 0a 6f 72 20 72 65 70 6c 61 63 65 20 6f 72 20 75  .or replace or u
d6d0: 70 64 61 74 65 20 77 68 65 72 65 20 4e 20 69 73  pdate where N is
d6e0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
d6f0: 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 74 61  olumns in the ta
d700: 62 6c 65 2e 20 20 0a 49 6e 20 74 68 65 20 70 72  ble.  .In the pr
d710: 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c  evious sentence,
d720: 20 4e 20 69 6e 63 6c 75 64 65 73 20 61 6e 79 20   N includes any 
d730: 68 69 64 64 65 6e 20 63 6f 6c 75 6d 6e 73 2e 0a  hidden columns..
d740: 0a 3c 70 3e 45 76 65 72 79 20 61 72 67 76 20 65  .<p>Every argv e
d750: 6e 74 72 79 20 77 69 6c 6c 20 68 61 76 65 20 61  ntry will have a
d760: 20 6e 6f 6e 2d 4e 55 4c 4c 20 76 61 6c 75 65 20   non-NULL value 
d770: 69 6e 20 43 20 62 75 74 20 6d 61 79 20 63 6f 6e  in C but may con
d780: 74 61 69 6e 20 74 68 65 20 0a 53 51 4c 20 76 61  tain the .SQL va
d790: 6c 75 65 20 4e 55 4c 4c 2e 20 20 49 6e 20 6f 74  lue NULL.  In ot
d7a0: 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 69 73  her words, it is
d7b0: 20 61 6c 77 61 79 73 20 74 72 75 65 20 74 68 61   always true tha
d7c0: 74 0a 3c 74 74 3e 61 72 67 76 26 23 39 31 3b 69  t.<tt>argv&#91;i
d7d0: 26 23 39 33 3b 21 3d 30 3c 2f 74 74 3e 20 66 6f  &#93;!=0</tt> fo
d7e0: 72 20 3c 62 3e 69 3c 2f 62 3e 20 62 65 74 77 65  r <b>i</b> betwe
d7f0: 65 6e 20 30 20 61 6e 64 20 3c 74 74 3e 61 72 67  en 0 and <tt>arg
d800: 63 2d 31 3c 2f 74 74 3e 2e 0a 48 6f 77 65 76 65  c-1</tt>..Howeve
d810: 72 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74  r, it might be t
d820: 68 65 20 63 61 73 65 20 74 68 61 74 0a 3c 74 74  he case that.<tt
d830: 3e 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  >sqlite3_value_t
d840: 79 70 65 28 61 72 67 76 26 23 39 31 3b 69 26 23  ype(argv&#91;i&#
d850: 39 33 3b 29 3d 3d 53 51 4c 49 54 45 5f 4e 55 4c  93;)==SQLITE_NUL
d860: 4c 3c 2f 74 74 3e 2e 0a 0a 3c 70 3e 54 68 65 20  L</tt>...<p>The 
d870: 61 72 67 76 5b 30 5d 20 70 61 72 61 6d 65 74 65  argv[0] paramete
d880: 72 20 69 73 20 74 68 65 20 3c 61 20 68 72 65 66  r is the <a href
d890: 3d 22 6c 61 6e 67 5f 63 72 65 61 74 65 74 61 62  ="lang_createtab
d8a0: 6c 65 2e 68 74 6d 6c 23 72 6f 77 69 64 22 3e 72  le.html#rowid">r
d8b0: 6f 77 69 64 3c 2f 61 3e 20 6f 66 20 61 20 72 6f  owid</a> of a ro
d8c0: 77 20 69 6e 20 74 68 65 20 76 69 72 74 75 61 6c  w in the virtual
d8d0: 20 74 61 62 6c 65 20 0a 74 6f 20 62 65 20 64 65   table .to be de
d8e0: 6c 65 74 65 64 2e 20 49 66 20 61 72 67 76 5b 30  leted. If argv[0
d8f0: 5d 20 69 73 20 61 6e 20 53 51 4c 20 4e 55 4c 4c  ] is an SQL NULL
d900: 2c 20 74 68 65 6e 20 6e 6f 20 64 65 6c 65 74 69  , then no deleti
d910: 6f 6e 20 6f 63 63 75 72 73 2e 0a 0a 3c 70 3e 54  on occurs...<p>T
d920: 68 65 20 61 72 67 76 5b 31 5d 20 70 61 72 61 6d  he argv[1] param
d930: 65 74 65 72 20 69 73 20 74 68 65 20 72 6f 77 69  eter is the rowi
d940: 64 20 6f 66 20 61 20 6e 65 77 20 72 6f 77 20 74  d of a new row t
d950: 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 0a 69  o be inserted .i
d960: 6e 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 20  nto the virtual 
d970: 74 61 62 6c 65 2e 20 49 66 20 61 72 67 76 5b 31  table. If argv[1
d980: 5d 20 69 73 20 61 6e 20 53 51 4c 20 4e 55 4c 4c  ] is an SQL NULL
d990: 2c 20 74 68 65 6e 20 74 68 65 20 69 6d 70 6c 65  , then the imple
d9a0: 6d 65 6e 74 61 74 69 6f 6e 20 0a 6d 75 73 74 20  mentation .must 
d9b0: 63 68 6f 6f 73 65 20 61 20 72 6f 77 69 64 20 66  choose a rowid f
d9c0: 6f 72 20 74 68 65 20 6e 65 77 6c 79 20 69 6e 73  or the newly ins
d9d0: 65 72 74 65 64 20 72 6f 77 2e 20 53 75 62 73 65  erted row. Subse
d9e0: 71 75 65 6e 74 20 61 72 67 76 5b 5d 20 0a 65 6e  quent argv[] .en
d9f0: 74 72 69 65 73 20 63 6f 6e 74 61 69 6e 20 76 61  tries contain va
da00: 6c 75 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75  lues of the colu
da10: 6d 6e 73 20 6f 66 20 74 68 65 20 76 69 72 74 75  mns of the virtu
da20: 61 6c 20 74 61 62 6c 65 2c 20 69 6e 20 74 68 65  al table, in the
da30: 20 0a 6f 72 64 65 72 20 74 68 61 74 20 74 68 65   .order that the
da40: 20 63 6f 6c 75 6d 6e 73 20 77 65 72 65 20 64 65   columns were de
da50: 63 6c 61 72 65 64 2e 20 54 68 65 20 6e 75 6d 62  clared. The numb
da60: 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 77 69  er of columns wi
da70: 6c 6c 0a 6d 61 74 63 68 20 74 68 65 20 74 61 62  ll.match the tab
da80: 6c 65 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74  le declaration t
da90: 68 61 74 20 74 68 65 20 3c 61 20 68 72 65 66 3d  hat the <a href=
daa0: 22 76 74 61 62 2e 68 74 6d 6c 23 78 63 6f 6e 6e  "vtab.html#xconn
dab0: 65 63 74 22 3e 78 43 6f 6e 6e 65 63 74 3c 2f 61  ect">xConnect</a
dac0: 3e 20 6f 72 20 3c 61 20 68 72 65 66 3d 22 76 74  > or <a href="vt
dad0: 61 62 2e 68 74 6d 6c 23 78 63 72 65 61 74 65 22  ab.html#xcreate"
dae0: 3e 78 43 72 65 61 74 65 3c 2f 61 3e 20 6d 65 74  >xCreate</a> met
daf0: 68 6f 64 20 6d 61 64 65 20 0a 75 73 69 6e 67 20  hod made .using 
db00: 74 68 65 20 3c 61 20 68 72 65 66 3d 22 63 33 72  the <a href="c3r
db10: 65 66 2f 64 65 63 6c 61 72 65 5f 76 74 61 62 2e  ef/declare_vtab.
db20: 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 64 65  html">sqlite3_de
db30: 63 6c 61 72 65 5f 76 74 61 62 28 29 3c 2f 61 3e  clare_vtab()</a>
db40: 20 63 61 6c 6c 2e 20 20 41 6c 6c 20 68 69 64 64   call.  All hidd
db50: 65 6e 20 63 6f 6c 75 6d 6e 73 20 61 72 65 20 69  en columns are i
db60: 6e 63 6c 75 64 65 64 2e 0a 0a 3c 70 3e 57 68 65  ncluded...<p>Whe
db70: 6e 20 64 6f 69 6e 67 20 61 6e 20 69 6e 73 65 72  n doing an inser
db80: 74 20 77 69 74 68 6f 75 74 20 61 20 72 6f 77 69  t without a rowi
db90: 64 20 28 61 72 67 63 3e 31 2c 20 61 72 67 76 5b  d (argc>1, argv[
dba0: 31 5d 20 69 73 20 61 6e 20 53 51 4c 20 4e 55 4c  1] is an SQL NUL
dbb0: 4c 29 2c 20 74 68 65 20 0a 69 6d 70 6c 65 6d 65  L), the .impleme
dbc0: 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 73 65 74  ntation must set
dbd0: 20 2a 70 52 6f 77 69 64 20 74 6f 20 74 68 65 20   *pRowid to the 
dbe0: 72 6f 77 69 64 20 6f 66 20 74 68 65 20 6e 65 77  rowid of the new
dbf0: 6c 79 20 69 6e 73 65 72 74 65 64 20 72 6f 77 3b  ly inserted row;
dc00: 20 0a 74 68 69 73 20 77 69 6c 6c 20 62 65 63 6f   .this will beco
dc10: 6d 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  me the value ret
dc20: 75 72 6e 65 64 20 62 79 20 74 68 65 20 3c 61 20  urned by the <a 
dc30: 68 72 65 66 3d 22 63 33 72 65 66 2f 6c 61 73 74  href="c3ref/last
dc40: 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 2e 68 74  _insert_rowid.ht
dc50: 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 6c 61 73 74  ml">sqlite3_last
dc60: 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 3c  _insert_rowid()<
dc70: 2f 61 3e 0a 66 75 6e 63 74 69 6f 6e 2e 20 53 65  /a>.function. Se
dc80: 74 74 69 6e 67 20 74 68 69 73 20 76 61 6c 75 65  tting this value
dc90: 20 69 6e 20 61 6c 6c 20 74 68 65 20 6f 74 68 65   in all the othe
dca0: 72 20 63 61 73 65 73 20 69 73 20 61 20 68 61 72  r cases is a har
dcb0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 3b 0a 74 68 65  mless no-op;.the
dcc0: 20 53 51 4c 69 74 65 20 65 6e 67 69 6e 65 20 69   SQLite engine i
dcd0: 67 6e 6f 72 65 73 20 74 68 65 20 2a 70 52 6f 77  gnores the *pRow
dce0: 69 64 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  id return value 
dcf0: 69 66 20 61 72 67 63 3d 3d 31 20 6f 72 20 0a 61  if argc==1 or .a
dd00: 72 67 76 5b 31 5d 20 69 73 20 6e 6f 74 20 61 6e  rgv[1] is not an
dd10: 20 53 51 4c 20 4e 55 4c 4c 2e 0a 0a 3c 70 3e 45   SQL NULL...<p>E
dd20: 61 63 68 20 63 61 6c 6c 20 74 6f 20 78 55 70 64  ach call to xUpd
dd30: 61 74 65 20 77 69 6c 6c 20 66 61 6c 6c 20 69 6e  ate will fall in
dd40: 74 6f 20 6f 6e 65 20 6f 66 20 63 61 73 65 73 20  to one of cases 
dd50: 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 4e 6f 74  shown below..Not
dd60: 20 74 68 61 74 20 72 65 66 65 72 65 6e 63 65 73   that references
dd70: 20 74 6f 20 3c 62 3e 61 72 67 76 26 23 39 31 3b   to <b>argv&#91;
dd80: 69 26 23 39 33 3c 2f 62 3e 20 6d 65 61 6e 20 74  i&#93</b> mean t
dd90: 68 65 20 53 51 4c 20 76 61 6c 75 65 0a 68 65 6c  he SQL value.hel
dda0: 64 20 77 69 74 68 69 6e 20 74 68 65 20 61 72 67  d within the arg
ddb0: 76 26 23 39 31 3b 69 26 23 39 33 3b 20 6f 62 6a  v&#91;i&#93; obj
ddc0: 65 63 74 2c 20 6e 6f 74 20 74 68 65 20 61 72 67  ect, not the arg
ddd0: 76 26 23 39 31 3b 69 26 23 39 33 3b 0a 6f 62 6a  v&#91;i&#93;.obj
dde0: 65 63 74 20 69 74 73 65 6c 66 2e 0a 0a 3c 62 6c  ect itself...<bl
ddf0: 6f 63 6b 71 75 6f 74 65 3e 0a 3c 64 6c 3e 0a 3c  ockquote>.<dl>.<
de00: 64 74 3e 3c 62 3e 61 72 67 63 20 3d 20 31 3c 2f  dt><b>argc = 1</
de10: 62 3e 0a 3c 64 64 3e 3c 70 3e 54 68 65 20 73 69  b>.<dd><p>The si
de20: 6e 67 6c 65 20 72 6f 77 20 77 69 74 68 20 72 6f  ngle row with ro
de30: 77 69 64 20 65 71 75 61 6c 20 74 6f 20 61 72 67  wid equal to arg
de40: 76 5b 30 5d 20 69 73 20 64 65 6c 65 74 65 64 2e  v[0] is deleted.
de50: 20 4e 6f 20 69 6e 73 65 72 74 20 6f 63 63 75 72   No insert occur
de60: 73 2e 0a 0a 3c 64 74 3e 3c 62 3e 61 72 67 63 20  s...<dt><b>argc 
de70: 3e 20 31 20 3c 62 72 3e 20 61 72 67 76 5b 30 5d  > 1 <br> argv[0]
de80: 20 3d 20 4e 55 4c 4c 3c 2f 62 3e 0a 3c 64 64 3e   = NULL</b>.<dd>
de90: 3c 70 3e 41 20 6e 65 77 20 72 6f 77 20 69 73 20  <p>A new row is 
dea0: 69 6e 73 65 72 74 65 64 20 77 69 74 68 20 61 20  inserted with a 
deb0: 72 6f 77 69 64 20 61 72 67 76 5b 31 5d 20 61 6e  rowid argv[1] an
dec0: 64 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 73 20  d column values 
ded0: 69 6e 0a 20 20 20 20 20 20 20 61 72 67 76 5b 32  in.       argv[2
dee0: 5d 20 61 6e 64 20 66 6f 6c 6c 6f 77 69 6e 67 2e  ] and following.
def0: 20 20 49 66 20 61 72 67 76 5b 31 5d 20 69 73 20    If argv[1] is 
df00: 61 6e 20 53 51 4c 20 4e 55 4c 4c 2c 0a 20 20 20  an SQL NULL,.   
df10: 20 20 20 20 74 68 65 20 61 20 6e 65 77 20 75 6e      the a new un
df20: 69 71 75 65 20 72 6f 77 69 64 20 69 73 20 67 65  ique rowid is ge
df30: 6e 65 72 61 74 65 64 20 61 75 74 6f 6d 61 74 69  nerated automati
df40: 63 61 6c 6c 79 2e 0a 0a 3c 64 74 3e 3c 62 3e 61  cally...<dt><b>a
df50: 72 67 63 20 3e 20 31 20 3c 62 72 3e 20 61 72 67  rgc > 1 <br> arg
df60: 76 5b 30 5d 20 26 6e 65 3b 20 4e 55 4c 4c 20 3c  v[0] &ne; NULL <
df70: 62 72 3e 20 61 72 67 76 5b 30 5d 20 3d 20 61 72  br> argv[0] = ar
df80: 67 76 5b 31 5d 3c 2f 62 3e 0a 3c 64 64 3e 3c 70  gv[1]</b>.<dd><p
df90: 3e 54 68 65 20 72 6f 77 20 77 69 74 68 20 72 6f  >The row with ro
dfa0: 77 69 64 20 61 72 67 76 5b 30 5d 20 69 73 20 75  wid argv[0] is u
dfb0: 70 64 61 74 65 64 20 77 69 74 68 20 6e 65 77 20  pdated with new 
dfc0: 76 61 6c 75 65 73 20 0a 20 20 20 20 20 20 20 69  values .       i
dfd0: 6e 20 61 72 67 76 5b 32 5d 20 61 6e 64 20 66 6f  n argv[2] and fo
dfe0: 6c 6c 6f 77 69 6e 67 20 70 61 72 61 6d 65 74 65  llowing paramete
dff0: 72 73 2e 0a 0a 3c 64 74 3e 3c 62 3e 61 72 67 63  rs...<dt><b>argc
e000: 20 3e 20 31 20 3c 62 72 3e 20 61 72 67 76 5b 30   > 1 <br> argv[0
e010: 5d 20 26 6e 65 3b 20 4e 55 4c 4c 20 3c 62 72 3e  ] &ne; NULL <br>
e020: 20 61 72 67 76 5b 30 5d 20 26 6e 65 3b 20 61 72   argv[0] &ne; ar
e030: 67 76 5b 31 5d 3c 2f 62 3e 0a 3c 64 64 3e 3c 70  gv[1]</b>.<dd><p
e040: 3e 20 54 68 65 20 72 6f 77 20 77 69 74 68 20 72  > The row with r
e050: 6f 77 69 64 20 61 72 67 76 5b 30 5d 20 69 73 20  owid argv[0] is 
e060: 75 70 64 61 74 65 64 20 77 69 74 68 20 72 6f 77  updated with row
e070: 69 64 20 61 72 67 76 5b 31 5d 20 0a 61 6e 64 20  id argv[1] .and 
e080: 6e 65 77 20 76 61 6c 75 65 73 20 69 6e 20 61 72  new values in ar
e090: 67 76 5b 32 5d 20 61 6e 64 20 66 6f 6c 6c 6f 77  gv[2] and follow
e0a0: 69 6e 67 20 70 61 72 61 6d 65 74 65 72 73 2e 20  ing parameters. 
e0b0: 54 68 69 73 20 77 69 6c 6c 20 6f 63 63 75 72 20  This will occur 
e0c0: 0a 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61  .when an SQL sta
e0d0: 74 65 6d 65 6e 74 20 75 70 64 61 74 65 73 20 61  tement updates a
e0e0: 20 72 6f 77 69 64 2c 20 61 73 20 69 6e 20 74 68   rowid, as in th
e0f0: 65 20 73 74 61 74 65 6d 65 6e 74 3a 0a 3c 62 6c  e statement:.<bl
e100: 6f 63 6b 71 75 6f 74 65 3e 0a 20 20 20 3c 61 20  ockquote>.   <a 
e110: 68 72 65 66 3d 22 6c 61 6e 67 5f 75 70 64 61 74  href="lang_updat
e120: 65 2e 68 74 6d 6c 22 3e 55 50 44 41 54 45 3c 2f  e.html">UPDATE</
e130: 61 3e 20 74 61 62 6c 65 20 53 45 54 20 72 6f 77  a> table SET row
e140: 69 64 3d 72 6f 77 69 64 2b 31 20 57 48 45 52 45  id=rowid+1 WHERE
e150: 20 2e 2e 2e 3b 20 0a 3c 2f 62 6c 6f 63 6b 71 75   ...; .</blockqu
e160: 6f 74 65 3e 0a 3c 2f 64 6c 3e 0a 3c 2f 62 6c 6f  ote>.</dl>.</blo
e170: 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68 65  ckquote>..<p>The
e180: 20 78 55 70 64 61 74 65 20 6d 65 74 68 6f 64 20   xUpdate method 
e190: 6d 75 73 74 20 72 65 74 75 72 6e 20 3c 61 20 68  must return <a h
e1a0: 72 65 66 3d 22 72 65 73 63 6f 64 65 2e 68 74 6d  ref="rescode.htm
e1b0: 6c 23 6f 6b 22 3e 53 51 4c 49 54 45 5f 4f 4b 3c  l#ok">SQLITE_OK<
e1c0: 2f 61 3e 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  /a> if and only 
e1d0: 69 66 20 69 74 20 69 73 0a 73 75 63 63 65 73 73  if it is.success
e1e0: 66 75 6c 2e 20 20 49 66 20 61 20 66 61 69 6c 75  ful.  If a failu
e1f0: 72 65 20 6f 63 63 75 72 73 2c 20 74 68 65 20 78  re occurs, the x
e200: 55 70 64 61 74 65 20 6d 75 73 74 20 72 65 74 75  Update must retu
e210: 72 6e 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  rn an appropriat
e220: 65 0a 3c 61 20 68 72 65 66 3d 22 72 65 73 63 6f  e.<a href="resco
e230: 64 65 2e 68 74 6d 6c 22 3e 65 72 72 6f 72 20 63  de.html">error c
e240: 6f 64 65 3c 2f 61 3e 2e 20 20 4f 6e 20 61 20 66  ode</a>.  On a f
e250: 61 69 6c 75 72 65 2c 20 74 68 65 20 70 56 54 61  ailure, the pVTa
e260: 62 2d 3e 7a 45 72 72 4d 73 67 20 65 6c 65 6d 65  b->zErrMsg eleme
e270: 6e 74 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c  nt may optionall
e280: 79 0a 62 65 20 72 65 70 6c 61 63 65 64 20 77 69  y.be replaced wi
e290: 74 68 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  th error message
e2a0: 20 74 65 78 74 20 73 74 6f 72 65 64 20 69 6e 20   text stored in 
e2b0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64  memory allocated
e2c0: 20 66 72 6f 6d 20 53 51 4c 69 74 65 20 0a 75 73   from SQLite .us
e2d0: 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 73 75  ing functions su
e2e0: 63 68 20 61 73 20 3c 61 20 68 72 65 66 3d 22 63  ch as <a href="c
e2f0: 33 72 65 66 2f 6d 70 72 69 6e 74 66 2e 68 74 6d  3ref/mprintf.htm
e300: 6c 22 3e 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  l">sqlite3_mprin
e310: 74 66 28 29 3c 2f 61 3e 20 6f 72 20 3c 61 20 68  tf()</a> or <a h
e320: 72 65 66 3d 22 63 33 72 65 66 2f 66 72 65 65 2e  ref="c3ref/free.
e330: 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 6d 61  html">sqlite3_ma
e340: 6c 6c 6f 63 28 29 3c 2f 61 3e 2e 0a 0a 3c 70 3e  lloc()</a>...<p>
e350: 49 66 20 74 68 65 20 78 55 70 64 61 74 65 20 6d  If the xUpdate m
e360: 65 74 68 6f 64 20 76 69 6f 6c 61 74 65 73 20 73  ethod violates s
e370: 6f 6d 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 6f  ome constraint o
e380: 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  f the virtual ta
e390: 62 6c 65 0a 28 69 6e 63 6c 75 64 69 6e 67 2c 20  ble.(including, 
e3a0: 62 75 74 20 6e 6f 74 20 6c 69 6d 69 74 65 64 20  but not limited 
e3b0: 74 6f 2c 20 61 74 74 65 6d 70 74 69 6e 67 20 74  to, attempting t
e3c0: 6f 20 73 74 6f 72 65 20 61 20 76 61 6c 75 65 20  o store a value 
e3d0: 6f 66 20 74 68 65 20 77 72 6f 6e 67 20 0a 64 61  of the wrong .da
e3e0: 74 61 74 79 70 65 2c 20 61 74 74 65 6d 70 74 69  tatype, attempti
e3f0: 6e 67 20 74 6f 20 73 74 6f 72 65 20 61 20 76 61  ng to store a va
e400: 6c 75 65 20 74 68 61 74 20 69 73 20 74 6f 6f 0a  lue that is too.
e410: 6c 61 72 67 65 20 6f 72 20 74 6f 6f 20 73 6d 61  large or too sma
e420: 6c 6c 2c 20 6f 72 20 61 74 74 65 6d 70 74 69 6e  ll, or attemptin
e430: 67 20 74 6f 20 63 68 61 6e 67 65 20 61 20 72 65  g to change a re
e440: 61 64 2d 6f 6e 6c 79 20 76 61 6c 75 65 29 20 74  ad-only value) t
e450: 68 65 6e 20 74 68 65 0a 78 55 70 64 61 74 65 20  hen the.xUpdate 
e460: 6d 75 73 74 20 66 61 69 6c 20 77 69 74 68 20 61  must fail with a
e470: 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 3c 61  n appropriate <a
e480: 20 68 72 65 66 3d 22 72 65 73 63 6f 64 65 2e 68   href="rescode.h
e490: 74 6d 6c 22 3e 65 72 72 6f 72 20 63 6f 64 65 3c  tml">error code<
e4a0: 2f 61 3e 2e 0a 0a 3c 70 3e 54 68 65 72 65 20 6d  /a>...<p>There m
e4b0: 69 67 68 74 20 62 65 20 6f 6e 65 20 6f 72 20 6d  ight be one or m
e4c0: 6f 72 65 20 3c 61 20 68 72 65 66 3d 22 63 33 72  ore <a href="c3r
e4d0: 65 66 2f 76 74 61 62 5f 63 75 72 73 6f 72 2e 68  ef/vtab_cursor.h
e4e0: 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 76 74 61  tml">sqlite3_vta
e4f0: 62 5f 63 75 72 73 6f 72 3c 2f 61 3e 20 6f 62 6a  b_cursor</a> obj
e500: 65 63 74 73 20 6f 70 65 6e 20 61 6e 64 20 69 6e  ects open and in
e510: 20 75 73 65 20 0a 6f 6e 20 74 68 65 20 76 69 72   use .on the vir
e520: 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 73 74 61  tual table insta
e530: 6e 63 65 20 61 6e 64 20 70 65 72 68 61 70 73 20  nce and perhaps 
e540: 65 76 65 6e 20 6f 6e 20 74 68 65 20 72 6f 77 20  even on the row 
e550: 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 0a 74  of the virtual.t
e560: 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20 78 55  able when the xU
e570: 70 64 61 74 65 20 6d 65 74 68 6f 64 20 69 73 20  pdate method is 
e580: 69 6e 76 6f 6b 65 64 2e 20 20 54 68 65 20 69 6d  invoked.  The im
e590: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 0a  plementation of.
e5a0: 78 55 70 64 61 74 65 20 6d 75 73 74 20 62 65 20  xUpdate must be 
e5b0: 70 72 65 70 61 72 65 64 20 66 6f 72 20 61 74 74  prepared for att
e5c0: 65 6d 70 74 73 20 74 6f 20 64 65 6c 65 74 65 20  empts to delete 
e5d0: 6f 72 20 6d 6f 64 69 66 79 20 72 6f 77 73 20 6f  or modify rows o
e5e0: 66 20 74 68 65 20 74 61 62 6c 65 0a 6f 75 74 20  f the table.out 
e5f0: 66 72 6f 6d 20 6f 74 68 65 72 20 65 78 69 73 74  from other exist
e600: 69 6e 67 20 63 75 72 73 6f 72 73 2e 20 20 49 66  ing cursors.  If
e610: 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
e620: 6c 65 20 63 61 6e 6e 6f 74 20 61 63 63 6f 6d 6d  le cannot accomm
e630: 6f 64 61 74 65 0a 73 75 63 68 20 63 68 61 6e 67  odate.such chang
e640: 65 73 2c 20 74 68 65 20 78 55 70 64 61 74 65 20  es, the xUpdate 
e650: 6d 65 74 68 6f 64 20 6d 75 73 74 20 72 65 74 75  method must retu
e660: 72 6e 20 61 6e 20 3c 61 20 68 72 65 66 3d 22 72  rn an <a href="r
e670: 65 73 63 6f 64 65 2e 68 74 6d 6c 22 3e 65 72 72  escode.html">err
e680: 6f 72 20 63 6f 64 65 3c 2f 61 3e 2e 0a 0a 3c 70  or code</a>...<p
e690: 3e 54 68 65 20 78 55 70 64 61 74 65 20 6d 65 74  >The xUpdate met
e6a0: 68 6f 64 20 69 73 20 6f 70 74 69 6f 6e 61 6c 2e  hod is optional.
e6b0: 0a 49 66 20 74 68 65 20 78 55 70 64 61 74 65 20  .If the xUpdate 
e6c0: 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 3c  pointer in the <
e6d0: 61 20 68 72 65 66 3d 22 63 33 72 65 66 2f 6d 6f  a href="c3ref/mo
e6e0: 64 75 6c 65 2e 68 74 6d 6c 22 3e 73 71 6c 69 74  dule.html">sqlit
e6f0: 65 33 5f 6d 6f 64 75 6c 65 3c 2f 61 3e 20 66 6f  e3_module</a> fo
e700: 72 20 61 20 76 69 72 74 75 61 6c 20 74 61 62 6c  r a virtual tabl
e710: 65 0a 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  e.is a NULL poin
e720: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 76 69  ter, then the vi
e730: 72 74 75 61 6c 20 74 61 62 6c 65 20 69 73 20 72  rtual table is r
e740: 65 61 64 2d 6f 6e 6c 79 2e 0a 0a 0a 3c 61 20 6e  ead-only....<a n
e750: 61 6d 65 3d 22 78 66 69 6e 64 66 75 6e 63 74 69  ame="xfindfuncti
e760: 6f 6e 22 3e 3c 2f 61 3e 0a 0a 3c 68 33 3e 32 2e  on"></a>..<h3>2.
e770: 31 34 20 54 68 65 20 78 46 69 6e 64 46 75 6e 63  14 The xFindFunc
e780: 74 69 6f 6e 20 4d 65 74 68 6f 64 3c 2f 68 33 3e  tion Method</h3>
e790: 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  ..<blockquote><p
e7a0: 72 65 3e 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e  re>.  int (*xFin
e7b0: 64 46 75 6e 63 74 69 6f 6e 29 28 0a 20 20 20 20  dFunction)(.    
e7c0: 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
e7d0: 74 61 62 2c 0a 20 20 20 20 69 6e 74 20 6e 41 72  tab,.    int nAr
e7e0: 67 2c 0a 20 20 20 20 63 6f 6e 73 74 20 63 68 61  g,.    const cha
e7f0: 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 76 6f  r *zName,.    vo
e800: 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71  id (**pxFunc)(sq
e810: 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
e820: 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
e830: 2a 2a 29 2c 0a 20 20 20 20 76 6f 69 64 20 2a 2a  **),.    void **
e840: 70 70 41 72 67 0a 20 20 29 3b 0a 3c 2f 70 72 65  ppArg.  );.</pre
e850: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a  ></blockquote>..
e860: 3c 70 3e 54 68 69 73 20 6d 65 74 68 6f 64 20 69  <p>This method i
e870: 73 20 63 61 6c 6c 65 64 20 64 75 72 69 6e 67 20  s called during 
e880: 3c 61 20 68 72 65 66 3d 22 63 33 72 65 66 2f 70  <a href="c3ref/p
e890: 72 65 70 61 72 65 2e 68 74 6d 6c 22 3e 73 71 6c  repare.html">sql
e8a0: 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 3c 2f  ite3_prepare()</
e8b0: 61 3e 20 74 6f 20 67 69 76 65 20 74 68 65 20 76  a> to give the v
e8c0: 69 72 74 75 61 6c 0a 74 61 62 6c 65 20 69 6d 70  irtual.table imp
e8d0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 20 6f  lementation an o
e8e0: 70 70 6f 72 74 75 6e 69 74 79 20 74 6f 20 6f 76  pportunity to ov
e8f0: 65 72 6c 6f 61 64 20 66 75 6e 63 74 69 6f 6e 73  erload functions
e900: 2e 20 0a 54 68 69 73 20 6d 65 74 68 6f 64 20 6d  . .This method m
e910: 61 79 20 62 65 20 73 65 74 20 74 6f 20 4e 55 4c  ay be set to NUL
e920: 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  L in which case 
e930: 6e 6f 20 6f 76 65 72 6c 6f 61 64 69 6e 67 20 6f  no overloading o
e940: 63 63 75 72 73 2e 0a 0a 3c 70 3e 57 68 65 6e 20  ccurs...<p>When 
e950: 61 20 66 75 6e 63 74 69 6f 6e 20 75 73 65 73 20  a function uses 
e960: 61 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 61 20  a column from a 
e970: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61 73  virtual table as
e980: 20 69 74 73 20 66 69 72 73 74 20 0a 61 72 67 75   its first .argu
e990: 6d 65 6e 74 2c 20 74 68 69 73 20 6d 65 74 68 6f  ment, this metho
e9a0: 64 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 73  d is called to s
e9b0: 65 65 20 69 66 20 74 68 65 20 76 69 72 74 75 61  ee if the virtua
e9c0: 6c 20 74 61 62 6c 65 20 77 6f 75 6c 64 20 0a 6c  l table would .l
e9d0: 69 6b 65 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  ike to overload 
e9e0: 74 68 65 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68  the function. Th
e9f0: 65 20 66 69 72 73 74 20 74 68 72 65 65 20 70 61  e first three pa
ea00: 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 70  rameters are inp
ea10: 75 74 73 3a 20 0a 74 68 65 20 76 69 72 74 75 61  uts: .the virtua
ea20: 6c 20 74 61 62 6c 65 2c 20 74 68 65 20 6e 75 6d  l table, the num
ea30: 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
ea40: 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   to the function
ea50: 2c 20 61 6e 64 20 74 68 65 20 0a 6e 61 6d 65 20  , and the .name 
ea60: 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2e  of the function.
ea70: 20 49 66 20 6e 6f 20 6f 76 65 72 6c 6f 61 64 69   If no overloadi
ea80: 6e 67 20 69 73 20 64 65 73 69 72 65 64 2c 20 74  ng is desired, t
ea90: 68 69 73 20 6d 65 74 68 6f 64 0a 72 65 74 75 72  his method.retur
eaa0: 6e 73 20 30 2e 20 54 6f 20 6f 76 65 72 6c 6f 61  ns 0. To overloa
eab0: 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20  d the function, 
eac0: 74 68 69 73 20 6d 65 74 68 6f 64 20 77 72 69 74  this method writ
ead0: 65 73 20 74 68 65 20 6e 65 77 20 0a 66 75 6e 63  es the new .func
eae0: 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
eaf0: 69 6f 6e 20 69 6e 74 6f 20 2a 70 78 46 75 6e 63  ion into *pxFunc
eb00: 20 61 6e 64 20 77 72 69 74 65 73 20 75 73 65 72   and writes user
eb10: 20 64 61 74 61 20 69 6e 74 6f 20 2a 70 70 41 72   data into *ppAr
eb20: 67 20 0a 61 6e 64 20 72 65 74 75 72 6e 73 20 31  g .and returns 1
eb30: 2e 0a 0a 3c 70 3e 4e 6f 74 65 20 74 68 61 74 20  ...<p>Note that 
eb40: 69 6e 66 69 78 20 66 75 6e 63 74 69 6f 6e 73 20  infix functions 
eb50: 28 3c 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f 65  (<a href="lang_e
eb60: 78 70 72 2e 68 74 6d 6c 23 6c 69 6b 65 22 3e 4c  xpr.html#like">L
eb70: 49 4b 45 3c 2f 61 3e 2c 20 3c 61 20 68 72 65 66  IKE</a>, <a href
eb80: 3d 22 6c 61 6e 67 5f 65 78 70 72 2e 68 74 6d 6c  ="lang_expr.html
eb90: 23 67 6c 6f 62 22 3e 47 4c 4f 42 3c 2f 61 3e 2c  #glob">GLOB</a>,
eba0: 20 3c 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f 65   <a href="lang_e
ebb0: 78 70 72 2e 68 74 6d 6c 23 72 65 67 65 78 70 22  xpr.html#regexp"
ebc0: 3e 52 45 47 45 58 50 3c 2f 61 3e 2c 20 61 6e 64  >REGEXP</a>, and
ebd0: 20 3c 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f 65   <a href="lang_e
ebe0: 78 70 72 2e 68 74 6d 6c 23 6d 61 74 63 68 22 3e  xpr.html#match">
ebf0: 4d 41 54 43 48 3c 2f 61 3e 29 20 72 65 76 65 72  MATCH</a>) rever
ec00: 73 65 20 0a 74 68 65 20 6f 72 64 65 72 20 6f 66  se .the order of
ec10: 20 74 68 65 69 72 20 61 72 67 75 6d 65 6e 74 73   their arguments
ec20: 2e 20 53 6f 20 22 6c 69 6b 65 28 41 2c 42 29 22  . So "like(A,B)"
ec30: 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
ec40: 6f 20 22 42 20 6c 69 6b 65 20 41 22 2e 20 0a 46  o "B like A". .F
ec50: 6f 72 20 74 68 65 20 66 6f 72 6d 20 22 42 20 6c  or the form "B l
ec60: 69 6b 65 20 41 22 20 74 68 65 20 42 20 74 65 72  ike A" the B ter
ec70: 6d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  m is considered 
ec80: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
ec90: 6e 74 20 0a 74 6f 20 74 68 65 20 66 75 6e 63 74  nt .to the funct
eca0: 69 6f 6e 2e 20 42 75 74 20 66 6f 72 20 22 6c 69  ion. But for "li
ecb0: 6b 65 28 41 2c 42 29 22 20 74 68 65 20 41 20 74  ke(A,B)" the A t
ecc0: 65 72 6d 20 69 73 20 63 6f 6e 73 69 64 65 72 65  erm is considere
ecd0: 64 20 74 68 65 20 0a 66 69 72 73 74 20 61 72 67  d the .first arg
ece0: 75 6d 65 6e 74 2e 0a 0a 3c 70 3e 54 68 65 20 66  ument...<p>The f
ecf0: 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
ed00: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
ed10: 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
ed20: 20 76 61 6c 69 64 20 66 6f 72 0a 74 68 65 20 6c   valid for.the l
ed30: 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20 3c  ifetime of the <
ed40: 61 20 68 72 65 66 3d 22 63 33 72 65 66 2f 76 74  a href="c3ref/vt
ed50: 61 62 2e 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33  ab.html">sqlite3
ed60: 5f 76 74 61 62 3c 2f 61 3e 20 6f 62 6a 65 63 74  _vtab</a> object
ed70: 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 66 69   given in the fi
ed80: 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 0a  rst parameter...
ed90: 3c 61 20 6e 61 6d 65 3d 22 78 42 65 67 69 6e 22  <a name="xBegin"
eda0: 3e 3c 2f 61 3e 0a 0a 3c 68 33 3e 32 2e 31 35 20  ></a>..<h3>2.15 
edb0: 54 68 65 20 78 42 65 67 69 6e 20 4d 65 74 68 6f  The xBegin Metho
edc0: 64 3c 2f 68 33 3e 0a 0a 3c 62 6c 6f 63 6b 71 75  d</h3>..<blockqu
edd0: 6f 74 65 3e 3c 70 72 65 3e 0a 20 20 69 6e 74 20  ote><pre>.  int 
ede0: 28 2a 78 42 65 67 69 6e 29 28 73 71 6c 69 74 65  (*xBegin)(sqlite
edf0: 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
ee00: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
ee10: 74 65 3e 0a 0a 3c 70 3e 54 68 69 73 20 6d 65 74  te>..<p>This met
ee20: 68 6f 64 20 62 65 67 69 6e 73 20 61 20 74 72 61  hod begins a tra
ee30: 6e 73 61 63 74 69 6f 6e 20 6f 6e 20 61 20 76 69  nsaction on a vi
ee40: 72 74 75 61 6c 20 74 61 62 6c 65 2e 0a 54 68 69  rtual table..Thi
ee50: 73 20 69 73 20 6d 65 74 68 6f 64 20 69 73 20 6f  s is method is o
ee60: 70 74 69 6f 6e 61 6c 2e 20 20 54 68 65 20 78 42  ptional.  The xB
ee70: 65 67 69 6e 20 70 6f 69 6e 74 65 72 20 6f 66 20  egin pointer of 
ee80: 3c 61 20 68 72 65 66 3d 22 63 33 72 65 66 2f 6d  <a href="c3ref/m
ee90: 6f 64 75 6c 65 2e 68 74 6d 6c 22 3e 73 71 6c 69  odule.html">sqli
eea0: 74 65 33 5f 6d 6f 64 75 6c 65 3c 2f 61 3e 0a 6d  te3_module</a>.m
eeb0: 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 0a 3c 70 3e  ay be NULL...<p>
eec0: 54 68 69 73 20 6d 65 74 68 6f 64 20 69 73 20 61  This method is a
eed0: 6c 77 61 79 73 20 66 6f 6c 6c 6f 77 65 64 20 62  lways followed b
eee0: 79 20 6f 6e 65 20 63 61 6c 6c 20 74 6f 20 65 69  y one call to ei
eef0: 74 68 65 72 20 74 68 65 0a 3c 61 20 68 72 65 66  ther the.<a href
ef00: 3d 22 76 74 61 62 2e 68 74 6d 6c 23 78 63 6f 6d  ="vtab.html#xcom
ef10: 6d 69 74 22 3e 78 43 6f 6d 6d 69 74 3c 2f 61 3e  mit">xCommit</a>
ef20: 20 6f 72 20 3c 61 20 68 72 65 66 3d 22 76 74 61   or <a href="vta
ef30: 62 2e 68 74 6d 6c 23 78 72 6f 6c 6c 62 61 63 6b  b.html#xrollback
ef40: 22 3e 78 52 6f 6c 6c 62 61 63 6b 3c 2f 61 3e 20  ">xRollback</a> 
ef50: 6d 65 74 68 6f 64 2e 20 20 56 69 72 74 75 61 6c  method.  Virtual
ef60: 20 74 61 62 6c 65 20 74 72 61 6e 73 61 63 74 69   table transacti
ef70: 6f 6e 73 20 64 6f 0a 6e 6f 74 20 6e 65 73 74 2c  ons do.not nest,
ef80: 20 73 6f 20 74 68 65 20 78 42 65 67 69 6e 20 6d   so the xBegin m
ef90: 65 74 68 6f 64 20 77 69 6c 6c 20 6e 6f 74 20 62  ethod will not b
efa0: 65 20 69 6e 76 6f 6b 65 64 20 6d 6f 72 65 20 74  e invoked more t
efb0: 68 61 6e 20 6f 6e 63 65 0a 6f 6e 20 61 20 73 69  han once.on a si
efc0: 6e 67 6c 65 20 76 69 72 74 75 61 6c 20 74 61 62  ngle virtual tab
efd0: 6c 65 0a 77 69 74 68 6f 75 74 20 61 6e 20 69 6e  le.without an in
efe0: 74 65 72 76 65 6e 69 6e 67 20 63 61 6c 6c 20 74  tervening call t
eff0: 6f 20 65 69 74 68 65 72 20 3c 61 20 68 72 65 66  o either <a href
f000: 3d 22 76 74 61 62 2e 68 74 6d 6c 23 78 63 6f 6d  ="vtab.html#xcom
f010: 6d 69 74 22 3e 78 43 6f 6d 6d 69 74 3c 2f 61 3e  mit">xCommit</a>
f020: 20 6f 72 20 3c 61 20 68 72 65 66 3d 22 76 74 61   or <a href="vta
f030: 62 2e 68 74 6d 6c 23 78 72 6f 6c 6c 62 61 63 6b  b.html#xrollback
f040: 22 3e 78 52 6f 6c 6c 62 61 63 6b 3c 2f 61 3e 2e  ">xRollback</a>.
f050: 0a 4d 75 6c 74 69 70 6c 65 20 63 61 6c 6c 73 20  .Multiple calls 
f060: 74 6f 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73  to other methods
f070: 20 63 61 6e 20 61 6e 64 20 6c 69 6b 65 6c 79 20   can and likely 
f080: 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e 20 62 65  will occur in be
f090: 74 77 65 65 6e 0a 74 68 65 20 78 42 65 67 69 6e  tween.the xBegin
f0a0: 20 61 6e 64 20 74 68 65 20 63 6f 72 72 65 73 70   and the corresp
f0b0: 6f 6e 64 69 6e 67 20 3c 61 20 68 72 65 66 3d 22  onding <a href="
f0c0: 76 74 61 62 2e 68 74 6d 6c 23 78 63 6f 6d 6d 69  vtab.html#xcommi
f0d0: 74 22 3e 78 43 6f 6d 6d 69 74 3c 2f 61 3e 20 6f  t">xCommit</a> o
f0e0: 72 20 3c 61 20 68 72 65 66 3d 22 76 74 61 62 2e  r <a href="vtab.
f0f0: 68 74 6d 6c 23 78 72 6f 6c 6c 62 61 63 6b 22 3e  html#xrollback">
f100: 78 52 6f 6c 6c 62 61 63 6b 3c 2f 61 3e 2e 0a 0a  xRollback</a>...
f110: 3c 61 20 6e 61 6d 65 3d 22 78 73 79 6e 63 22 3e  <a name="xsync">
f120: 3c 2f 61 3e 0a 0a 3c 68 33 3e 32 2e 31 36 20 54  </a>..<h3>2.16 T
f130: 68 65 20 78 53 79 6e 63 20 4d 65 74 68 6f 64 3c  he xSync Method<
f140: 2f 68 33 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74  /h3>..<blockquot
f150: 65 3e 3c 70 72 65 3e 0a 20 20 69 6e 74 20 28 2a  e><pre>.  int (*
f160: 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 76  xSync)(sqlite3_v
f170: 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 3c 2f 70  tab *pVTab);.</p
f180: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
f190: 0a 0a 0a 3c 70 3e 54 68 69 73 20 6d 65 74 68 6f  ...<p>This metho
f1a0: 64 20 73 69 67 6e 61 6c 73 20 74 68 65 20 73 74  d signals the st
f1b0: 61 72 74 20 6f 66 20 61 20 74 77 6f 2d 70 68 61  art of a two-pha
f1c0: 73 65 20 63 6f 6d 6d 69 74 20 6f 6e 20 61 20 76  se commit on a v
f1d0: 69 72 74 75 61 6c 0a 74 61 62 6c 65 2e 0a 54 68  irtual.table..Th
f1e0: 69 73 20 69 73 20 6d 65 74 68 6f 64 20 69 73 20  is is method is 
f1f0: 6f 70 74 69 6f 6e 61 6c 2e 20 20 54 68 65 20 78  optional.  The x
f200: 53 79 6e 63 20 70 6f 69 6e 74 65 72 20 6f 66 20  Sync pointer of 
f210: 3c 61 20 68 72 65 66 3d 22 63 33 72 65 66 2f 6d  <a href="c3ref/m
f220: 6f 64 75 6c 65 2e 68 74 6d 6c 22 3e 73 71 6c 69  odule.html">sqli
f230: 74 65 33 5f 6d 6f 64 75 6c 65 3c 2f 61 3e 0a 6d  te3_module</a>.m
f240: 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 0a 3c 70 3e  ay be NULL...<p>
f250: 54 68 69 73 20 6d 65 74 68 6f 64 20 69 73 20 6f  This method is o
f260: 6e 6c 79 20 69 6e 76 6f 6b 65 64 20 61 66 74 65  nly invoked afte
f270: 72 20 63 61 6c 6c 20 74 6f 20 74 68 65 20 3c 61  r call to the <a
f280: 20 68 72 65 66 3d 22 76 74 61 62 2e 68 74 6d 6c   href="vtab.html
f290: 23 78 42 65 67 69 6e 22 3e 78 42 65 67 69 6e 3c  #xBegin">xBegin<
f2a0: 2f 61 3e 20 6d 65 74 68 6f 64 20 61 6e 64 0a 70  /a> method and.p
f2b0: 72 69 6f 72 20 74 6f 20 61 6e 20 3c 61 20 68 72  rior to an <a hr
f2c0: 65 66 3d 22 76 74 61 62 2e 68 74 6d 6c 23 78 63  ef="vtab.html#xc
f2d0: 6f 6d 6d 69 74 22 3e 78 43 6f 6d 6d 69 74 3c 2f  ommit">xCommit</
f2e0: 61 3e 20 6f 72 20 3c 61 20 68 72 65 66 3d 22 76  a> or <a href="v
f2f0: 74 61 62 2e 68 74 6d 6c 23 78 72 6f 6c 6c 62 61  tab.html#xrollba
f300: 63 6b 22 3e 78 52 6f 6c 6c 62 61 63 6b 3c 2f 61  ck">xRollback</a
f310: 3e 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20  >.  In order to 
f320: 69 6d 70 6c 65 6d 65 6e 74 20 74 77 6f 2d 70 68  implement two-ph
f330: 61 73 65 0a 63 6f 6d 6d 69 74 2c 20 74 68 65 20  ase.commit, the 
f340: 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 6f 6e 20  xSync method on 
f350: 61 6c 6c 20 76 69 72 74 75 61 6c 20 74 61 62 6c  all virtual tabl
f360: 65 73 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 72  es is invoked pr
f370: 69 6f 72 20 74 6f 0a 69 6e 76 6f 6b 69 6e 67 20  ior to.invoking 
f380: 74 68 65 20 3c 61 20 68 72 65 66 3d 22 76 74 61  the <a href="vta
f390: 62 2e 68 74 6d 6c 23 78 63 6f 6d 6d 69 74 22 3e  b.html#xcommit">
f3a0: 78 43 6f 6d 6d 69 74 3c 2f 61 3e 20 6d 65 74 68  xCommit</a> meth
f3b0: 6f 64 20 6f 6e 20 61 6e 79 20 76 69 72 74 75 61  od on any virtua
f3c0: 6c 20 74 61 62 6c 65 2e 20 20 49 66 20 61 6e 79  l table.  If any
f3d0: 20 6f 66 20 74 68 65 20 0a 78 53 79 6e 63 20 6d   of the .xSync m
f3e0: 65 74 68 6f 64 73 20 66 61 69 6c 2c 20 74 68 65  ethods fail, the
f3f0: 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74   entire transact
f400: 69 6f 6e 20 69 73 20 72 6f 6c 6c 65 64 20 62 61  ion is rolled ba
f410: 63 6b 2e 0a 0a 3c 61 20 6e 61 6d 65 3d 22 78 63  ck...<a name="xc
f420: 6f 6d 6d 69 74 22 3e 3c 2f 61 3e 0a 0a 3c 68 33  ommit"></a>..<h3
f430: 3e 32 2e 31 37 20 54 68 65 20 78 43 6f 6d 6d 69  >2.17 The xCommi
f440: 74 20 4d 65 74 68 6f 64 3c 2f 68 33 3e 0a 0a 3c  t Method</h3>..<
f450: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
f460: 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74  .  int (*xCommit
f470: 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
f480: 70 56 54 61 62 29 3b 0a 3c 2f 70 72 65 3e 3c 2f  pVTab);.</pre></
f490: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e  blockquote>..<p>
f4a0: 54 68 69 73 20 6d 65 74 68 6f 64 20 63 61 75 73  This method caus
f4b0: 65 73 20 61 20 76 69 72 74 75 61 6c 20 74 61 62  es a virtual tab
f4c0: 6c 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  le transaction t
f4d0: 6f 20 63 6f 6d 6d 69 74 2e 0a 54 68 69 73 20 69  o commit..This i
f4e0: 73 20 6d 65 74 68 6f 64 20 69 73 20 6f 70 74 69  s method is opti
f4f0: 6f 6e 61 6c 2e 20 20 54 68 65 20 78 43 6f 6d 6d  onal.  The xComm
f500: 69 74 20 70 6f 69 6e 74 65 72 20 6f 66 20 3c 61  it pointer of <a
f510: 20 68 72 65 66 3d 22 63 33 72 65 66 2f 6d 6f 64   href="c3ref/mod
f520: 75 6c 65 2e 68 74 6d 6c 22 3e 73 71 6c 69 74 65  ule.html">sqlite
f530: 33 5f 6d 6f 64 75 6c 65 3c 2f 61 3e 0a 6d 61 79  3_module</a>.may
f540: 20 62 65 20 4e 55 4c 4c 2e 0a 0a 3c 70 3e 41 20   be NULL...<p>A 
f550: 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 6d 65 74  call to this met
f560: 68 6f 64 20 61 6c 77 61 79 73 20 66 6f 6c 6c 6f  hod always follo
f570: 77 73 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20  ws a prior call 
f580: 74 6f 20 3c 61 20 68 72 65 66 3d 22 76 74 61 62  to <a href="vtab
f590: 2e 68 74 6d 6c 23 78 42 65 67 69 6e 22 3e 78 42  .html#xBegin">xB
f5a0: 65 67 69 6e 3c 2f 61 3e 20 61 6e 64 0a 3c 61 20  egin</a> and.<a 
f5b0: 68 72 65 66 3d 22 76 74 61 62 2e 68 74 6d 6c 23  href="vtab.html#
f5c0: 78 73 79 6e 63 22 3e 78 53 79 6e 63 3c 2f 61 3e  xsync">xSync</a>
f5d0: 2e 0a 0a 0a 3c 61 20 6e 61 6d 65 3d 22 78 72 6f  ....<a name="xro
f5e0: 6c 6c 62 61 63 6b 22 3e 3c 2f 61 3e 0a 0a 3c 68  llback"></a>..<h
f5f0: 33 3e 32 2e 31 38 20 54 68 65 20 78 52 6f 6c 6c  3>2.18 The xRoll
f600: 62 61 63 6b 20 4d 65 74 68 6f 64 3c 2f 68 33 3e  back Method</h3>
f610: 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  ..<blockquote><p
f620: 72 65 3e 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c  re>.  int (*xRol
f630: 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76  lback)(sqlite3_v
f640: 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 3c 2f 70  tab *pVTab);.</p
f650: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
f660: 0a 0a 3c 70 3e 54 68 69 73 20 6d 65 74 68 6f 64  ..<p>This method
f670: 20 63 61 75 73 65 73 20 61 20 76 69 72 74 75 61   causes a virtua
f680: 6c 20 74 61 62 6c 65 20 74 72 61 6e 73 61 63 74  l table transact
f690: 69 6f 6e 20 74 6f 20 72 6f 6c 6c 62 61 63 6b 2e  ion to rollback.
f6a0: 0a 54 68 69 73 20 69 73 20 6d 65 74 68 6f 64 20  .This is method 
f6b0: 69 73 20 6f 70 74 69 6f 6e 61 6c 2e 20 20 54 68  is optional.  Th
f6c0: 65 20 78 52 6f 6c 6c 62 61 63 6b 20 70 6f 69 6e  e xRollback poin
f6d0: 74 65 72 20 6f 66 20 3c 61 20 68 72 65 66 3d 22  ter of <a href="
f6e0: 63 33 72 65 66 2f 6d 6f 64 75 6c 65 2e 68 74 6d  c3ref/module.htm
f6f0: 6c 22 3e 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  l">sqlite3_modul
f700: 65 3c 2f 61 3e 0a 6d 61 79 20 62 65 20 4e 55 4c  e</a>.may be NUL
f710: 4c 2e 0a 0a 3c 70 3e 41 20 63 61 6c 6c 20 74 6f  L...<p>A call to
f720: 20 74 68 69 73 20 6d 65 74 68 6f 64 20 61 6c 77   this method alw
f730: 61 79 73 20 66 6f 6c 6c 6f 77 73 20 61 20 70 72  ays follows a pr
f740: 69 6f 72 20 63 61 6c 6c 20 74 6f 20 3c 61 20 68  ior call to <a h
f750: 72 65 66 3d 22 76 74 61 62 2e 68 74 6d 6c 23 78  ref="vtab.html#x
f760: 42 65 67 69 6e 22 3e 78 42 65 67 69 6e 3c 2f 61  Begin">xBegin</a
f770: 3e 2e 0a 0a 0a 3c 61 20 6e 61 6d 65 3d 22 78 72  >....<a name="xr
f780: 65 6e 61 6d 65 22 3e 3c 2f 61 3e 0a 0a 3c 68 33  ename"></a>..<h3
f790: 3e 32 2e 31 39 20 54 68 65 20 78 52 65 6e 61 6d  >2.19 The xRenam
f7a0: 65 20 4d 65 74 68 6f 64 3c 2f 68 33 3e 0a 0a 3c  e Method</h3>..<
f7b0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
f7c0: 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65  .  int (*xRename
f7d0: 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
f7e0: 70 56 74 61 62 2c 20 63 6f 6e 73 74 20 63 68 61  pVtab, const cha
f7f0: 72 20 2a 7a 4e 65 77 29 3b 0a 3c 2f 70 72 65 3e  r *zNew);.</pre>
f800: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c  </blockquote>..<
f810: 70 3e 54 68 69 73 20 6d 65 74 68 6f 64 20 70 72  p>This method pr
f820: 6f 76 69 64 65 73 20 6e 6f 74 69 66 69 63 61 74  ovides notificat
f830: 69 6f 6e 20 74 68 61 74 20 74 68 65 20 76 69 72  ion that the vir
f840: 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65  tual table imple
f850: 6d 65 6e 74 61 74 69 6f 6e 0a 74 68 61 74 20 74  mentation.that t
f860: 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
f870: 20 77 69 6c 6c 20 62 65 20 67 69 76 65 6e 20 61   will be given a
f880: 20 6e 65 77 20 6e 61 6d 65 2e 20 0a 49 66 20 74   new name. .If t
f890: 68 69 73 20 6d 65 74 68 6f 64 20 72 65 74 75 72  his method retur
f8a0: 6e 73 20 3c 61 20 68 72 65 66 3d 22 72 65 73 63  ns <a href="resc
f8b0: 6f 64 65 2e 68 74 6d 6c 23 6f 6b 22 3e 53 51 4c  ode.html#ok">SQL
f8c0: 49 54 45 5f 4f 4b 3c 2f 61 3e 20 74 68 65 6e 20  ITE_OK</a> then 
f8d0: 53 51 4c 69 74 65 20 72 65 6e 61 6d 65 73 20 74  SQLite renames t
f8e0: 68 65 20 74 61 62 6c 65 2e 0a 49 66 20 74 68 69  he table..If thi
f8f0: 73 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  s method returns
f900: 20 61 6e 20 3c 61 20 68 72 65 66 3d 22 72 65 73   an <a href="res
f910: 63 6f 64 65 2e 68 74 6d 6c 22 3e 65 72 72 6f 72  code.html">error
f920: 20 63 6f 64 65 3c 2f 61 3e 20 74 68 65 6e 20 74   code</a> then t
f930: 68 65 20 72 65 6e 61 6d 69 6e 67 20 69 73 20 70  he renaming is p
f940: 72 65 76 65 6e 74 65 64 2e 0a 0a 3c 70 3e 54 68  revented...<p>Th
f950: 65 20 78 52 65 6e 61 6d 65 20 6d 65 74 68 6f 64  e xRename method
f960: 20 69 73 20 72 65 71 75 69 72 65 64 20 66 6f 72   is required for
f970: 20 65 76 65 72 79 20 76 69 72 74 75 61 6c 20 74   every virtual t
f980: 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
f990: 69 6f 6e 2e 0a 0a 3c 61 20 6e 61 6d 65 3d 22 78  ion...<a name="x
f9a0: 73 61 76 65 70 6f 69 6e 74 22 3e 3c 2f 61 3e 0a  savepoint"></a>.
f9b0: 0a 3c 68 33 3e 32 2e 32 30 20 54 68 65 20 78 53  .<h3>2.20 The xS
f9c0: 61 76 65 70 6f 69 6e 74 2c 20 78 52 65 6c 65 61  avepoint, xRelea
f9d0: 73 65 2c 20 61 6e 64 20 78 52 6f 6c 6c 62 61 63  se, and xRollbac
f9e0: 6b 54 6f 20 4d 65 74 68 6f 64 73 3c 2f 68 33 3e  kTo Methods</h3>
f9f0: 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  ..<blockquote><p
fa00: 72 65 3e 0a 20 20 69 6e 74 20 28 2a 78 53 61 76  re>.  int (*xSav
fa10: 65 70 6f 69 6e 74 29 28 73 71 6c 69 74 65 33 5f  epoint)(sqlite3_
fa20: 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74  vtab *pVtab, int
fa30: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 6c 65  );.  int (*xRele
fa40: 61 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ase)(sqlite3_vta
fa50: 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 29 3b 0a  b *pVtab, int);.
fa60: 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63    int (*xRollbac
fa70: 6b 54 6f 29 28 73 71 6c 69 74 65 33 5f 76 74 61  kTo)(sqlite3_vta
fa80: 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 29 3b 0a  b *pVtab, int);.
fa90: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
faa0: 74 65 3e 0a 0a 3c 70 3e 0a 54 68 65 73 65 20 6d  te>..<p>.These m
fab0: 65 74 68 6f 64 73 20 70 72 6f 76 69 64 65 20 74  ethods provide t
fac0: 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
fad0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
fae0: 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 20 74  an opportunity t
faf0: 6f 0a 69 6d 70 6c 65 6d 65 6e 74 20 6e 65 73 74  o.implement nest
fb00: 65 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 2e  ed transactions.
fb10: 20 20 54 68 65 79 20 61 72 65 20 61 6c 77 61 79    They are alway
fb20: 73 20 6f 70 74 69 6f 6e 61 6c 20 61 6e 64 20 77  s optional and w
fb30: 69 6c 6c 20 6f 6e 6c 79 20 62 65 0a 63 61 6c 6c  ill only be.call
fb40: 65 64 20 69 6e 20 53 51 4c 69 74 65 20 3c 61 20  ed in SQLite <a 
fb50: 68 72 65 66 3d 22 72 65 6c 65 61 73 65 6c 6f 67  href="releaselog
fb60: 2f 33 5f 37 5f 37 2e 68 74 6d 6c 22 3e 76 65 72  /3_7_7.html">ver
fb70: 73 69 6f 6e 20 33 2e 37 2e 37 3c 2f 61 3e 20 61  sion 3.7.7</a> a
fb80: 6e 64 20 6c 61 74 65 72 2e 0a 3c 2f 70 3e 0a 0a  nd later..</p>..
fb90: 3c 70 3e 0a 57 68 65 6e 20 78 53 61 76 65 70 6f  <p>.When xSavepo
fba0: 69 6e 74 28 58 2c 4e 29 20 69 73 20 69 6e 76 6f  int(X,N) is invo
fbb0: 6b 65 64 2c 20 74 68 61 74 20 69 73 20 61 20 73  ked, that is a s
fbc0: 69 67 6e 61 6c 20 74 6f 20 74 68 65 20 76 69 72  ignal to the vir
fbd0: 74 75 61 6c 20 74 61 62 6c 65 20 58 0a 74 68 61  tual table X.tha
fbe0: 74 20 69 74 20 73 68 6f 75 6c 64 20 73 61 76 65  t it should save
fbf0: 20 69 74 73 20 63 75 72 72 65 6e 74 20 73 74 61   its current sta
fc00: 74 65 20 61 73 20 73 61 76 65 70 6f 69 6e 74 20  te as savepoint 
fc10: 4e 2e 20 20 0a 41 20 73 75 62 73 65 71 75 65 6e  N.  .A subsequen
fc20: 74 20 63 61 6c 6c 0a 74 6f 20 78 52 6f 6c 6c 62  t call.to xRollb
fc30: 61 63 6b 54 6f 28 58 2c 52 29 20 6d 65 61 6e 73  ackTo(X,R) means
fc40: 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 20   that the state 
fc50: 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  of the virtual t
fc60: 61 62 6c 65 20 73 68 6f 75 6c 64 20 72 65 74 75  able should retu
fc70: 72 6e 0a 74 6f 20 77 68 61 74 20 69 74 20 77 61  rn.to what it wa
fc80: 73 20 77 68 65 6e 20 78 53 61 76 65 70 6f 69 6e  s when xSavepoin
fc90: 74 28 58 2c 52 29 20 77 61 73 20 6c 61 73 74 20  t(X,R) was last 
fca0: 63 61 6c 6c 65 64 2e 20 20 0a 54 68 65 20 63 61  called.  .The ca
fcb0: 6c 6c 0a 74 6f 20 78 52 6f 6c 6c 62 61 63 6b 54  ll.to xRollbackT
fcc0: 6f 28 58 2c 52 29 20 77 69 6c 6c 20 69 6e 76 61  o(X,R) will inva
fcd0: 6c 69 64 61 74 65 20 61 6c 6c 20 73 61 76 65 70  lidate all savep
fce0: 6f 69 6e 74 73 20 77 69 74 68 20 4e 3e 52 3b 20  oints with N>R; 
fcf0: 6e 6f 6e 65 20 6f 66 20 74 68 65 0a 69 6e 76 61  none of the.inva
fd00: 6c 69 64 65 64 20 73 61 76 65 70 6f 69 6e 74 73  lided savepoints
fd10: 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20   will be rolled 
fd20: 62 61 63 6b 20 6f 72 20 72 65 6c 65 61 73 65 64  back or released
fd30: 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 0a 62   without first.b
fd40: 65 69 6e 67 20 72 65 69 6e 69 74 69 61 6c 69 7a  eing reinitializ
fd50: 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20  ed by a call to 
fd60: 78 53 61 76 65 70 6f 69 6e 74 28 29 2e 20 20 0a  xSavepoint().  .
fd70: 41 20 63 61 6c 6c 20 74 6f 20 78 52 65 6c 65 61  A call to xRelea
fd80: 73 65 28 58 2c 4d 29 20 69 6e 76 61 6c 69 64 61  se(X,M) invalida
fd90: 74 65 73 20 61 6c 6c 20 73 61 76 65 70 6f 69 6e  tes all savepoin
fda0: 74 73 20 77 68 65 72 65 20 4e 3e 3d 4d 2e 0a 3c  ts where N>=M..<
fdb0: 2f 70 3e 0a 0a 3c 70 3e 0a 4e 6f 6e 65 20 6f 66  /p>..<p>.None of
fdc0: 20 74 68 65 20 78 53 61 76 65 70 6f 69 6e 74 28   the xSavepoint(
fdd0: 29 2c 20 78 52 65 6c 65 61 73 65 28 29 2c 20 6f  ), xRelease(), o
fde0: 72 20 78 52 6f 6c 6c 62 61 63 6b 54 6f 28 29 20  r xRollbackTo() 
fdf0: 6d 65 74 68 6f 64 73 20 77 69 6c 6c 20 65 76 65  methods will eve
fe00: 72 0a 62 65 20 63 61 6c 6c 65 64 20 65 78 63 65  r.be called exce
fe10: 70 74 20 69 6e 20 62 65 74 77 65 65 6e 20 63 61  pt in between ca
fe20: 6c 6c 73 20 74 6f 20 78 42 65 67 69 6e 28 29 20  lls to xBegin() 
fe30: 61 6e 64 20 0a 65 69 74 68 65 72 20 78 43 6f 6d  and .either xCom
fe40: 6d 69 74 28 29 20 6f 72 20 78 52 6f 6c 6c 62 61  mit() or xRollba
fe50: 63 6b 28 29 2e 0a 3c 2f 70 3e 0a 0a              ck()..</p>..